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

# Yahoo! UI Library

### Slider Widget 2.2.2

Yahoo! UI Library > slider > YAHOO.widget.Slider

## 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

#### 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.

#### 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 25.

#### 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

#### 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)

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

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

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

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

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

`__yui_events, __yui_subscribers`

### Methods

#### _getNextX

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

Returns: `void`

#### _getNextY

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

Returns: `void`

#### b4MouseDown

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

Returns: `void`

#### endMove

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

Returns: `void`

#### 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.

Returns: `void`

#### focus

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

Returns: `void`

#### 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

Returns: `void`

#### 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

Returns: `void`

#### handleThumbChange

`private void handleThumbChange ( )`
Internal handler for the slider thumb's onChange event

Returns: `void`

#### initSlider

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

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

Returns: `void`

#### initThumb

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

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

Returns: `void`

#### lock

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

Returns: `void`

#### 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

Returns: `void`

#### moveThumb

`private void moveThumb ( x , y , skipAnim )`
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

Returns: `void`

#### onAvailable

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

Returns: `void`

#### 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

Returns: `void`

Deprecated use instance.subscribe("change") instead

#### onDrag

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

Returns: `void`

#### onMouseDown

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

Returns: `void`

#### onSliderEnd

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

Returns: `void`

Deprecated use instance.subscribe("slideEnd") instead

#### onSlideStart

`void onSlideStart ( )`
Event that fires when the at the beginning of the slider thumb move

Returns: `void`

Deprecated use instance.subscribe("slideStart") instead

#### setRegionValue

`boolean setRegionValue ( newOffset , newOffset2 , skipAnim , force )`
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

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

Returns: `void`

#### 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

Returns: `void`

#### setValue

`boolean setValue ( newOffset , skipAnim , force )`
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

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

#### thumbMouseUp

`private void thumbMouseUp ( )`
Handles mouseup event on the slider background

Returns: `void`

#### toString

`string toString ( )`
Slider toString

Returns: `string`
  string representation of the instance

#### unlock

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

Returns: `void`

#### verifyOffset

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

Parameters:
  `checkPos <boolean>` check the position instead of using cached value

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

#### 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.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, endDrag, getDragEl, getEl, getTargetCoord, getTick, handleMouseDown, handleOnAvailable, init, initTarget, isLocked, isTarget, isValidHandleChild, lock, onAvailable, onDrag, onDragDrop, onDragEnter, onDragOut, onDragOver, onInvalidDrop, onMouseDown, onMouseUp, padding, 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.

Copyright © 2007 Yahoo! Inc. All rights reserved.