# Titanium.UI.Slider

A slider component with a draggable thumb.

Availability

0.8

9.2.0

Extends

Titanium.UI.View

# Overview

Android	iOS	Windows

A slider lets the user select from a range of values by dragging the slider thumb.

Use the Titanium.UI.createSlider method or <Slider> Alloy element to create a slider.

# Android Platform Implementation Notes

On Android, the user can also maniuplate the slider using the arrow keys. For this reason, placing other focusable UI elements to the left or right of the slider is not recommended.

On Android, both min and max must be specified for the slider to work properly.

Earlier versions of the Titanium SDK implicitly enforced that both the Titanium.UI.Slider.leftTrackImage and Titanium.UI.Slider.rightTrackImage properties be specified before the properties would be honored. Beginning with Titanium SDK 4.0.0 this limitation has been removed. However it is recommended that either both or neither be specified.

# Examples

# Simple Slider

The following sample demonstrates creating a slider and adding a listener to handle the change events.

var slider = Titanium.UI.createSlider({
    top: 50,
    min: 0,
    max: 100,
    width: Ti.UI.FILL,
    value: 50
    });

var label = Ti.UI.createLabel({
    text: slider.value,
    width: Ti.UI.FILL,
    top: 30,
    left: 0,
    textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER
});

slider.addEventListener('change', function(e) {
    label.text = String.format('%3.1f', e.value);
});

# Alloy XML Markup

Previous example as an Alloy view.

Implement the updateLabel callback in the controller to update the label value and set the initial text value for the label in the TSS file or controller.

index.xml:

<Alloy>
    <Window id="window" backgroundColor="white">
        <Slider id="slider" top="50" min="0" max="100" width="Ti.UI.FILL" value="50" onChange="updateLabel"/>
        <Label id="label" width="Ti.UI.FILL" top="30" left="0" />
    </Window>
</Alloy>

index.js:

$.slider.text = $.slider.value;
function updateLabel(e) {
    $.label.text = String.format('%3.1f', e.value);
}
$.window.open();

# Properties

# disabledLeftTrackImage

Availability

0.8

9.2.0

disabledLeftTrackImage :String

Image URL of the slider left track when in the disabled state.

# disabledRightTrackImage

Availability

0.8

9.2.0

disabledRightTrackImage :String

Image URL of the slider right track when in the disabled state.

# disabledThumbImage

Availability

0.8

9.2.0

disabledThumbImage :String

Image URL of the slider thumb when in the disabled state.

# enabled

Availability

0.8

9.2.0

enabled :Boolean

Boolean to indicate the enabled state of the slider.

Default: Slider is enabled by default (property value may be `undefined`).

# highlightedLeftTrackImage

Availability

0.8

9.2.0

highlightedLeftTrackImage :String

Image URL of the slider left track when in the highlighted state.

# highlightedRightTrackImage

Availability

0.8

9.2.0

highlightedRightTrackImage :String

Image URL of the slider right track when in the highlighted state.

# highlightedThumbImage

Availability

0.8

9.2.0

highlightedThumbImage :String

Image URL of the slider thumb when in the highlighted state.

# leftTrackImage

Availability

0.8

9.2.0

leftTrackImage :String

Image URL of the slider left track.

See introduction of the Titanium.UI.Slider component for implementation specific information on Android Platform.

# leftTrackLeftCap

Availability

3.0.0

9.2.0

leftTrackLeftCap :Number

Size of the left end cap for the leftTrackImage, disabledLeftTrackImage, highlightedLeftTrackImage and selectedLeftTrackImage properties.

This property must be set before the track images are loaded. When specified at creation this property is loaded before loading any of the track images

End caps specify the portion of an image that should not be resized when an image is stretched. This technique is used to implement buttons and other resizable image-based interface elements. When an image with end caps is resized, the resizing occurs only in the middle of the image, in the region between the end caps. The end caps themselves keep their original size and appearance. This property specifies the size of the left end cap.

Default: 1

# leftTrackTopCap

Availability

3.0.0

9.2.0

leftTrackTopCap :Number

Size of the top end cap for the leftTrackImage, disabledLeftTrackImage, highlightedLeftTrackImage and selectedLeftTrackImage properties.

This property must be set before the track images are loaded. When specified at creation this property is loaded before loading any of the track images

Default: 1

# max

Availability

0.8

9.2.0

max :Number

Maximum value of the slider.

Specifies the value of the slider when the thumb is all the way to the right. This value is inclusive.

On Android, the selectable values can be limited using the minRange and maxRange properties.

On Android this must be an integer value.

Default: 1. (property value might be undefined)

# maxRange

Availability

0.8

maxRange :Number

Upper limit on the slider value that can be selected.

If maxRange is specified, value of the slider can't be increased above maxRange.

The total displayed range of the slider is still from min to max.

If undefined, the slider can go all the way to max.

On Android this must be an integer value.

Default: undefined

# min

Availability

0.8

9.2.0

min :Number

Minimum value of the slider.

Specifies the value of the slider when the thumb is all the way to the left. This value is inclusive.

On Android, the selectable values can be limited using the minRange and maxRange properties.

On Android this must be an integer value.

Default: 0. (property value might be undefined)

# minRange

Availability

0.8

minRange :Number

Lower limit on the slider value that can be selected.

If minRange is specified, value of the slider can't be decreased below minRange.

The total displayed range of the slider is still from min to max.

If undefined, the slider can go all the way to min.

On Android this must be an integer value.

Default: undefined

# rightTrackImage

Availability

0.8

9.2.0

rightTrackImage :String

Image URL of the slider right track.

See introduction of the Titanium.UI.Slider component for implementation specific information on Android Platform.

# rightTrackLeftCap

Availability

3.0.0

9.2.0

rightTrackLeftCap :Number

Size of the left end cap for the rightTrackImage, disabledRightTrackImage, highlightedRightTrackImage and selectedRightTrackImage properties.

This property must be set before the track images are loaded. When specified at creation this property is loaded before loading any of the track images

Default: 1

# rightTrackTopCap

Availability

3.0.0

9.2.0

rightTrackTopCap :Number

Size of the top end cap for the rightTrackImage, disabledRightTrackImage, highlightedRightTrackImage and selectedRightTrackImage properties.

This property must be set before the track images are loaded. When specified at creation this property is loaded before loading any of the track images

Default: 1

# selectedLeftTrackImage

Availability

0.8

9.2.0

selectedLeftTrackImage :String

Image URL of the slider left track when in the selected state.

# selectedRightTrackImage

Availability

0.8

9.2.0

selectedRightTrackImage :String

Image URL of the slider right track when in the selected state.

# selectedThumbImage

Availability

0.8

9.2.0

selectedThumbImage :String

Image URL of the slider thumb when in the selected state.

# splitTrack

Availability

6.2.0

splitTrack :Boolean

Separates the thumbImage from the slider track.

Default: false

# thumbImage

Availability

0.8

9.2.0

thumbImage :String | Titanium.Blob

Image for the slider thumb.

The thumb image can be specified as a URL.

Support for using Titanium.Blob for this property is only available on iOS.

# tintColor

Availability

3.1.3

9.2.0

tintColor :String | Titanium.UI.Color

The color shown for the portion of the progress bar that is filled.

This property is a direct correspondant of the tintColor property of UIView on iOS. If no value is specified, the tintColor of the View is inherited from its superview.

Default: null

# trackTintColor

Availability

8.3.0

9.2.0

trackTintColor :String | Titanium.UI.Color

The color shown for the portion of the progress bar that is not filled.

# value

Availability

0.8

9.2.0

value :Number

Current value of the slider.

# Methods

# setValue

Availability

0.8

9.2.0

setValue(value[, options]) → void

Sets the value property.

On iOS, you can specify that the value change should be animated by passing the optional options parameter.

Parameters

Name	Type	Description
`value`	Number	New value for the value property.
`options`	AnimatedOptions	Specifies animation options. The only supported property for this dictionary is the `animated` flag, which specifies whether the value change should be animated. `animated` is false by default. Only used on iOS.

Returns

Type: void

# Events

# click

Availability

0.9

Fired when the device detects a click against the view.

There is a subtle difference between singletap and click events.

A singletap event is generated when the user taps the screen briefly without moving their finger. This gesture will also generate a click event.

However, a click event can also be generated when the user touches, moves their finger, and then removes it from the screen.

For sliders on Android, the click event is only generated by a trackball click on the slider thumb.

Properties

Name	Type	Description
y	Number	Y coordinate of the event from the `source` view's coordinate system.
x	Number	X coordinate of the event from the `source` view's coordinate system.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# change

Availability

0.8

9.2.0

Fired when the value of the slider changes.

Properties

Name	Type	Description
value	Number	New value of the slider.
thumbSize	Size	Dictionary with properties `width` and `height` of the size of the thumb. Available with custom thumb image.
thumbOffset	Point	Dictionary with properties `x` and `y` of the thumb's left-top corner in the control. Available with custom thumb image.
isTrusted	Boolean	True if change was made by the user. False if change was made programmatically.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# start

Availability

3.1.0

9.2.0

Fired when the user starts tracking the slider.

Properties

Name	Type	Description
value	Number	Current value of the slider.
bubbles	Boolean	False. This event does not bubble.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# stop

Availability

3.1.0

9.2.0

Fired when the user stops tracking the slider.

Properties

Name	Type	Description
value	Number	Current value of the slider.
bubbles	Boolean	False. This event does not bubble.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.