An option dialog is a modal view that includes a message and one or more option items positioned in the middle of the display on Android and at the bottom edge on iOS. On Android, buttons may be added below the options.
 |
 |
 |
| Android | iPhone | iPad |
|---|
An option dialog is created using Titanium.UI.createOptionDialog or Alloy <OptionDialog>
element. See Examples below for usage.
This dialog is presented differently on each platform, as described below.
Android
On Android, the dialog is shown in the middle of the display (not touching the edges), with the option items represented in a picker. The previously-selected, or default, item can be set on creation.
You can assign a View to the androidView property to define a custom dialog UI and layout, or you can assign a set of options to the options property, but not both. If both of these properties are set, the custom view will appear but the options will be hidden.
Buttons below the picker may be optionally defined using the buttonNames property.
The click event returns a Boolean value to indicate whether either an option item or a button was clicked.
iOS
The destructive property may be set for an item, to give a visual cue that selecting it
results in an irreversible action.
Since iOS 4, option dialogs are automatically cancelled when the application is paused/suspended.
iPhone
On iPhone, this dialog is shown at the bottom edge of the display, with the option items represented as vertical buttons.
iPad
On iPad, this dialog is shown in the middle of the display, or as a popover-like dialog if
another view or control is specified via an argument passed to the open() method.
Note that on iPad, the cancel button is not displayed -- users can cancel the dialog by clicking outside of the dialog.
Caveats
Care should be taken not to define any properties that are not documented, as this may produce
unexpected results. For example, setting a message property will prevent the picker of option
items from being displayed on Android.
Examples
Dialog with 3 Options
Ti.UI.setBackgroundColor('white');
var win = Ti.UI.createWindow({
title: 'Click window to test',
backgroundColor: 'white'
});
var opts = {
cancel: 2,
options: ['Confirm', 'Help', 'Cancel'],
selectedIndex: 2,
destructive: 0,
title: 'Delete File?'
};
win.addEventListener('click', function(e){
var dialog = Ti.UI.createOptionDialog(opts).show();
});
win.open();Dialog with 2 Options and 1 Button on Android and 3 Options on iOS
var win = Ti.UI.createWindow({ title: 'Click window to test OptionDialog', backgroundColor: 'white' });
var opts = { title: 'Delete File?' };
var isAndroid = Ti.Platform.osname === 'android';
if (isAndroid) { opts.options = ['Confirm', 'Cancel']; opts.buttonNames = ['Help']; } else { opts.options = ['Confirm', 'Help', 'Cancel']; }
var dialog; win.addEventListener('click', function() { dialog = Ti.UI.createOptionDialog(opts);
dialog.addEventListener('click', onSelectDialog); dialog.addEventListener('cancel', function(e) { alert('Dialog canceled! e.cancel = ' + e.cancel + ', e.index = ' + e.index); })
dialog.show(); });
function onSelectDialog(e) { if (isAndroid) { if (e.button === false && e.index === 0) { alert('Confirm option selected! e.index = ' + e.index); }
if (e.button === false && eventeindex === 1) {
alert('Cancel option selected! e.index = ' + e.index);
}
if (e.button === true && e.index === 0) {
alert('Help Button clicked! e.index = ' + e.index);
}
} }
win.open();
Alloy XML Markup
Previous example as an Alloy view.
optiondialog.xml:
<Alloy>
<Window id="win" onClick="showOptions" title="Click window to test"
fullscreen="false" onExit="true" backgroundColor="white">
<!--
The OptionDialog tag declares an option dialog,
which will need to be opened by the controller.
-->
<OptionDialog id="dialog" title="Delete File?">
<!-- The Options tag sets the options property. -->
<Options>
<Option>Confirm</Option>
<Option platform="ios">Help</Option>
<Option>Cancel</Option>
</Options>
<!-- The ButtonNames tag sets the Android-only buttonNames property. -->
<ButtonNames>
<ButtonName>Help</ButtonName>
</ButtonNames>
<!-- Add a View for the androidView property here. -->
</OptionDialog>
<!-- Add views here -->
</Window>
</Alloy>
optiondialog.js:
function showOptions(){
$.dialog.show();
}
- 0.8
- 0.8
- 0.8
Properties
View to load inside the message area, to create a custom layout.
View to load inside the message area, to create a custom layout.
On Android you can either define a custom view with this property, or you can assign a set of options to the options property, but not both. If you do, the custom view will appear but not the options you defined.
In an Alloy application you can specify this property with either an <AndroidView/> or
<View/> element inside the <OptionDialog/> element, for example:
<Alloy>
<OptionDialog id="dialog" title="Delete File?" onClick="clickCB">
<!-- Add View or AndroidView for the androidView property -->
<AndroidView platform="android" layout="vertical">
<Label color="red" text="Warning! This change is permanent and you cannot undo it!" />
</AndroidView>
<ButtonNames>
<ButtonName>Confirm</ButtonName>
<ButtonName>Cancel</ButtonName>
</ButtonNames>
</OptionDialog>
</Alloy>
- 0.8
The name of the API that this proxy corresponds to.
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.
- 3.2.0
- 3.2.0
- 3.2.0
Indicates if the proxy will bubble an event to its parent.
Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.
Default: true
- 3.0.0
- 3.0.0
- 3.0.0
Index to define the cancel option.
On iOS, set to -1 to disable the cancel option.
On iPad, the cancel option must be set to either -1 or the index of the last
option. For example, if there are 3 options and one of them is a cancel button,
the cancel button must be the last option (index 2). If cancel is set to a
different value, the last entry in the options
array is not displayed.
Note that the cancel button is never shown on iPad, since the user can cancel the dialog by clicking outside of the dialog.
Default: undefined (Android), -1 (iOS)
Index to define the destructive option, indicated by a visual cue when rendered.
Default: -1
- 0.8
- 0.8
Base elevation of the view relative to its parent in pixels.
Requires: Android 5 and later
The elevation of a view determines the appearance of its shadow. Higher elevations produce larger and softer shadows.
Note: The elevation property only works on Titanium.UI.View objects.
Many Android components have a default elevation that cannot be modified.
For more information, see
Google design guidelines: Elevation and shadows.
- 5.0.0
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
- 3.6.0
Boolean value indicating if the option dialog should have an opaque background.
This property is useful to ensure that the option dialog will display contents properly on the iPAD idiom without ghosting when scrolling. This property is only respected on the iPAD idiom on iOS7 and above.
Default: false
- 3.2.0
- 3.2.0
List of option names to display in the dialog.
List of option names to display in the dialog.
On Android you can assign a set of options to the OptionDialog with this property, or
assign a custom view to the androidView property, but not both.
If you do, the custom view will appear but not the options you defined.
Boolean value indicating if the option dialog should only be cancelled by user gesture or by hide method.
This property is useful to ensure that the option dialog will not be ignored by the user when the application is paused/suspended.
Default: true
- 3.0.0
- 3.0.0
- 3.0.0
The preview context used in the 3D-Touch feature "Peek and Pop".
Requires: iOS 9.0 and later
Preview context to present the "Peek and Pop" of a view. Use an configured instance of Titanium.UI.iOS.PreviewContext here.
Note: This property can only be used on devices running iOS9 or later and supporting 3D-Touch. It is ignored on older devices and can manually be checked using Titanium.UI.iOS.forceTouchSupported.
- 5.1.0
Clockwise 2D rotation of the view in degrees.
Clockwise 2D rotation of the view in degrees.
Translation values are applied to the static post layout value.
- 5.4.0
Clockwise rotation of the view in degrees (x-axis).
Clockwise rotation of the view in degrees (x-axis).
Translation values are applied to the static post layout value.
- 5.4.0
Clockwise rotation of the view in degrees (y-axis).
Clockwise rotation of the view in degrees (y-axis).
Translation values are applied to the static post layout value.
- 5.4.0
Scaling of the view in x-axis in pixels.
Scaling of the view in x-axis in pixels.
Translation values are applied to the static post layout value.
- 5.4.0
Scaling of the view in y-axis in pixels.
Scaling of the view in y-axis in pixels.
Translation values are applied to the static post layout value.
- 5.4.0
Defines the default selected option.
Defines the default selected option.
- 0.8
The view's tintColor. This property is applicable on iOS 7 and greater.
Requires: iOS 7.0 and later
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:
- 3.1.3
- 3.1.3
Key identifying a string in the locale file to use for the title text.
Key identifying a string in the locale file to use for the title text.
A material design visual construct that provides an instantaneous visual confirmation of touch point.
Requires: Android 5.0 and later
This is an opt-in feature available from Android Lollipop. Touch feedback is applied only if the backgroundColor is a solid color.
Default: false
- 6.1.0
Optional touch feedback ripple color. This has no effect unless touchFeedback is true.
Requires: Android 5.0 and later
Default: Theme provided color.
- 6.1.0
A name to identify this view in activity transition.
Requires: Android 5 and later
Name should be unique in the View hierarchy.
- 5.0.2
Horizontal location of the view relative to its left position in pixels.
Horizontal location of the view relative to its left position in pixels.
Translation values are applied to the static post layout value.
- 5.0.0
Vertical location of the view relative to its top position in pixels.
Vertical location of the view relative to its top position in pixels.
Translation values are applied to the static post layout value.
- 5.0.0
Depth of the view relative to its elevation in pixels.
Requires: Android 5 and later
Translation values are applied to the static post layout value.
- 5.0.0
Methods
Adds the specified callback as an event listener for the named event.
Parameters
- name : String
Name of the event.
- callback : Callback<Object>
Callback function to invoke when the event is fired.
Returns
- void
Applies the properties to the proxy.
Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.
- 3.0.0
- 3.0.0
- 3.0.0
Parameters
- props : Dictionary
A dictionary of properties to apply.
Returns
- void
Finishes a batch update of the View's layout properties and schedules a layout pass of the view tree.
deprecated since 3.0.0
Use the <Titanium.Proxy.applyProperties> method to batch-update layout properties.
Since the layout pass scheduled is asynchronous, the rect
and size values may not be available immediately after
finishLayout is called.
To be notified when the layout pass completes, add a listener for the postlayout event.
- 2.0.0
- 2.0.0
- 2.0.0
Returns
- void
Fires a synthesized event to any registered listeners.
Parameters
- name : String
Name of the event.
- event : Dictionary
A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.
Returns
- void
Returns the matching view of a given view ID.
- 6.1.0
- 6.1.0
- 6.1.0
Parameters
- id : String
The ID of the view that should be returned. Use the
idproperty in your views to enable it for indexing in this method.
Returns
Hides this dialog.
This triggers a click event as if cancel was invoked.
- 0.9
- 0.9
- 0.9
Parameters
- params : hideParams (optional)
Argument containing parameters for this method. Only used on iOS.
Returns
- void
Overrides: Titanium.UI.View.hide
Inserts a view at the specified position in the children array.
Useful if the layout property is set to horizontal or vertical.
- 3.3.0
- 3.3.0
- 3.3.0
Parameters
- params : Dictionary
Pass an object with the following key-value pairs:
view(Titanium.UI.View): View to insertposition(Number): Position in the children array to insert the view. If omitted, inserts the view to the end of the array.
Returns
- void
Removes the specified callback as an event listener for the named event.
Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.
When adding a listener, you must save a reference to the callback function in order to remove the listener later:
var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);
To remove the listener, pass in a reference to the callback function:
window.removeEventListener('click', listener);
Parameters
- name : String
Name of the event.
- callback : Callback<Object>
Callback function to remove. Must be the same function passed to
addEventListener.
Returns
- void
Replaces a view at the specified position in the children array.
Useful if the layout property is set to horizontal or vertical.
- 3.3.0
- 3.3.0
- 3.3.0
Parameters
- params : Dictionary
Pass an object with the following key-value pairs:
view(Titanium.UI.View): View to insertposition(Number): Position in the children array of the view elment to replace.
Returns
- void
Sets the value of the androidView property.
- 0.8
Parameters
- androidView : Titanium.UI.View
New value for the property.
Returns
- void
Sets the value of the bubbleParent property.
- 3.0.0
- 3.0.0
- 3.0.0
Parameters
- bubbleParent : Boolean
New value for the property.
Returns
- void
Sets the value of the buttonNames property.
- 0.8
Parameters
- buttonNames : Array<String>
New value for the property.
Returns
- void
Sets the value of the cancel property.
Parameters
- cancel : Number
New value for the property.
Returns
- void
Sets the value of the destructive property.
- 0.8
- 0.8
Parameters
- destructive : Number
New value for the property.
Returns
- void
Sets the value of the elevation property.
- 5.0.0
Parameters
- elevation : Number
New value for the property.
Returns
- void
Sets the value of the hiddenBehavior property.
- 6.1.0
Parameters
- hiddenBehavior : Number
New value for the property.
Returns
- void
Sets the value of the lifecycleContainer property.
- 3.6.0
Parameters
- lifecycleContainer : Titanium.UI.Window/Titanium.UI.TabGroup
New value for the property.
Returns
- void
Sets the value of the opaquebackground property.
- 3.2.0
- 3.2.0
Parameters
- opaquebackground : Boolean
New value for the property.
Returns
- void
Sets the value of the options property.
Parameters
- options : Array<String>
New value for the property.
Returns
- void
Sets the value of the persistent property.
- 3.0.0
- 3.0.0
- 3.0.0
Parameters
- persistent : Boolean
New value for the property.
Returns
- void
Sets the value of the previewContext property.
- 5.1.0
Parameters
- previewContext : Titanium.UI.iOS.PreviewContext
New value for the property.
Returns
- void
Sets the value of the rotation property.
- 5.4.0
Parameters
- rotation : Number
New value for the property.
Returns
- void
Sets the value of the rotationX property.
- 5.4.0
Parameters
- rotationX : Number
New value for the property.
Returns
- void
Sets the value of the rotationY property.
- 5.4.0
Parameters
- rotationY : Number
New value for the property.
Returns
- void
Sets the value of the scaleX property.
- 5.4.0
Parameters
- scaleX : Number
New value for the property.
Returns
- void
Sets the value of the scaleY property.
- 5.4.0
Parameters
- scaleY : Number
New value for the property.
Returns
- void
Sets the value of the selectedIndex property.
- 0.8
Parameters
- selectedIndex : Number
New value for the property.
Returns
- void
Sets the value of the tintColor property.
- 3.1.3
- 3.1.3
Parameters
- tintColor : String
New value for the property.
Returns
- void
Sets the value of the title property.
Parameters
- title : String
New value for the property.
Returns
- void
Sets the value of the titleid property.
Parameters
- titleid : String
New value for the property.
Returns
- void
Sets the value of the touchFeedback property.
- 6.1.0
Parameters
- touchFeedback : Boolean
New value for the property.
Returns
- void
Sets the value of the touchFeedbackColor property.
- 6.1.0
Parameters
- touchFeedbackColor : String
New value for the property.
Returns
- void
Sets the value of the transitionName property.
- 5.0.2
Parameters
- transitionName : String
New value for the property.
Returns
- void
Sets the value of the translationX property.
- 5.0.0
Parameters
- translationX : Number
New value for the property.
Returns
- void
Sets the value of the translationY property.
- 5.0.0
Parameters
- translationY : Number
New value for the property.
Returns
- void
Sets the value of the translationZ property.
- 5.0.0
Parameters
- translationZ : Number
New value for the property.
Returns
- void
Shows this dialog.
On iPad, this dialog is shown in the middle of the display or, when specified via the
params argument, as a popover-like dialog attached to another view or control.
- 0.9
- 0.9
- 0.9
Parameters
- params : showParams (optional)
Argument containing parameters for this method. Only used on iPad.
Returns
- void
Overrides: Titanium.UI.View.show
Starts a batch update of this view's layout properties.
deprecated since 3.0.0
Use the <Titanium.Proxy.applyProperties> method to batch-update layout properties.
To prevent a layout pass each time a property is modified, call startLayout before
changing any properties that may change this view's layout. This initiates a batch update
mode where layout changes are deferred.
Call finishLayout to end batch update mode and trigger a layout pass. For example:
view.startLayout();
view.top = 50;
view.left = 50;
view.finishLayout();
Note that any property changes made during the batch update may be deferred until
finishLayout is called. This may vary somewhat by platform. For example, changing the
text of a label may trigger a layout pass. In iOS, updating the label text is
deferred.
See also: updateLayout, finishLayout, postlayout event.
- 2.0.0
- 2.0.0
- 2.0.0
Returns
- void
Performs a batch update of all supplied layout properties and schedules a layout pass after they have been updated.
deprecated since 3.0.0
Use the <Titanium.Proxy.applyProperties> method to batch-update layout properties.
This is another way to perform a batch update. The updateLayout method is called with a
dictionary of layout properties to perform the batch update. For example:
view.updateLayout({top:50, left:50});
This is equivalent to the following:
view.startLayout();
view.top = 50;
view.left = 50;
view.finishLayout();
See also: startLayout, finishLayout, postlayout event.
- 2.0.0
- 2.0.0
- 2.0.0
Parameters
- params : Dictionary
Layout properties to be updated.
Returns
- void
Events
Fired when an option of this dialog is clicked or, under certain circumstances, when this dialog is dismissed.
On iOS as of Release 2.0, when the dialog is dismissed without using an option, for example, using
the hide method (iPhone, iPad) or a tap outside of the
dialog (iPad), this event is fired as though the cancel option was selected. In these
circumstances, the index property will be the cancel option index if defined or -1
otherwise.
- 0.9
- 0.9
- 0.9
Properties
- index : Number
Index of the option that was pressed. See description for result of the dialog being dismissed in some other way.
- button : Boolean
Indicates whether the index returned by the
indexproperty relates to a button rather than an option item. - cancel : Boolean/Number
Boolean type on Android; Number on iOS.
On Android, indicates whether the cancel button was clicked, in which case returns
true.On iOS, the value of the cancel property is returned, if defined, or
-1otherwise. - destructive : Number
Index of the destructive option if defined or
-1otherwise. - 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.
Overrides: Titanium.UI.View.click