# Titanium.UI.Switch

An on/off switch control.

Availability

0.8

9.2.0

Extends

Titanium.UI.View

# Overview

Android	iOS	Windows

The appearance of a Switch control varies by platform:

On Android, a Switch object can be styled either as a switch, checkbox or toggle button based on the Titanium.UI.Switch.style property. The checkbox style can optionally display a label next to the control.
On iOS, a Switch appears as an iOS on/off switch and doesn't have any text associated with it.

Use the Titanium.UI.createSwitch method or <Switch> Alloy element to create a switch.

# Examples

# Simple Switch Example

Create a standard switch, using default values, and output value property on each change event.

var win = Ti.UI.createWindow({
  backgroundColor: 'white'
});

var basicSwitch = Ti.UI.createSwitch({
  value:true // mandatory property for iOS
});
win.add(basicSwitch);

basicSwitch.addEventListener('change',function(e){
  Ti.API.info('Switch value: ' + basicSwitch.value);
});

win.open();

// print initial value
Ti.API.info('Switch value: ' + basicSwitch.value);

# Toggle Button Switch Example (Android)

Create a standard (toggle button) switch with a customized title for each on/off state, and output value property on each change event.

var win = Ti.UI.createWindow({
  backgroundColor: 'white'
});

var basicSwitch = Ti.UI.createSwitch({
  style: Ti.UI.SWITCH_STYLE_TOGGLE_BUTTON,
  titleOn:'Notifications Enabled',
  titleOff:'Notifications Disabled',
  value:true,
  width: 200, height:120
});
win.add(basicSwitch);

basicSwitch.addEventListener('change',function(e){
  Ti.API.info('Switch value: ' + basicSwitch.value);
});

win.open();

# Checkbox Switch Example (Android)

Create a checkbox switch, and output value property on each change event.

var win = Ti.UI.createWindow({
  backgroundColor: 'white'
});

var basicSwitch = Ti.UI.createSwitch({
  style: Ti.UI.SWITCH_STYLE_CHECKBOX,
  textAlign:Ti.UI.TEXT_ALIGNMENT_CENTER,
  title:'Notifications',
  value:true,
  width: 300 // necessary for textAlign to be effective
});
win.add(basicSwitch);

basicSwitch.addEventListener('change',function(e){
  Ti.API.info('Switch value: ' + basicSwitch.value);
});

win.open();

# Alloy XML Markup

Previous simple switch example as an Alloy view.

switchexample.xml:

<Alloy>
    <Window id="win" backgroundColor="white">
        <Switch id="basicSwitch" value="true" onChange="outputState"/>
    </Window>
</Alloy>

switchexample.js:

function outputState(){
    Ti.API.info('Switch value: ' + $.basicSwitch.value);
}

# Properties

# animated

Availability

5.1.1

9.2.0

animated :Boolean

Determines if there is animation when the switch value changes.

Set to true if animation is desired or false for no animation.

Default: undefined (equivalent to true)

# color

Availability

0.8

color :String | Titanium.UI.Color

Color to use for switch text, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Default: black

# enabled

Availability

0.8

9.2.0

enabled :Boolean

Determines whether the switch is enabled.

Be careful not to confused this with the value property, which is used to turn the switch on and off.

Set to true to enable or false to disable the switch.

Default: undefined (equivalent to enabled)

# font

Availability

0.8

font :Font

Font to use for the switch text.

# onTintColor

Availability

3.3.0

9.2.0

onTintColor :String | Titanium.UI.Color

The color used to tint the appearance of the switch when it is turned on.

Default: undefined

# style

Availability

0.8

10.0.0

style :Number

Style of the switch.

For Titanium versions older than 10.0.0, this is an Android only property and must be assigned a SWITCH_STYLE_* constant from the Titanium.UI module.

This API can be assigned the following constants:

Default: Titanium.UI.SWITCH_STYLE_SLIDER

# textAlign

Availability

0.8

textAlign :String | Number

Horizontal text alignment of the switch title.

This property is only applicable when the switch style is set to SWITCH_STYLE_CHECKBOX, SWITCH_STYLE_SLIDER, or SWITCH_STYLE_TOGGLE_BUTTON,

This property is only effective if the width property is set to a value greater than the width of the title contents.

This API can be assigned the following constants:

Default: Titanium.UI.TEXT_ALIGNMENT_CENTER> (toggle button, Android), <Titanium.UI.TEXT_ALIGNMENT_LEFT> (slider, Android), <Titanium.UI.TEXT_ALIGNMENT_LEFT> (checkbox, Android)

# thumbTintColor

Availability

3.3.0

9.2.0

thumbTintColor :String | Titanium.UI.Color

The color used to tint the appearance of the thumb.

Default: undefined

# tintColor

Availability

3.3.0

9.2.0

tintColor :String | Titanium.UI.Color

The color used to tint the outline of the switch when it is turned off.

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: undefined

# title

Availability

0.8

title :String

Text to display next to the switch, when the checkbox or slider style is in use.

This property is only effective when the style property is set to SWITCH_STYLE_CHECKBOX or SWITCH_STYLE_SLIDER.

Use the textAlign property to align this text within the switch.

# titleOff

Availability

0.8

titleOff :String

Text to display on the switch in its "off" state, when the toggle button style is in use.

Set to an empty string to remove title text.

It is typically useful to set the width and/or height properties, to prevent the switch changing size between its on/off state.

Default: Off

# titleOn

Availability

0.8

titleOn :String

Text to display on the switch in its "on" state, when the toggle button style is in use.

Set to an empty string to remove title text.

It is typically useful to set the width and/or height properties, to prevent the switch changing size between its on/off state.

Default: On

# value

Availability

0.8

9.2.0

value :Boolean

Indicates whether the switch has been turned on or off by the user. May also be set programmatically.

Set to true to turn on and false to turn off the switch.

On Android, if this property is not defined, the rendered state of the switch is off.

On iOS, be aware that this property must be set when the switch is rendered, otherwise it will not be visible. This is a known issue.

Default: undefined (visual state off, Android)

# verticalAlign

Availability

0.8

verticalAlign :Number | String

Vertical alignment for the text field.

This API can be assigned the following constants:

Default: Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER

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

The click event can also be generated by a trackball click.

If you want to receive and trigger the value of switch, please use the change event instead.

Properties

Name	Type	Description
x	Number	X coordinate of the event from the `source` view's coordinate system.
y	Number	Y 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 switch value changes.

Properties

Name	Type	Description
value	Boolean	New value of the switch.
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.