<commit_before>---
name: Titanium.UI.AlertDialog
summary: |
    An alert dialog is a modal view that includes an optional title, a message and buttons, 
    positioned in the middle of the display.
description: |
    <table id="platformComparison">
      <tr>
        <td><img src="images/alertdialog/alertdialog_android.png" height="75" /></td>
        <td><img src="images/alertdialog/alertdialog_ios.png" height="75" /></td>
        <td><img src="images/alertdialog/alertdialog_mobileweb.png" height="75" /></td>
      </tr>
      <tr><th>Android</th><th>iOS</th><th>Mobile Web</th></tr>
    </table>
    
    An alert dialog is created using <Titanium.UI.createAlertDialog> or **`<AlertDialog>`** Alloy element.
    
    Although this dialog always appears in the middle of the display (not touching the edges), 
    other aspects of its aesthetics and the way the user interacts with it are different for each 
    platform, as described below.

    #### Android
    
    On Android, the default alert dialog displays text information, via a title and message, without 
    any buttons. As the user can use the system hardware `back` button to dismiss it, a button is 
    optional.
    
    Buttons are shown if the `buttonNames` property is defined, and are rendered horizontally below 
    the message.

    To create a custom layout, a view may be added and, in turn, a hierarchy of views added to that 
    child view.
    
    #### iOS
    
    On iOS, the default alert dialog displays text information, via a title and message, with 
    a single button to allow it to be dismissed.
    
    Buttons are defined using the `buttonNames` property and are rendered vertically below 
    the message.

    On iOS 4.0 and later, alert dialogs are automatically cancelled when the application is 
    paused/suspended. This behavior can avoided by setting `persistent` property on alert dialog 
    to be `true`.

    On iOS 5.0 and later, `style` property can be used to allow the user to enter plain text, 
    obscured text or login identifier and password. Entered values can be captured with listening
    `cancel` event.
    
    #### Global Alias
    
    A global method `alert()` is aliased to this object, and can be invoked with a single message. 
    For example
    
        alert('this is a message');
    
    This will generate an alert with a title of "Alert" and an "OK" button.
    
    #### Caveats
    
    Multiple alerts should not be shown at once.
    
    The `title` and `ok` properties cannot be changed while the alert dialog is being displayed. On
    Android only, you can change the `message` property while the alert dialog is being displayed.
extends: Titanium.Proxy
since: "0.8"

events:
  - name: click
    summary: Fired when a button in the dialog is clicked.

    properties:
      - name: cancel
        summary: |
            Boolean type on Android and Mobile Web; Number on iOS. 
            
            On Android and Mobile Web, indicates whether the cancel button was clicked, in which 
            case returns `true`. 
            
            On iOS, the value of the [cancel](Titanium.UI.AlertDialog.cancel) property is 
            returned, if defined, or `-1` otherwise. 
            
            See the `Three-button Alert Dialog` example for a cross-platform workaround for this 
            parity issue.
        type: [Boolean, Number]
        
      - name: index
        summary: Index of the button that was clicked.
        type: Number

      - name: login
        summary: |
            Value of login field if dialog `style` property is defined as 
            <Titanium.UI.iPhone.AlertDialogStyle.LOGIN_AND_PASSWORD_INPUT>.
        type: String
        platforms: [iphone, ipad]

      - name: password
        summary: |
            Value of password field if dialog `style` property is defined as 
            <Titanium.UI.iPhone.AlertDialogStyle.LOGIN_AND_PASSWORD_INPUT>.
        type: String
        platforms: [iphone, ipad]

      - name: text
        summary: |
            Value of text field if dialog `style` property is defined as
            <Titanium.UI.iPhone.AlertDialogStyle.PLAIN_TEXT_INPUT> or 
            <Titanium.UI.iPhone.AlertDialogStyle.SECURE_TEXT_INPUT>.
        type: String
        platforms: [iphone, ipad]

methods:
  - name: show
    summary: Shows this dialog.

  - name: hide
    summary: Hides this dialog.

properties:
  - name: androidView
    summary: View to load inside the message area, to create a custom layout.
    description: |
        In an Alloy application you can specify this property with either an `<AndroidView/>` or
        `<View/>` element inside the `<AlertDialog/>` element, for example:

            <Alloy>
                <AlertDialog onClick="doClick" title="Delete"
                    message="Would you like to delete the file?" cancel="1">

                    <!--  Add View or AndroidView for the androidView property  -->
                    <View platform="android">
                        <Label color="red" text="Warning!  This change is permanent and you cannot undo it!" />
                    </View>

                    <ButtonNames>
                        <ButtonName>Confirm</ButtonName>
                        <ButtonName>Cancel</ButtonName>
                    </ButtonNames>
                </AlertDialog>
            </Alloy>

    type: Titanium.UI.View
    platforms: [android]
    accessors: false
    
  - name: buttonNames
    summary: Name of each button to create.

    description: |
        On iOS, a button will automatically be created if none are explicitly defined, because 
        without it users would be unable to dismiss the dialog. Conversely, a dialog with no 
        buttons may be created on Android, as the hardware `back` button may be used instead.
        
        A maximum of 3 buttons is supported on Android.

        Alloy applications can specify this property with a `<ButtonNames>` element containing
        one or more `<ButtonName>` elements (see example).

            <Alloy>
                <AlertDialog id="dialog" onClick="doClick" title="Decide!" message="Do you really want to do that?" cancel="1">
                    <ButtonNames>
                        <ButtonName>Confirm</ButtonName>
                        <ButtonName>Cancel</ButtonName>
                        <ButtonName>Help</ButtonName>
                    </ButtonNames>
                </AlertDialog>
            </Alloy>

    type: Array<String>
    default: No buttons (Android), Single "OK" button (iOS, Mobile Web)
    availability: creation

  - name: cancel
    summary: Index to define the cancel button.

    description: |
        On iOS and Mobile Web, set to `-1` to disable the cancel option.
    type: Number
    default: undefined (Android), -1 (iOS, Mobile Web)
    
  - name: message
    summary: Dialog message.
    type: String
<commit_msg>TC-5357: Update documentation<commit_after>---
name: Titanium.UI.AlertDialog
summary: |
    An alert dialog is a modal view that includes an optional title, a message and buttons, 
    positioned in the middle of the display.
description: |
    <table id="platformComparison">
      <tr>
        <td><img src="images/alertdialog/alertdialog_android.png" height="75" /></td>
        <td><img src="images/alertdialog/alertdialog_ios.png" height="75" /></td>
        <td><img src="images/alertdialog/alertdialog_mobileweb.png" height="75" /></td>
      </tr>
      <tr><th>Android</th><th>iOS</th><th>Mobile Web</th></tr>
    </table>
    
    An alert dialog is created using <Titanium.UI.createAlertDialog> or **`<AlertDialog>`** Alloy element.
    
    Although this dialog always appears in the middle of the display (not touching the edges), 
    other aspects of its aesthetics and the way the user interacts with it are different for each 
    platform, as described below.

    #### Android
    
    On Android, the default alert dialog displays text information, via a title and message, without 
    any buttons. As the user can use the system hardware `back` button to dismiss it, a button is 
    optional.
    
    Buttons are shown if the `buttonNames` property is defined, and are rendered horizontally below 
    the message.

    To create a custom layout, a view may be added and, in turn, a hierarchy of views added to that 
    child view.
    
    #### iOS
    
    On iOS, the default alert dialog displays text information, via a title and message, with 
    a single button to allow it to be dismissed.
    
    Buttons are defined using the `buttonNames` property and are rendered vertically below 
    the message.

    On iOS 4.0 and later, alert dialogs are automatically cancelled when the application is 
    paused/suspended. This behavior can avoided by setting `persistent` property on alert dialog 
    to be `true`.

    On iOS 5.0 and later, `style` property can be used to allow the user to enter plain text, 
    obscured text or login identifier and password. Entered values can be captured with listening
    `cancel` event.
    
    #### Global Alias
    
    A global method `alert()` is aliased to this object, and can be invoked with a single message. 
    For example
    
        alert('this is a message');
    
    This will generate an alert with a title of "Alert" and an "OK" button.
    
    #### Caveats
    
    Multiple alerts should not be shown at once.
    
    The `title` and `ok` properties cannot be changed while the alert dialog is being displayed. On
    Android only, you can change the `message` property while the alert dialog is being displayed.
extends: Titanium.Proxy
since: "0.8"

events:
  - name: click
    summary: Fired when a button in the dialog is clicked.

    properties:
      - name: cancel
        summary: |
            Boolean type on Android and Mobile Web; Number on iOS. 
            
            On Android and Mobile Web, indicates whether the cancel button was clicked, in which 
            case returns `true`. 
            
            On iOS, the value of the [cancel](Titanium.UI.AlertDialog.cancel) property is 
            returned, if defined, or `-1` otherwise. 
            
            See the `Three-button Alert Dialog` example for a cross-platform workaround for this 
            parity issue.
        type: [Boolean, Number]
        
      - name: index
        summary: Index of the button that was clicked.
        type: Number

      - name: login
        summary: |
            Value of login field if dialog `style` property is defined as 
            <Titanium.UI.iPhone.AlertDialogStyle.LOGIN_AND_PASSWORD_INPUT>.
        type: String
        platforms: [iphone, ipad]

      - name: password
        summary: |
            Value of password field if dialog `style` property is defined as 
            <Titanium.UI.iPhone.AlertDialogStyle.LOGIN_AND_PASSWORD_INPUT>.
        type: String
        platforms: [iphone, ipad]

      - name: text
        summary: |
            Value of text field if dialog `style` property is defined as
            <Titanium.UI.iPhone.AlertDialogStyle.PLAIN_TEXT_INPUT> or 
            <Titanium.UI.iPhone.AlertDialogStyle.SECURE_TEXT_INPUT>.
        type: String
        platforms: [iphone, ipad]

methods:
  - name: show
    summary: Shows this dialog.

  - name: hide
    summary: Hides this dialog.

properties:
  - name: androidView
    summary: View to load inside the message area, to create a custom layout.
    description: |
        In an Alloy application you can specify this property with either an `<AndroidView/>` or
        `<View/>` element inside the `<AlertDialog/>` element, for example:

            <Alloy>
                <AlertDialog onClick="doClick" title="Delete"
                    message="Would you like to delete the file?" cancel="1">

                    <!--  Add View or AndroidView for the androidView property  -->
                    <View platform="android">
                        <Label color="red" text="Warning!  This change is permanent and you cannot undo it!" />
                    </View>

                    <ButtonNames>
                        <ButtonName>Confirm</ButtonName>
                        <ButtonName>Cancel</ButtonName>
                    </ButtonNames>
                </AlertDialog>
            </Alloy>

    type: Titanium.UI.View
    platforms: [android]
    accessors: false
    
  - name: buttonNames
    summary: Name of each button to create.

    description: |
        On iOS, a button will automatically be created if none are explicitly defined, because 
        without it users would be unable to dismiss the dialog. Conversely, a dialog with no 
        buttons may be created on Android, as the hardware `back` button may be used instead.
        
        A maximum of 3 buttons is supported on Android.

        Alloy applications can specify this property with a `<ButtonNames>` element containing
        one or more `<ButtonName>` elements (see example).

            <Alloy>
                <AlertDialog id="dialog" onClick="doClick" title="Decide!" message="Do you really want to do that?" cancel="1">
                    <ButtonNames>
                        <ButtonName>Confirm</ButtonName>
                        <ButtonName>Cancel</ButtonName>
                        <ButtonName>Help</ButtonName>
                    </ButtonNames>
                </AlertDialog>
            </Alloy>

    type: Array<String>
    default: No buttons (Android), Single "OK" button (iOS, Mobile Web)
    availability: creation

  - name: cancel
    summary: Index to define the cancel button.

    description: |
        On iOS and Mobile Web, set to `-1` to disable the cancel option.
    type: Number
    default: undefined (Android), -1 (iOS, Mobile Web)

  - name: destructive
    summary: Index to define the destructive button.
    platforms: [iphone, ipad]
    description: |
        Note that this property available on iOS SDK 8 or above. 
    type: Number
    default: -1
    
  - name: message
    summary: Dialog message.
    type: String

{'fraction_non_alphanumeric': 0.07602836879432624, 'fraction_numerical': 0.0029787234042553193, 'mean_word_length': 2.1946080652469417, 'pattern_counts': {'":': 0, '<': 121, '<?xml version=': 0, '>': 121, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1863893', 'n_tokens_mistral': 3705, 'n_tokens_neox': 3517, 'n_words': 1544}