API: slider YAHOO.widget.Slider (YUI Library)

# Yahoo! UI Library

### Slider Widget 2.8.1

Yahoo! UI Library > slider > YAHOO.widget.Slider
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.widget.Slider - extends YAHOO.util.DragDrop - uses YAHOO.util.EventProvider

A DragDrop implementation that can be used as a background for a slider. It takes a reference to the thumb instance so it can delegate some of the events to it. The goal is to make the thumb jump to the location on the background when the background is clicked.

### Constructor

YAHOO.widget.Slider `( id , sGroup , oThumb , sType )`

Parameters:
  `id <String>` The id of the element linked to this instance
  `sGroup <String>` The group of related DragDrop items
  `oThumb <SliderThumb>` The thumb for this slider
  `sType <String>` The type of slider (horiz, vert, region)

### Properties

#### _mouseDown - `private boolean`

Tracks the state of the mouse button to aid in when events are fired.
Default Value: false

#### _silent - `private boolean`

Indicates whether or not events will be supressed for the current slide operation

#### animate - `boolean`

Flag that determines if the thumb will animate when moved

#### animationDuration - `int`

If animation is configured, specifies the length of the animation in seconds.
Default Value: 0.2

#### backgroundEnabled - `boolean`

Set to false to disable a background click thumb move

#### baselinePos - `[int, int]`

The basline position of the background element, used to determine if the background has moved since the last operation.

#### dragOnly - `boolean`

Override the default setting of dragOnly to true.
Default Value: true

#### enableKeys - `boolean`

Enables the arrow, home and end keys, defaults to true.

#### isTarget - `private object`

Overrides the isTarget property in YAHOO.util.DragDrop

#### keyIncrement - `int`

Specifies the number of pixels the arrow keys will move the slider. Default is 20.

#### lastOffset - `[int, int]`

Saved offset used to protect against NaN problems when slider is set to display:none

#### moveComplete - `Boolean`

moveComplete is set to true when the slider has moved to its final destination. For animated slider, this value can be checked in the onChange handler to make it possible to execute logic only when the move is complete rather than at all points along the way. Deprecated because this flag is only useful when the background is clicked and the slider is animated. If the user drags the thumb, the flag is updated when the drag is over ... the final onDrag event fires before the mouseup the ends the drag, so the implementer will never see it.
Deprecated: use the slideEnd event instead

#### Slider.ANIM_AVAIL - `static boolean`

By default, animation is available if the animation utility is detected.

#### Slider.SOURCE_KEY_EVENT - `static final object`

Constant for valueChangeSource, indicating that the value was altered by hitting any of the supported keyboard characters.
Default Value: 2

#### Slider.SOURCE_SET_VALUE - `static final object`

Constant for valueChangeSource, indicating that the value was altered by a programmatic call to setValue/setRegionValue.
Default Value: 2

#### Slider.SOURCE_UI_EVENT - `static final object`

Constant for valueChangeSource, indicating that the user clicked or dragged the slider to change the value.
Default Value: 1

#### SOURCE_SET_VALUE - `final object`

Constant for valueChangeSource, indicating that the value was altered by a programmatic call to setValue/setRegionValue.
Default Value: 2
Deprecated: use static Slider.SOURCE_SET_VALUE

#### SOURCE_UI_EVENT - `final object`

Constant for valueChangeSource, indicating that the user clicked or dragged the slider to change the value.
Default Value: 1
Deprecated: use static Slider.SOURCE_UI_EVENT

#### thumb - `YAHOO.widget.SliderThumb`

A YAHOO.widget.SliderThumb instance that we will use to reposition the thumb when the background is clicked

#### thumbCenterPoint - `{"x": int, "y": int}`

The center of the slider element is stored so we can place it in the correct position when the background is clicked.

#### tickPause - `int`

Adjustment factor for tick animation, the more ticks, the faster the animation (by default)

#### type - `string`

The type of the slider (horiz, vert, region)

#### valueChangeSource - `int`

When the slider value changes, this property is set to identify where the update came from. This will be either 1, meaning the slider was clicked or dragged, or 2, meaning that it was set via a setValue() call. This can be used within event handlers to apply some of the logic only when dealing with one source or another.

#### Properties inherited from YAHOO.util.DragDrop:

`__ygDragDrop, _domRef, available, config, constrainX, constrainY, cursorIsOver, deltaX, deltaY, dragElId, dragOnly, events, groups, handleElId, hasOuterHandles, id, invalidHandleClasses, invalidHandleIds, invalidHandleTypes, isTarget, locked, maintainOffset, maxX, maxY, minX, minY, overlap, padding, primaryButtonOnly, startPageX, startPageY, useShim, xTicks, yTicks`

#### Properties inherited from YAHOO.util.EventProvider:

`__yui_events, __yui_subscribers`

### Methods

#### _bindKeyEvents

`protected void _bindKeyEvents ( )`
Sets up the listeners for keydown and key press events.

#### _getNextX

`private void _getNextX ( )`
Returns the next X tick value based on the current coord and the target coord.

#### _getNextY

`private void _getNextY ( )`
Returns the next Y tick value based on the current coord and the target coord.

#### _setRegionValue

`protected boolean _setRegionValue ( source , newOffset , newOffset2 , skipAnim , force , silent )`
Worker function to execute the value set operation. Accepts type of set operation in addition to the usual setValue params.

Parameters:
  `source <int>` what triggered the set (e.g. Slider.SOURCE_SET_VALUE)
  `newOffset <int>` the number of pixels the thumb should be positioned away from the initial start point (x axis for region)
  `newOffset2 <int>` the number of pixels the thumb should be positioned away from the initial start point (y axis for region)
  `skipAnim <boolean>` set to true to disable the animation for this move action (but not others).
  `force <boolean>` ignore the locked setting and set value anyway
  `silent <boolean>` when true, do not fire events

Returns: `boolean`
  true if the move was performed, false if it failed

#### _setValue

`protected boolean _setValue ( source , newOffset , skipAnim , force , silent )`
Worker function to execute the value set operation. Accepts type of set operation in addition to the usual setValue params.

Parameters:
  `source <int>` what triggered the set (e.g. Slider.SOURCE_SET_VALUE)
  `newOffset <int>` the number of pixels the thumb should be positioned away from the initial start point
  `skipAnim <boolean>` set to true to disable the animation for this move action (but not others).
  `force <boolean>` ignore the locked setting and set value anyway
  `silent <boolean>` when true, do not fire events

Returns: `boolean`
  true if the move was performed, false if it failed

#### b4MouseDown

`private void b4MouseDown ( )`
Resets the constraints before moving the thumb.

#### endMove

`private void endMove ( )`
Fired when the slider movement ends

#### fireEvents

`private void fireEvents ( thumbEvent )`
Fires the change event if the value has been changed. Ignored if we are in the middle of an animation as the event will fire when the animation is complete

Parameters:
  `thumbEvent <boolean>` set to true if this event is fired from an event that occurred on the thumb. If it is, the state of the thumb dd object should be correct. Otherwise, the event originated on the background, so the thumb state needs to be refreshed before proceeding.

#### focus

`private void focus ( )`
Try to focus the element when clicked so we can add accessibility features

#### getThumb

`SliderThumb getThumb ( )`
Returns a reference to this slider's thumb

Returns: `SliderThumb`
  this slider's thumb

#### getValue

`int getValue ( )`
Returns the slider's thumb offset from the start position

Returns: `int`
  the current value

#### getXValue

`int getXValue ( )`
Returns the slider's thumb X offset from the start position

Returns: `int`
  the current horizontal offset

#### getYValue

`int getYValue ( )`
Returns the slider's thumb Y offset from the start position

Returns: `int`
  the current vertical offset

#### handleKeyDown

`void handleKeyDown ( e )`
Executed when a keydown event happens with the control focused. Updates the slider value and display when the keypress is an arrow key, home, or end as long as enableKeys is set to true.

Parameters:
  `e <Event>` the keydown event

#### handleKeyPress

`void handleKeyPress ( e )`
Executed when a keypress event happens with the control focused. Prevents the default behavior for navigation keys. The actual logic for moving the slider thumb in response to a key event happens in handleKeyDown.

Parameters:
  `e <Event>` the keypress event

#### initSlider

`void initSlider ( sType )`
Initializes the slider. Executed in the constructor

Parameters:
  `sType <string>` the type of slider (horiz, vert, region)

#### initThumb

`void initThumb ( t )`
Initializes the slider's thumb. Executed in the constructor.

Parameters:
  `t <YAHOO.widget.SliderThumb>` the slider thumb

#### lock

`void lock ( )`
Locks the slider, overrides YAHOO.util.DragDrop

#### moveOneTick

`private void moveOneTick ( the )`
Move the slider one tick mark towards its final coordinate. Used for the animation when tick marks are defined

Parameters:
  `the <int[]>` destination coordinate

#### moveThumb

`private void moveThumb ( x , y , skipAnim , midMove )`
Move the associated slider moved to a timeout to try to get around the mousedown stealing moz does when I move the slider element between the cursor and the background during the mouseup event

Parameters:
  `x <int>` the X coordinate of the click
  `y <int>` the Y coordinate of the click
  `skipAnim <boolean>` don't animate if the move happend onDrag
  `midMove <boolean>` set to true if this is not terminating the slider movement

#### onAvailable

`void onAvailable ( )`
Executed when the slider element is available

#### onChange

`void onChange ( firstOffset , secondOffset )`
Event that fires when the value of the slider has changed

Parameters:
  `firstOffset <int>` the number of pixels the thumb has moved from its start position. Normal horizontal and vertical sliders will only have the firstOffset. Regions will have both, the first is the horizontal offset, the second the vertical.
  `secondOffset <int>` the y offset for region sliders

Deprecated use instance.subscribe("change") instead

#### onDrag

`private void onDrag ( )`
Handles the onDrag event for the slider background

#### onMouseDown

`private void onMouseDown ( )`
Handles the mousedown event for the slider background

#### onSliderEnd

`void onSliderEnd ( )`
Event that fires at the end of a slider thumb move
Deprecated use instance.subscribe("slideEnd") instead

#### onSlideStart

`void onSlideStart ( )`
Event that fires when the at the beginning of the slider thumb move
Deprecated use instance.subscribe("slideStart") instead

#### resetThumbConstraints

`protected void resetThumbConstraints ( )`
Resets the X and Y contraints for the thumb. Used in lieu of the thumb instance's inherited resetConstraints because some logic was not applicable.

#### setRegionValue

`boolean setRegionValue ( newOffset , newOffset2 , skipAnim , force , silent )`
Provides a way to set the value of the region slider in code.

Parameters:
  `newOffset <int>` the number of pixels the thumb should be positioned away from the initial start point (x axis for region)
  `newOffset2 <int>` the number of pixels the thumb should be positioned away from the initial start point (y axis for region)
  `skipAnim <boolean>` set to true to disable the animation for this move action (but not others).
  `force <boolean>` ignore the locked setting and set value anyway
  `silent <boolean>` when true, do not fire events

Returns: `boolean`
  true if the move was performed, false if it failed

#### setStartSliderState

`void setStartSliderState ( )`
Initialization that sets up the value offsets once the elements are ready

#### setThumbCenterPoint

`void setThumbCenterPoint ( )`
When the thumb is available, we cache the centerpoint of the element so we can position the element correctly when the background is clicked

#### setValue

`boolean setValue ( newOffset , skipAnim , force , silent )`
Provides a way to set the value of the slider in code.

Parameters:
  `newOffset <int>` the number of pixels the thumb should be positioned away from the initial start point
  `skipAnim <boolean>` set to true to disable the animation for this move action (but not others).
  `force <boolean>` ignore the locked setting and set value anyway
  `silent <boolean>` when true, do not fire events

Returns: `boolean`
  true if the move was performed, false if it failed

#### thumbMouseUp

`private void thumbMouseUp ( )`
Handles mouseup event on the thumb

#### toString

`string toString ( )`
Slider toString

Returns: `string`
  string representation of the instance

#### unlock

`void unlock ( )`
Unlocks the slider, overrides YAHOO.util.DragDrop

#### verifyOffset

`boolean verifyOffset ( )`
Checks the background position element position. If it has moved from the baseline position, the constraints for the thumb are reset

Returns: `boolean`
  True if the offset is the same as the baseline.

#### YAHOO.widget.Slider.getHorizDualSlider

`static DualSlider YAHOO.widget.Slider.getHorizDualSlider ( bg , minthumb , maxthumb , range , iTickSize , initVals )`
Factory method for creating a horizontal dual-thumb slider

Parameters:
  `bg <String>` the id of the slider's background element
  `minthumb <String>` the id of the min thumb
  `maxthumb <String>` the id of the thumb thumb
  `range <int>` the number of pixels the thumbs can move within
  `iTickSize <int>` (optional) the element should move this many pixels at a time
  `initVals <Array>` (optional) [min,max] Initial thumb placement

Returns: `DualSlider`
  a horizontal dual-thumb slider control

#### YAHOO.widget.Slider.getHorizSlider

`static Slider YAHOO.widget.Slider.getHorizSlider ( sBGElId , sHandleElId , iLeft , iRight , iTickSize )`
Factory method for creating a horizontal slider

Parameters:
  `sBGElId <String>` the id of the slider's background element
  `sHandleElId <String>` the id of the thumb element
  `iLeft <int>` the number of pixels the element can move left
  `iRight <int>` the number of pixels the element can move right
  `iTickSize <int>` optional parameter for specifying that the element should move a certain number pixels at a time.

Returns: `Slider`
  a horizontal slider control

#### YAHOO.widget.Slider.getSliderRegion

`static Slider YAHOO.widget.Slider.getSliderRegion ( sBGElId , sHandleElId , iLeft , iRight , iUp , iDown , iTickSize )`
Factory method for creating a slider region like the one in the color picker example

Parameters:
  `sBGElId <String>` the id of the slider's background element
  `sHandleElId <String>` the id of the thumb element
  `iLeft <int>` the number of pixels the element can move left
  `iRight <int>` the number of pixels the element can move right
  `iUp <int>` the number of pixels the element can move up
  `iDown <int>` the number of pixels the element can move down
  `iTickSize <int>` optional parameter for specifying that the element should move a certain number pixels at a time.

Returns: `Slider`
  a slider region control

#### YAHOO.widget.Slider.getVertDualSlider

`static DualSlider YAHOO.widget.Slider.getVertDualSlider ( bg , minthumb , maxthumb , range , iTickSize , initVals )`
Factory method for creating a vertical dual-thumb slider.

Parameters:
  `bg <String>` the id of the slider's background element
  `minthumb <String>` the id of the min thumb
  `maxthumb <String>` the id of the thumb thumb
  `range <int>` the number of pixels the thumbs can move within
  `iTickSize <int>` (optional) the element should move this many pixels at a time
  `initVals <Array>` (optional) [min,max] Initial thumb placement

Returns: `DualSlider`
  a vertical dual-thumb slider control

#### YAHOO.widget.Slider.getVertSlider

`static Slider YAHOO.widget.Slider.getVertSlider ( sBGElId , sHandleElId , iUp , iDown , iTickSize )`
Factory method for creating a vertical slider

Parameters:
  `sBGElId <String>` the id of the slider's background element
  `sHandleElId <String>` the id of the thumb element
  `iUp <int>` the number of pixels the element can move up
  `iDown <int>` the number of pixels the element can move down
  `iTickSize <int>` optional parameter for specifying that the element should move a certain number pixels at a time.

Returns: `Slider`
  a vertical slider control

#### Methods inherited from YAHOO.util.DragDrop:

`addInvalidHandleClass, addInvalidHandleId, addInvalidHandleType, addToGroup, applyConfig, b4Drag, b4DragDrop, b4DragOut, b4DragOver, b4EndDrag, b4MouseDown, b4StartDrag, clearConstraints, clearTicks, clickValidator, endDrag, getDragEl, getEl, getTargetCoord, getTick, handleMouseDown, handleOnAvailable, init, initTarget, isLocked, isValidHandleChild, lock, on, onAvailable, onDrag, onDragDrop, onDragEnter, onDragOut, onDragOver, onInvalidDrop, onMouseDown, onMouseUp, removeFromGroup, removeInvalidHandleClass, removeInvalidHandleId, removeInvalidHandleType, resetConstraints, setDragElId, setHandleElId, setInitialPosition, setOuterHandleElId, setPadding, setStartPosition, setXConstraint, setXTicks, setYConstraint, setYTicks, startDrag, toString, unlock, unreg`

#### Methods inherited from YAHOO.util.EventProvider:

`createEvent, fireEvent, hasEvent, subscribe, unsubscribe, unsubscribeAll`

### Events

#### change

`change ( newOffset|x , y )`
Event the fires when the value of the control changes. If the control is animated the event will fire every point along the way.

Parameters:
  `newOffset|x <int>` the new offset for normal sliders, or the new x offset for region sliders
  `y <int>` the number of pixels the thumb has moved on the y axis (region sliders only)

#### slideEnd

`slideEnd ( )`
Event that fires at the end of a slider thumb move

#### slideStart

`slideStart ( )`
Event that fires at the beginning of a slider thumb move.

#### Events inherited from YAHOO.util.DragDrop:

`b4DragDropEvent, b4DragEvent, b4DragOutEvent, b4DragOverEvent, b4EndDragEvent, b4MouseDownEvent, b4StartDragEvent, dragDropEvent, dragEnterEvent, dragEvent, dragOutEvent, dragOverEvent, endDragEvent, invalidDropEvent, mouseDownEvent, mouseUpEvent, startDragEvent,`

Copyright © 2010 Yahoo! Inc. All rights reserved.