Titanium.UI.Button

Object of Titanium.UI.

Platform	Since
Android	0.8
iPhone	0.8
iPad	0.8
Mobile Web	1.8

Summary

A button widget.

Description

A button widget that has four states, normal, disabled, focused and selected. (Note that the focused state is only used on Android devices that have navigation keys or a keyboard.)

You can specify background images for each state, as well as button text and a button icon. On iOS, there are button styles which define appearance for each state, even if no button images are set.

Use the Titanium.UI.createButton method to create a button.

Android Platform Notes

Android uses default button images for the normal, focused, selected and disabled states. If you use a custom button image, you should specify versions for the focused and selected states (and the disabled state, if the button is ever disabled).

Android also supports setting the background color for each of the states. These are not supported on iOS.

iOS Platform Notes

iOS buttons have two special properties, style and systemButton.

The style property specifies the type of button decoration, and can be set to one of the values described in Titanium.UI.iPhone.SystemButtonStyle.

Unlike Android, iOS doesn't supply any default background images for buttons-- system button styles serve this purpose.

Button style decorations are drawn above the background gradient and background color, and below any background images.

To use a custom button style, for example using a background gradient, you may need to explicitly set style to PLAIN, to prevent the button style from
overriding any background color or gradient. In addition, the backgroundImage must be partially or wholly transparent for the background color or background gradient to be visible.

In order for a background gradient to show through, the backgroundColor may need to be set to 'transparent'.

The systemButton property lets you create a predefined system-defined button, such as the Camera or Add buttons, for use in toolbars and nav bars. Specifically, system buttons may be used in the following locations:

Titanium.UI.iOS.Toolbar. The items array can contain system buttons.
Titanium.UI.iPad.Popover. The leftNavButton and rightNavButton properties can refer to system buttons
Titanium.UI.iPad.SplitWindow. The toolbar array can contain system buttons.
Titanium.UI.TextField. The keyboardToolbar array can contain system buttons.
Titanium.UI.TextArea. The keyboardToolbar array can contain system buttons.
Titanium.UI.Window. The leftNavButton and rightNavButton properties can refer to system buttons and the toolbar array can contain system buttons.

Use the constants in Titanium.UI.iPhone.SystemButton to specify a button type. The size, style and decoration of system buttons is set automatically, so you can create a button by setting only the systemButton property.

For example:

cancelButton = Ti.UI.createButton({ systemButton: Ti.UI.iPhone.SystemButton.CANCEL });

Note that the systemButton property specifies appearance, not behavior. For example, to bring up the camera when the user presses the Camera button, you must add an event listener to the button and call Titanium.Media.showCamera when the button is clicked.

Code Examples

Simple Button Example

var button = Titanium.UI.createButton({
   title: 'Hello',
   top: 10,
   width: 100,
   height: 50
});
button.addEventListener('click',function(e)
{
   Titanium.API.info("You clicked the button");
});

Methods

Name	Summary
add	Adds a child to this view's hierarchy.
addEventListener	Adds the specified callback as an event listener for the named event.
animate	Animates this view.
convertPointToView	Translates a point from this view's coordinate system to another view's coordinate system. (Android, iPhone, iPad only.)
fireEvent	Fires a synthesized event to any registered listeners.
getAnchorPoint	Gets the value of the anchorPoint property. (iPhone, iPad only.)
getAnimatedCenterPoint	Gets the value of the animatedCenterPoint property. (Android, iPhone, iPad only.)
getBackgroundColor	Gets the value of the backgroundColor property.
getBackgroundDisabledColor	Gets the value of the backgroundDisabledColor property. (Android only.)
getBackgroundDisabledImage	Gets the value of the backgroundDisabledImage property.
getBackgroundFocusedColor	Gets the value of the backgroundFocusedColor property. (Android only.)
getBackgroundFocusedImage	Gets the value of the backgroundFocusedImage property.
getBackgroundGradient	Gets the value of the backgroundGradient property. (iPhone, iPad, Mobile Web only.)
getBackgroundImage	Gets the value of the backgroundImage property.
getBackgroundLeftCap	Gets the value of the backgroundLeftCap property. (iPhone, iPad only.)
getBackgroundRepeat	Gets the value of the backgroundRepeat property. (iPhone, iPad only.)
getBackgroundSelectedColor	Gets the value of the backgroundSelectedColor property. (Android, Mobile Web only.)
getBackgroundSelectedImage	Gets the value of the backgroundSelectedImage property.
getBackgroundTopCap	Gets the value of the backgroundTopCap property. (iPhone, iPad only.)
getBorderColor	Gets the value of the borderColor property.
getBorderRadius	Gets the value of the borderRadius property.
getBorderWidth	Gets the value of the borderWidth property.
getBottom	Gets the value of the bottom property.
getCenter	Gets the value of the center property.
getChildren	Gets the value of the children property.
getColor	Gets the value of the color property.
getEnabled	Gets the value of the enabled property.
getFocusable	Gets the value of the focusable property. (Android only.)
getFont	Gets the value of the font property.
getHeight	Gets the value of the height property.
getImage	Gets the value of the image property.
getKeepScreenOn	Gets the value of the keepScreenOn property. (Android only.)
getLayout	Gets the value of the layout property.
getLeft	Gets the value of the left property.
getOpacity	Gets the value of the opacity property.
getRight	Gets the value of the right property.
getSelectedColor	Gets the value of the selectedColor property. (iPhone, iPad only.)
getSize	Gets the value of the size property.
getSoftKeyboardOnFocus	Gets the value of the softKeyboardOnFocus property. (Android only.)
getStyle	Gets the value of the style property. (iPhone, iPad only.)
getSystemButton	Gets the value of the systemButton property. (iPhone, iPad only.)
getTextAlign	Gets the value of the textAlign property.
getTitle	Gets the value of the title property.
getTitleid	Gets the value of the titleid property.
getTop	Gets the value of the top property.
getTouchEnabled	Gets the value of the touchEnabled property.
getTransform	Gets the value of the transform property.
getVerticalAlign	Gets the value of the verticalAlign property. (Android only.)
getVisible	Gets the value of the visible property.
getWidth	Gets the value of the width property.
getZIndex	Gets the value of the zIndex property.
hide	Hides this view.
remove	Removes a child view from this view's hierarchy.
removeEventListener	Removes the specified callback as an event listener for the named event.
setAnchorPoint	Sets the value of the anchorPoint property. (iPhone, iPad only.)
setBackgroundColor	Sets the value of the backgroundColor property.
setBackgroundDisabledColor	Sets the value of the backgroundDisabledColor property. (Android only.)
setBackgroundDisabledImage	Sets the value of the backgroundDisabledImage property.
setBackgroundFocusedColor	Sets the value of the backgroundFocusedColor property. (Android only.)
setBackgroundFocusedImage	Sets the value of the backgroundFocusedImage property.
setBackgroundGradient	Sets the value of the backgroundGradient property. (iPhone, iPad, Mobile Web only.)
setBackgroundImage	Sets the value of the backgroundImage property.
setBackgroundLeftCap	Sets the value of the backgroundLeftCap property. (iPhone, iPad only.)
setBackgroundRepeat	Sets the value of the backgroundRepeat property. (iPhone, iPad only.)
setBackgroundSelectedColor	Sets the value of the backgroundSelectedColor property. (Android, Mobile Web only.)
setBackgroundSelectedImage	Sets the value of the backgroundSelectedImage property.
setBackgroundTopCap	Sets the value of the backgroundTopCap property. (iPhone, iPad only.)
setBorderColor	Sets the value of the borderColor property.
setBorderRadius	Sets the value of the borderRadius property.
setBorderWidth	Sets the value of the borderWidth property.
setBottom	Sets the value of the bottom property.
setCenter	Sets the value of the center property.
setColor	Sets the value of the color property.
setEnabled	Sets the value of the enabled property.
setFocusable	Sets the value of the focusable property. (Android only.)
setFont	Sets the value of the font property.
setHeight	Sets the value of the height property.
setImage	Sets the value of the image property.
setKeepScreenOn	Sets the value of the keepScreenOn property. (Android only.)
setLayout	Sets the value of the layout property.
setLeft	Sets the value of the left property.
setOpacity	Sets the value of the opacity property.
setRight	Sets the value of the right property.
setSelectedColor	Sets the value of the selectedColor property. (iPhone, iPad only.)
setSoftKeyboardOnFocus	Sets the value of the softKeyboardOnFocus property. (Android only.)
setStyle	Sets the value of the style property. (iPhone, iPad only.)
setSystemButton	Sets the value of the systemButton property. (iPhone, iPad only.)
setTextAlign	Sets the value of the textAlign property.
setTitle	Sets the value of the title property.
setTitleid	Sets the value of the titleid property.
setTop	Sets the value of the top property.
setTouchEnabled	Sets the value of the touchEnabled property.
setTransform	Sets the value of the transform property.
setVerticalAlign	Sets the value of the verticalAlign property. (Android only.)
setVisible	Sets the value of the visible property.
setWidth	Sets the value of the width property.
setZIndex	Sets the value of the zIndex property.
show	Makes this view visible.
toImage	Returns an image of the rendered view, as a Blob. (Android, iPhone, iPad only.)

Properties

Name	Type	Summary
anchorPoint	`Point`	Anchor point where animation should occur, relative to the view's boundaries. (iPhone, iPad only.)
animatedCenterPoint	`Point`	Current position of the view during an animation. (Android, iPhone, iPad only.) read-only
backgroundColor	String	Background color of the view.
backgroundDisabledColor	String	Disabled background color of the view. (Android only.)
backgroundDisabledImage	String	Background image for the button in its disabled state, specified as a local file path or URL.
backgroundFocusedColor	String	Focused background color of the view. (Android only.)
backgroundFocusedImage	String	Background image for the button in its focused state, specified as a local file path or URL.
backgroundGradient	`Gradient`	A background gradient for the view. (iPhone, iPad, Mobile Web only.)
backgroundImage	String	Background image for the button in its normal state, specified as a local file path or URL.
backgroundLeftCap	Number	Size of the left end cap. (iPhone, iPad only.)
backgroundRepeat	Boolean	Toggle for whether or not to tile a background across a view. (iPhone, iPad only.)
backgroundSelectedColor	String	Selected background color of the view. (Android, Mobile Web only.)
backgroundSelectedImage	String	Background image for the button in its selected state, specified as a local file path or URL.
backgroundTopCap	Number	Size of the top end cap. (iPhone, iPad only.)
borderColor	String	Border color of the view.
borderRadius	Number	Border radius of the view.
borderWidth	Number	Border width of the view.
bottom	Number or String	View's bottom position, in platform-specific units.
center	`Point`	View's center position, in the parent view's coordinates.
children	Array<`Titanium.UI.View`>	Array of this view's child views. read-only
color	String	Default button text color.
enabled	Boolean	Set to `true` to enable the button, `false` to disable the button.
focusable	Boolean	Whether view should be focusable while navigating with the trackball. (Android only.)
font	`Font`	Font to use for the button text.
height	Number or String	View height, in platform-specific units.
image	String or `Titanium.Blob`	Image to display on the button, specified as a local path, URL or (on iOS only) a `Blob`.
keepScreenOn	Boolean	Whether to keep the device screen on. (Android only.)
layout	String	Specifies how the view positions its children. One of: 'absolute', 'vertical', or 'horizontal'.
left	Number or String	View's left position, in platform-specific units.
opacity	Number	Opacity of this view, from 0.0 (transparent) to 1.0 (opaque).
right	Number or String	View's right position, in platform-specific units.
selectedColor	String	Button text color used to indicate the selected state. (iPhone, iPad only.)
size	Object	Rendered size of the view as a dictionary of width and height properties. read-only
softKeyboardOnFocus	Number	Determines keyboard behavior when this view is focused. (Android only.)
style	Number	Style constant for the button, as defined in `Titanium.UI.iPhone.SystemButtonStyles`. (iPhone, iPad only.)
systemButton	Number	Specifies an iOS system button appearance, as defined in `Titanium.UI.iPhone.SystemButton`. (iPhone, iPad only.)
textAlign	String or Number	Text alignment, specified using one of the `Titanium.UI` text alignment constants: TEXT_ALIGNMENT_LEFT, TEXT_ALIGNMENT_CENTER, or TEXT_ALIGNMENT_RIGHT.
title	String	Button title.
titleid	String	Key identifying a string from the locale file to use for the button title.
top	Number or String	The view's top position.
touchEnabled	Boolean	Whether view should receive touch events.
transform	`Titanium.UI.2DMatrix` or `Titanium.UI.iOS.3DMatrix`	Transformation matrix to apply to the view.
verticalAlign	Number or String	Vertical alignment for the text field, specified using one of the vertical alignment constants from `Titanium.UI`: TEXT_VERTICAL_ALIGNMENT_BOTTOM, TEXT_VERTICAL_ALIGNMENT_CENTER, or TEXT_VERTICAL_ALIGNMENT_TOP. (Android only.)
visible	Boolean	Boolean value indicating whether the view is visible.
width	Number or String	View's width, in platform-specific units.
zIndex	Number	Z index position relative to other sibling views.

Events

Name	Summary
click	Fired when the device detects a click against the view.
dblclick	Fired when the device detects a double click against the view.
doubletap	Fired when the device detects a double tap against the view. (Android, iPhone, iPad only.)
longclick	Fired when the device detects a long click. (Android only.)
longpress	Fired when the device detects a long press. (Android, iPhone, iPad only.)
pinch	Fired when the device detects a pinch gesture. (iPhone, iPad only.)
singletap	Fired when the device detects a single tap against the view.
swipe	Fired when the device detects a swipe gesture (left or right) against the view. (iPhone, iPad, Mobile Web only.)
touchcancel	Fired when a touch event is interrupted by the device.
touchend	Fired when a touch event is completed.
touchmove	Fired as soon as the device detects movement of a touch.
touchstart	Fired as soon as the device detects a touch gesture.
twofingertap	Fired when the device detects a two-finger tap against the view.