Browse the API284 types

Version13.2.0

You are reading 13.2.0. See this page in 13.4.1.

Titanium.UI.Button

viewAndroidiPhoneiPadmacOSsince 0.8

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

Android	iOS

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

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:

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.iOS.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.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 PLAIN style or use system icons such as 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 win = Ti.UI.createWindow();
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");
});
win.add(button);
win.open();

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 89

accessibilityDisableLongPress

BooleanAndroidsince 12.4.0

Parameters	Type	Description
name	String	Name of the event.
callback	Callback<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.

Parameters	Type	Description
animation	Titanium.UI.Animation \| Dictionary<Titanium.UI.Animation>	Either a dictionary of animation properties or an Animation object.
callback?	Callback<Object>	Function to be invoked upon completion of the animation.

Parameters	Type	Description
point	Point	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.
destinationView	Titanium.UI.View	View that specifies the destination coordinate system to convert to. If this argument is not a view, an exception will be raised.

Parameters	Type	Description
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.

Event properties	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	Returns `true` if the 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.

Event properties	Type	Description
scale	Number	The scale factor relative to the points of the two touches in screen coordinates.
velocity	Number	The velocity of the pinch in scale factor per second.
time	Number	The event time of the current event being processed.
timeDelta	Number	The time difference in milliseconds between the previous accepted scaling event and the current scaling event.
currentSpan	Number	The average distance between each of the pointers forming the gesture in progress through the focal point.
currentSpanX	Number	The average X distance between each of the pointers forming the gesture in progress through the focal point.
currentSpanY	Number	The average Y distance between each of the pointers forming the gesture in progress through the focal point.
previousSpan	Number	The previous average distance between each of the pointers forming the gesture in progress through the focal point.
previousSpanX	Number	The previous average X distance between each of the pointers forming the gesture in progress through the focal point.
previousSpanY	Number	The previous average Y distance between each of the pointers forming the gesture in progress through the focal point.
focusX	Number	The X coordinate of the current gesture's focal point.
focusY	Number	The Y coordinate of the current gesture's focal point.
inProgress	Boolean	Returns `true` if a scale gesture is in progress, `false` otherwise.

Event properties	Type	Description
direction	String	Direction of the swipe--either 'left', 'right', 'up', or 'down'.
x	Number	X coordinate of the event's endpoint from the `source` view's coordinate system.
y	Number	Y coordinate of the event's endpoint from the `source` view's coordinate system.
obscured	Boolean	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.

Examples

Simple Button Example

Alloy XML Markup

Properties 89

Linear and Radial Gradients

Methods 13

Events 18