Titanium Mobile

# Titanium.UI.Button

A button widget that has four states: normal, disabled, focused and selected.

Availability
0.8
0.8
9.2.0
Extends
Titanium.UI.View

# Overview

Android iOS Windows
Android iOS Windows

A button displays its selected state while it is being pressed. The focused state is only used on Android devices that have navigation keys or a keyboard, to indicate which button has input focus.

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 or a <Button> Alloy element to create a button (see Examples) .

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

The Material style introduced in Titanium SDK 10.0.0 will change the default look of the buttons. You can change button styles with a custom theme as follows:

<!-- Assign this custom theme to "tiapp.xml" file's android manifest application element. -->
<style name="Theme.MyTheme" parent="Theme.Titanium.Light">
    <item name="textAppearanceButton">@style/TextAppearance.MyButton</item>
    <item name="android:buttonStyle">@style/Widget.MyButton</item>
    <item name="buttonStyle">@style/Widget.MyButton</item>
</style>

<!-- Affects the appearance of text in all material buttons. -->
<style name="TextAppearance.MyButton" parent="TextAppearance.MaterialComponents.Button">
    <!-- Do not display button text in all-caps. -->
    <item name="android:textAllCaps">false</item>
    <!-- Remove extra spacing between characters. -->
    <item name="android:letterSpacing">0</item>
</style>

<!-- Affects the appearance of all non-material system buttons. -->
<style name="Widget.MyButton" parent="Widget.AppCompat.Button">
    <!-- Do not display button text in all-caps. -->
    <item name="android:textAllCaps">false</item>
    <!-- Remove extra spacing between characters. -->
    <item name="android:letterSpacing">0</item>
</style>

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

To use a custom button style, such as a background gradient, you may need to explicitly set the button's style property to PLAIN, to prevent the button style from overriding any background color or gradient.

Also note:

  • When assigning a custom image to the backgroundImage property, the image must be partially or wholly transparent for the background color or background gradient to be visible.
  • Similarly, for an assigned background gradient to show through, the backgroundColor may need to be set to 'transparent'.

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

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:

Use the constants in Titanium.UI.iOS.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:

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

In Alloy, you can omit the namespace when setting the systemButton property:

<Button id="cancelbtn" systemButton="CANCEL"></Button>

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.

# iOS Pressed Button Effects

If you do not supply separate background images for the normal and selected states, iOS supplies a built-in effect for pressed buttons. For most iOS buttons, the effect dims the entire button (except for the text) while the button is being pressed.

For toolbar buttons that use the Titanium.UI.iOS.SystemButtonStyle.PLAIN style or use system icons such as Titanium.UI.iOS.SystemButton.CAMERA, a glow effect is used. The glow effect shows as a white circular glow or highlight at the center of the button when the button is pressed.

# 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");
});

# Alloy XML Markup

Previous example as an Alloy view.

button.xml:

<Alloy>
    <Window id="win" backgroundColor="white">
        <!-- The title property can also be defined as node text. -->
        <Button id="button" onClick="doClick" title="Hello"
            top="10" width="100" height="50" />
    </Window>
</Alloy>

button.js:

function doClick(e){
    Titanium.API.info("You clicked the button");
};

# Properties

# attributedString

Availability
7.5.0
7.5.0
9.2.0
attributedString :Titanium.UI.AttributedString

Specify an attributed string for the label.

The underlying attributed string drawn by the label. If set, avoid setting common attributes in the label, such as color and font, as unexpected behaviors may result.

iOS Note: This property can also be used to supress the underline style when accessibility is enabled. To do so, set the type to ATTRIBUTE_UNDERLINES_STYLE and the value to ATTRIBUTE_UNDERLINE_STYLE_NONE.

# backgroundDisabledImage

Availability
0.9
0.8
9.2.0
backgroundDisabledImage :String

Background image for the button in its disabled state, specified as a local file path or URL.

Also sets the background image for the other button states (normal, focused, selected), unless they've been specified explicitly, except for iOS, which requires a backgroundImage.

# backgroundFocusedImage

Availability
0.9
0.8
9.2.0
backgroundFocusedImage :String

Background image for the button in its focused state, specified as a local file path or URL.

Focusable must be true for normal views. Sets the background image for the focused state only. For iOS, since there is not a trackball, this does nothing.

# backgroundImage

Availability
0.9
0.9
9.2.0
backgroundImage :String

Background image for the button in its normal state, specified as a local file path or URL.

Also sets the background image for the other button states (disabled, focused, selected), unless they've been specified explicitly. On iOS, if backgroundDisabledImage is unset, the image will appear faded to indicate being disabled. Also on iOS, if backgroundSelectedImage is unset, the image will be darkened to indicate being selected.

# backgroundSelectedColor

Availability
0.9.0
6.1.0
9.2.0
backgroundSelectedColor :String | Titanium.UI.Color

Selected background color of the view, as a color name or hex triplet.

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

Default: Background color of this view.

# backgroundSelectedImage

Availability
0.9
0.8
9.2.0
backgroundSelectedImage :String

Background image for the button in its selected state, specified as a local file path or URL.

On Android, Focusable must be true in order to be selected. Sets the background image for the selected state only.

# color

Availability
0.8
0.8
9.2.0
color :String | Titanium.UI.Color

Default button text color, as a color name or hex triplet.

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

# disabledColor

Availability
3.2.0
9.2.0
disabledColor :String | Titanium.UI.Color

Text color of the button in its disabled state, as a color name or hex triplet.

# enabled

Availability
0.8
0.8
enabled :Boolean

Set to true to enable the button, false to disable the button.

Default: true

# font

Availability
0.8
0.8
9.2.0
font :Font

Font to use for the button text.

# image

Availability
0.8
0.8
9.2.0
image :String | Number | Titanium.Blob

Image to display next to the button title.

As of Titanium 10.2.0, the imageIsMask property determines how this image is displayed. If set true, this image will be tinted using the color assigned to the tintColor property. If set false, the image is displayed as-is.

On Android, you can set this to a numeric resource drawable ID via Ti.App.Android.R.drawable.* which lets you use native vector drawbles that are commonly used as icons.

# imageIsMask

Availability
10.2.0
10.2.0
10.2.0
imageIsMask :Boolean

Set true to tint the button image. Set false to show the image as-is.

Default: true

# selectedColor

Availability
0.8
9.2.0
selectedColor :String | Titanium.UI.Color

Button text color used to indicate the selected state, as a color name or hex triplet.

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

# shadowColor

Availability
3.2.0
3.2.0
9.2.0
shadowColor :String | Titanium.UI.Color

Shadow color of the title, as a color name or hex triplet.

Use in conjunction with shadowOffset and shadowRadius. For information about color values, see the "Colors" section of Titanium.UI.

# shadowOffset

Availability
3.2.0
3.2.0
9.2.0
shadowOffset :Point

Shadow offset of the title, as a dictionary with the properties x and y.

Use in conjunction with shadowColor and shadowRadius.

# shadowRadius

Availability
3.2.0
shadowRadius :Number

Shadow radius of the title.

Use in conjunction with shadowColor and shadowOffset.

# style

Availability
10.0.0
0.8
9.2.0
style :Number

The border and fill style the button will use.

On Android, this is a creation-only property and cannot be changed dynamically.

For Titanium versions older than 10.0.0, this is an iOS only property and must be assigned a constant from Titanium.UI.iOS.SystemButtonStyle which is now deprecated.

This API can be assigned the following constants:

Default: Titanium.UI.BUTTON_STYLE_TEXT> (on iOS), <Titanium.UI.BUTTON_STYLE_FILLED> (on Android)

# systemButton

Availability
0.8
9.2.0
systemButton :Number

Specifies an iOS system button appearance, as defined in Titanium.UI.iOS.SystemButton.

In JavaScript:

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

In Alloy, you can omit the namespace when setting the systemButton property on a <Button> element:

<Button systemButton="CAMERA"/>
This API can be assigned the following constants:

# textAlign

Availability
0.8
0.8
9.2.0
textAlign :String | Number

Text alignment, specified using one of the Titanium.UI text alignment constants.

This API can be assigned the following constants:

Default: Titanium.UI.TEXT_ALIGNMENT_CENTER

# tintColor

Availability
5.4.0
3.1.3
9.2.0
tintColor :String

Color applied to button's image and title.

Color to be applied to the button's image, but only if the imageIsMask property is set true.

This tint color is also applied to the button's title unless the color property is set.

Default: null

# title

Availability
0.8
0.8
9.2.0
title :String

Button title.

# titleid

Availability
1.5
1.5
9.2.0
titleid :String

Key identifying a string from the locale file to use for the button title.

Only one of title or titleid should be specified.

# verticalAlign

Availability
0.8
0.8
9.2.0
verticalAlign :Number | String

Vertical alignment for the text field, specified using one of the vertical alignment constants from Titanium.UI.

This API can be assigned the following constants:

Default: Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER

# Events

# touchfiltered

Availability
9.3.0

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

If the button's filterTouchesWhenObscured property is set true, then this event will be fired if the touch event was discarded because another app's overlapping window obscured it.

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.

You can use this event to display an alert dialog explaining why the button's action has been disabled. Especially if the overlapping window is completely invisible.

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.

obscured Boolean

Always true since the touch event passed through another app's overlapping window.

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.

Contents