Skip to content
Titanium SDK
Version12.5.0

You are reading 12.5.0. See this page in 13.4.1.

Titanium.UI.Switch

viewAndroidiPhoneiPadmacOSsince 0.8

Extends Titanium.UI.ViewTitanium.Proxy

An on/off switch control.

Android iOS
Android iOS

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 85

animated

BooleaniPhoneiPadmacOSsince 5.1.1

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)

apiName

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

Inherited from Titanium.UI.View

A background gradient for the view.

Linear and Radial Gradients

The following code excerpt creates two views, one with a linear gradient and one with a radial gradient.

var win1 = Titanium.UI.createWindow({
    title:'Tab 1',
    backgroundColor:'#fff',
    layout: 'vertical'
});

var radialGradient = Ti.UI.createView({
    top: 10,
    width: 100,
    height: 100,
    backgroundGradient: {
        type: 'radial',
        startPoint: { x: 50, y: 50 },
        endPoint: { x: 50, y: 50 },
        colors: [ 'red', 'blue'],
        startRadius: 50,
        endRadius: 0,
        backfillStart: true
    }
});
var linearGradient = Ti.UI.createView({
    top: 10,
    width: 100,
    height: 100,
    backgroundGradient: {
        type: 'linear',
        startPoint: { x: '0%', y: '50%' },
        endPoint: { x: '100%', y: '50%' },
        colors: [ { color: 'red', offset: 0.0}, { color: 'blue', offset: 0.25 }, { color: 'red', offset: 1.0 } ],
    }
});
win1.add(radialGradient);
win1.add(linearGradient);
win1.open();

borderRadius

Number | String | Array<Number> | Array<String>

Inherited from Titanium.UI.View

Radius for the rounded corners of the view's border.

Default: 0

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

Indicates if the proxy will bubble an event to its parent.

Default: true

color

String | Titanium.UI.ColorAndroid

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

elevation

NumberAndroidsince 5.0.0Android 5+

Inherited from Titanium.UI.View

Base elevation of the view relative to its parent in pixels.

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)

focusable

BooleanAndroid

Inherited from Titanium.UI.View

Whether view should be focusable while navigating with the trackball.

Default: false

font

FontAndroid

Font to use for the switch text.

layout

String

Inherited from Titanium.UI.View

Specifies how the view positions its children. One of: 'composite', 'vertical', or 'horizontal'.

left

Number | String

Inherited from Titanium.UI.View

View's left position, in platform-specific units.

onThumbColor

String | Titanium.UI.ColorAndroidsince 12.4.0

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

Android: Active thumb color of the Material Switch.

Default: undefined

onTintColor

String | Titanium.UI.Colorsince Android 12.4.0, iPhone 3.3.0, iPad 3.3.0

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

Default: undefined

opacity

Number

Inherited from Titanium.UI.View

Opacity of this view, from 0.0 (transparent) to 1.0 (opaque). Defaults to 1.0 (opaque).

rect

DimensionWithAbsolutessince 2.0.0read-only

Inherited from Titanium.UI.View

The bounding box of the view relative to its parent, in system units.

rotation

NumberAndroidiPhoneiPadsince Android 5.4.0, iPhone 12.3.0, iPad 12.3.0

Inherited from Titanium.UI.View

Clockwise 2D rotation of the view in degrees.

textAlign

String | NumberAndroid

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.

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

thumbColor

String | Titanium.UI.ColorAndroidsince 12.4.0

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

Android: Inactive thumb color of the Material Switch.

Default: undefined

tintColor

String | Titanium.UI.ColorAndroidiPhoneiPadsince Android 12.4.0, iPhone 3.3.0, iPad 3.3.0

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

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

Android: Track color of the Material Switch.

Default: undefined

titleOff

StringAndroid

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

StringAndroid

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

tooltip

Stringsince 12.1.0iOS 15.0+

Inherited from Titanium.UI.View

The default text to display in the control's tooltip.

touchFeedback

BooleanAndroidsince 6.1.0

Inherited from Titanium.UI.View

A material design visual construct that provides an instantaneous visual confirmation of touch point.

Default: false

translationX

NumberAndroidsince 5.0.0

Inherited from Titanium.UI.View

Horizontal location of the view relative to its left position in pixels.

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)

Methods 13

Inherited from Titanium.Proxy

Adds the specified callback as an event listener for the named event.

Parameters
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

Callback function to invoke when the event is fired.

4 fields
bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

convertPointToView

since Android 1.8, iPhone 1.8, iPad 1.8, macOS 9.2.0

Inherited from Titanium.UI.View

Translates a point from this view's coordinate system to another view's coordinate system.

Parameters
ParametersTypeDescription
pointPoint

A point in this view's coordinate system.

If this argument is missing an x or y property, or the properties can not be converted into numbers, an exception will be raised.

destinationViewTitanium.UI.View

View that specifies the destination coordinate system to convert to. If this argument is not a view, an exception will be raised.

Returns Point

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

Parameters
ParametersTypeDescription
nameString

Name of the event.

event?Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

getViewById

since 6.1.0

Inherited from Titanium.UI.View

Returns the matching view of a given view ID.

Parameters
ParametersTypeDescription
idString

The ID of the view that should be returned. Use the id property in your views to enable it for indexing in this method.

Inherited from Titanium.UI.View

Hides this view.

Parameters
ParametersTypeDescription
options?AnimatedOptions

Animation options for Android only. Since SDK 5.1.0 and used only on Android 5.0+

Determines whether to enable a circular reveal animation. Note that the default here is equivalent to passing in { animated: false }

insertAt

since 3.3.0

Inherited from Titanium.UI.View

Inserts a view at the specified position in the children array.

Parameters
ParametersTypeDescription
paramsViewPositionOptions

Pass an object that specifies the view to insert and optionally at which position (defaults to end)

2 fields
position? Number

Position in the children array of the view element to replace.

view Titanium.UI.View

View to insert. Required.

Inherited from Titanium.Proxy

Removes the specified callback as an event listener for the named event.

Parameters
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

4 fields
bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

Inherited from Titanium.UI.View

Makes this view visible.

Parameters
ParametersTypeDescription
options?AnimatedOptions

Animation options for Android only. Since SDK 5.1.0 and only used on Android 5.0+

Determines whether to enable a circular reveal animation. Note that the default here is equivalent to passing in { animated: false }

Inherited from Titanium.UI.View

Returns an image of the rendered view, as a Blob.

Parameters
ParametersTypeDescription
callback?Callback<Titanium.Blob>

Function to be invoked upon completion. If non-null, this method will be performed asynchronously. If null, it will be performed immediately.

honorScaleFactor?Boolean

Determines whether the image is scaled based on scale factor of main screen. (iOS only)

When set to true, image is scale factor is honored. When set to false, the image in the blob has the same dimensions for retina and non-retina devices.

Events 17

Fired when the switch value changes.

Event properties
Event propertiesTypeDescription
valueBoolean

New value of the switch.

click

Android

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.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

Inherited from Titanium.UI.View

Fired when the device detects a double click against the view.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

obscuredBoolean

Returns true if the double click passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Inherited from Titanium.UI.View

Fired when the device detects a double tap against the view.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

obscuredBoolean

Returns true if the double tap passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

keypressed

since Android 3.1.0, iPhone 5.4.0, iPad 5.4.0, macOS 9.2.0

Inherited from Titanium.UI.View

Fired when a hardware key is pressed in the view.

Event properties
Event propertiesTypeDescription
keyCodeNumber

The code for the physical key that was pressed. For more details, see KeyEvent. This API is experimental and subject to change.

Inherited from Titanium.UI.View

Fired when the device detects a long press.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

obscuredBoolean

Returns true if the long press passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

pinch

since 1.8.0

Inherited from Titanium.UI.View

Fired when the device detects a pinch gesture.

Event properties
Event propertiesTypeDescription
scaleNumber

The scale factor relative to the points of the two touches in screen coordinates.

velocityNumber

The velocity of the pinch in scale factor per second.

timeNumber

The event time of the current event being processed.

timeDeltaNumber

The time difference in milliseconds between the previous accepted scaling event and the current scaling event.

currentSpanNumber

The average distance between each of the pointers forming the gesture in progress through the focal point.

currentSpanXNumber

The average X distance between each of the pointers forming the gesture in progress through the focal point.

currentSpanYNumber

The average Y distance between each of the pointers forming the gesture in progress through the focal point.

previousSpanNumber

The previous average distance between each of the pointers forming the gesture in progress through the focal point.

previousSpanXNumber

The previous average X distance between each of the pointers forming the gesture in progress through the focal point.

previousSpanYNumber

The previous average Y distance between each of the pointers forming the gesture in progress through the focal point.

focusXNumber

The X coordinate of the current gesture's focal point.

focusYNumber

The Y coordinate of the current gesture's focal point.

inProgressBoolean

Returns true if a scale gesture is in progress, false otherwise.

Inherited from Titanium.UI.View

Fired when the device detects a single tap against the view.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

obscuredBoolean

Returns true if the single tap passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Inherited from Titanium.UI.View

Fired when the device detects a swipe gesture against the view.

Event properties
Event propertiesTypeDescription
directionString

Direction of the swipe--either 'left', 'right', 'up', or 'down'.

xNumber

X coordinate of the event's endpoint from the source view's coordinate system.

yNumber

Y coordinate of the event's endpoint from the source view's coordinate system.

obscuredBoolean

Returns true if the swipe passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Inherited from Titanium.UI.View

Fired when a touch event is interrupted by the device.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

forceNumber

The current force value of the touch event. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later and on some Android devices.

sizeNumber

The current size of the touch area. Note: This property is only available on some Android devices.

maximumPossibleForceNumber

Maximum possible value of the force property. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

altitudeAngleNumber

A value which indicates the stylus angle on the screen. If the stylus is perpendicular to the screen or no stylus is being used, the value will be Pi/2. If the stylus is parallel to the screen, the value will be 0. Note: This property is only available for iOS devices that support 3D-Touch and are 9.1 or later.

timestampNumber

The time (in seconds) when the touch was used in correlation with the system start up. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

azimuthUnitVectorInViewXNumber

The x value of the unit vector that points in the direction of the azimuth of the stylus. Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.

azimuthUnitVectorInViewYNumber

The y value of the unit vector that points in the direction of the azimuth of the stylus. Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.

obscuredBoolean

Returns true if the touch passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Inherited from Titanium.UI.View

Fired when a touch event is completed.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

forceNumber

The current force value of the touch event. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later and on some Android devices.

sizeNumber

The current size of the touch area. Note: This property is only available on some Android devices.

maximumPossibleForceNumber

Maximum possible value of the force property. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

altitudeAngleNumber

A value which indicates the stylus angle on the screen. If the stylus is perpendicular to the screen or no stylus is being used, the value will be Pi/2. If the stylus is parallel to the screen, the value will be 0. Note: This property is only available for iOS devices that support 3D-Touch and are 9.1 or later.

timestampNumber

The time (in seconds) when the touch was used in correlation with the system start up. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

azimuthUnitVectorInViewXNumber

The x value of the unit vector that points in the direction of the azimuth of the stylus. Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.

azimuthUnitVectorInViewYNumber

The y value of the unit vector that points in the direction of the azimuth of the stylus. Note: This property is only available for iOS devices that support the Apple Penciland are 9.1 or later.

obscuredBoolean

Returns true if the touch passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Inherited from Titanium.UI.View

Fired as soon as the device detects movement of a touch.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

forceNumber

The current force value of the touch event. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later and on some Android devices.

sizeNumber

The current size of the touch area. Note: This property is only available on some Android devices.

maximumPossibleForceNumber

Maximum possible value of the force property. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

altitudeAngleNumber

A value which indicates the stylus angle on the screen. If the stylus is perpendicular to the screen or no stylus is being used, the value will be Pi/2. If the stylus is parallel to the screen, the value will be 0. Note: This property is only available for iOS devices that support 3D-Touch and are 9.1 or later.

timestampNumber

The time (in seconds) when the touch was used in correlation with the system start up. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

azimuthUnitVectorInViewXNumber

The x value of the unit vector that points in the direction of the azimuth of the stylus. Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.

azimuthUnitVectorInViewYNumber

The y value of the unit vector that points in the direction of the azimuth of the stylus. Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.

obscuredBoolean

Returns true if the touch passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Inherited from Titanium.UI.View

Fired as soon as the device detects a touch gesture.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

forceNumber

The current force value of the touch event. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later and on some Android devices.

sizeNumber

The current size of the touch area. Note: This property is only available on some Android devices.

maximumPossibleForceNumber

Maximum possible value of the force property. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

altitudeAngleNumber

A value which indicates the stylus angle on the screen. If the stylus is perpendicular to the screen or no stylus is being used, the value will be Pi/2. If the stylus is parallel to the screen, the value will be 0. Note: This property is only available for iOS devices that support 3D-Touch and are 9.1 or later.

timestampNumber

The time (in seconds) when the touch was used in correlation with the system start up. Note: This property is only available for iOS devices that support 3D-Touch and run 9.0 or later.

azimuthUnitVectorInViewXNumber

The x value of the unit vector that points in the direction of the azimuth of the stylus. Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.

azimuthUnitVectorInViewYNumber

The y value of the unit vector that points in the direction of the azimuth of the stylus. Note: This property is only available for iOS devices that support the Apple Pencil and are 9.1 or later.

obscuredBoolean

Returns true if the touch passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

twofingertap

since 3.0.0

Inherited from Titanium.UI.View

Fired when the device detects a two-finger tap against the view.

Event properties
Event propertiesTypeDescription
xNumber

X coordinate of the event from the source view's coordinate system.

yNumber

Y coordinate of the event from the source view's coordinate system.

obscuredBoolean

Returns true if the tap passed through an overlapping window belonging to another app.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.