# Titanium.UI.OptionDialog

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

- Source: https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.UI.OptionDialog
- Titanium SDK version: 12.6.3
- Kind: view
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.8
- Extends: Titanium.UI.View
- Inheritance: Titanium.UI.View > Titanium.Proxy

| Android | iPhone | iPad |
| ------- | ------ | ---- |
| ![Android](./optiondialog_android.png) | ![iPhone](./optiondialog_iphone.png) | ![iPad](./optiondialog_ipad.png) |

An option dialog is created using [Titanium.UI.createOptionDialog](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#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](https://titaniumsdk.com/docs/sdk/Titanium.UI.View.md) to the [Titanium.UI.OptionDialog.androidView](https://titaniumsdk.com/docs/sdk/Titanium.UI.OptionDialog.md#androidView) property
to define a custom dialog UI and layout, or you can assign a set of options to the
[Titanium.UI.OptionDialog.options](https://titaniumsdk.com/docs/sdk/Titanium.UI.OptionDialog.md#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. 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.

## Example: Dialog with 3 Options

``` js
Ti.UI.backgroundColor = '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();
```

## Example: Dialog with 2 Options and 1 Button on Android and 3 Options on iOS

``` js
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();
```

## Example: Alloy XML Markup

Previous example as an Alloy view. You can set [cancel](Titanium.UI.OptionDialog.cancel)
and [destructive](Titanium.UI.OptionDialog.destructive) on a `<Option/>` tag.

optiondialog.xml:
``` 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 destructive="true">Confirm</Option>
                <Option platform="ios">Help</Option>
                <Option cancel="true">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:
``` js
function showOptions(){
    $.dialog.show();
}
```

## Properties

### androidView

- Type: Titanium.UI.View
- Platforms: Android

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
[Titanium.UI.OptionDialog.options](https://titaniumsdk.com/docs/sdk/Titanium.UI.OptionDialog.md#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:

``` xml
<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>
```

### buttonNames

- Type: Array<String>
- Platforms: Android

List of button names.

This property creates buttons underneath the picker options.
The dialog only supports up to three buttons.

### cancel

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Default: `undefined (Android), -1 (iOS)`

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](https://titaniumsdk.com/docs/sdk/Titanium.UI.OptionDialog.md#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.

### destructive

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `-1`

Index to define the destructive option, indicated by a visual cue when rendered.

### opaquebackground

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.2.0
- Default: `false`

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.

### options

- Type: Array<String>
- Platforms: Android, iPhone, iPad, macOS

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  [Titanium.UI.OptionDialog.androidView](https://titaniumsdk.com/docs/sdk/Titanium.UI.OptionDialog.md#androidView) property, but not both.
If you do, the custom view will appear but not the options you defined.

### persistent

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.0.0
- Default: `true`

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.

### selectedIndex

- Type: Number
- Platforms: Android

Defines the default selected option. Since `8.1.0`, if not defined or -1 it will show a normal list instead of radio buttons.

### title

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Title of the dialog.

### titleid

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Key identifying a string in the locale file to use for the title text.

## Methods

### hide

- Platforms: Android, iPhone, iPad, macOS

Hides this dialog.

This triggers a `click` event as if cancel was invoked.

Parameters:

- `params` (hideParams, optional): Argument containing parameters for this method. Only used on iOS.

### show

- Platforms: Android, iPhone, iPad, macOS

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.

Parameters:

- `params` (showParams, optional): Argument containing parameters for this method. Only used on iPad.

## Events

### click

- Platforms: Android, iPhone, iPad, macOS

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](https://titaniumsdk.com/docs/sdk/Titanium.UI.OptionDialog.md#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.

Event 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 `index` property 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](https://titaniumsdk.com/docs/sdk/Titanium.UI.OptionDialog.md#cancel) property is returned, if defined, or `-1` otherwise.
- `destructive` (Number): Index of the destructive option if defined or `-1` otherwise.

## Inherited members

32 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`
- [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.UI.View.md): `accessibilityDisableLongPress`, `clearMotionEffects`, `elevation`, `filterTouchesWhenObscured`, `getViewById`, `hiddenBehavior`, `horizontalMotionEffect`, `id`, `insertAt`, `previewContext`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `stopAnimation`, `tintColor`, `tooltip`, `touchFeedback`, `touchFeedbackColor`, `transitionName`, `translationX`, `translationY`, `translationZ`, `verticalMotionEffect`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.