michael@0: <!---
michael@0:     Licensed to the Apache Software Foundation (ASF) under one
michael@0:     or more contributor license agreements.  See the NOTICE file
michael@0:     distributed with this work for additional information
michael@0:     regarding copyright ownership.  The ASF licenses this file
michael@0:     to you under the Apache License, Version 2.0 (the
michael@0:     "License"); you may not use this file except in compliance
michael@0:     with the License.  You may obtain a copy of the License at
michael@0: 
michael@0:       http://www.apache.org/licenses/LICENSE-2.0
michael@0: 
michael@0:     Unless required by applicable law or agreed to in writing,
michael@0:     software distributed under the License is distributed on an
michael@0:     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
michael@0:     KIND, either express or implied.  See the License for the
michael@0:     specific language governing permissions and limitations
michael@0:     under the License.
michael@0: -->
michael@0: 
michael@0: # org.apache.cordova.dialogs
michael@0: 
michael@0: This plugin provides access to some native dialog UI elements
michael@0: via a global `navigator.notification` object.
michael@0: 
michael@0: Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event.
michael@0: 
michael@0:     document.addEventListener("deviceready", onDeviceReady, false);
michael@0:     function onDeviceReady() {
michael@0:         console.log(navigator.notification);
michael@0:     }
michael@0: 
michael@0: ## Installation
michael@0: 
michael@0:     cordova plugin add org.apache.cordova.dialogs
michael@0: 
michael@0: ## Methods
michael@0: 
michael@0: - `navigator.notification.alert`
michael@0: - `navigator.notification.confirm`
michael@0: - `navigator.notification.prompt`
michael@0: - `navigator.notification.beep`
michael@0: 
michael@0: ## navigator.notification.alert
michael@0: 
michael@0: Shows a custom alert or dialog box.  Most Cordova implementations use a native
michael@0: dialog box for this feature, but some platforms use the browser's `alert`
michael@0: function, which is typically less customizable.
michael@0: 
michael@0:     navigator.notification.alert(message, alertCallback, [title], [buttonName])
michael@0: 
michael@0: - __message__: Dialog message. _(String)_
michael@0: 
michael@0: - __alertCallback__: Callback to invoke when alert dialog is dismissed. _(Function)_
michael@0: 
michael@0: - __title__: Dialog title. _(String)_ (Optional, defaults to `Alert`)
michael@0: 
michael@0: - __buttonName__: Button name. _(String)_ (Optional, defaults to `OK`)
michael@0: 
michael@0: 
michael@0: ### Example
michael@0: 
michael@0:     function alertDismissed() {
michael@0:         // do something
michael@0:     }
michael@0: 
michael@0:     navigator.notification.alert(
michael@0:         'You are the winner!',  // message
michael@0:         alertDismissed,         // callback
michael@0:         'Game Over',            // title
michael@0:         'Done'                  // buttonName
michael@0:     );
michael@0: 
michael@0: ### Supported Platforms
michael@0: 
michael@0: - Amazon Fire OS
michael@0: - Android
michael@0: - BlackBerry 10
michael@0: - Firefox OS
michael@0: - iOS
michael@0: - Tizen
michael@0: - Windows Phone 7 and 8
michael@0: - Windows 8
michael@0: - Windows
michael@0: 
michael@0: ### Windows Phone 7 and 8 Quirks
michael@0: 
michael@0: - There is no built-in browser alert, but you can bind one as follows to call `alert()` in the global scope:
michael@0: 
michael@0:         window.alert = navigator.notification.alert;
michael@0: 
michael@0: - Both `alert` and `confirm` are non-blocking calls, results of which are only available asynchronously.
michael@0: 
michael@0: ### Firefox OS Quirks:
michael@0: 
michael@0: Both native-blocking `window.alert()` and non-blocking `navigator.notification.alert()` are available.
michael@0: 
michael@0: ### BlackBerry 10 Quirks
michael@0: `navigator.notification.alert('text', callback, 'title', 'text')` callback parameter is passed the number 1.
michael@0: 
michael@0: ## navigator.notification.confirm
michael@0: 
michael@0: Displays a customizable confirmation dialog box.
michael@0: 
michael@0:     navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])
michael@0: 
michael@0: - __message__: Dialog message. _(String)_
michael@0: 
michael@0: - __confirmCallback__: Callback to invoke with index of button pressed (1, 2, or 3) or when the dialog is dismissed without a button press (0). _(Function)_
michael@0: 
michael@0: - __title__: Dialog title. _(String)_ (Optional, defaults to `Confirm`)
michael@0: 
michael@0: - __buttonLabels__: Array of strings specifying button labels. _(Array)_  (Optional, defaults to [`OK,Cancel`])
michael@0: 
michael@0: 
michael@0: ### confirmCallback
michael@0: 
michael@0: The `confirmCallback` executes when the user presses one of the
michael@0: buttons in the confirmation dialog box.
michael@0: 
michael@0: The callback takes the argument `buttonIndex` _(Number)_, which is the
michael@0: index of the pressed button. Note that the index uses one-based
michael@0: indexing, so the value is `1`, `2`, `3`, etc.
michael@0: 
michael@0: ### Example
michael@0: 
michael@0:     function onConfirm(buttonIndex) {
michael@0:         alert('You selected button ' + buttonIndex);
michael@0:     }
michael@0: 
michael@0:     navigator.notification.confirm(
michael@0:         'You are the winner!', // message
michael@0:          onConfirm,            // callback to invoke with index of button pressed
michael@0:         'Game Over',           // title
michael@0:         ['Restart','Exit']     // buttonLabels
michael@0:     );
michael@0: 
michael@0: ### Supported Platforms
michael@0: 
michael@0: - Amazon Fire OS
michael@0: - Android
michael@0: - BlackBerry 10
michael@0: - Firefox OS
michael@0: - iOS
michael@0: - Tizen
michael@0: - Windows Phone 7 and 8
michael@0: - Windows 8
michael@0: - Windows
michael@0: 
michael@0: ### Windows Phone 7 and 8 Quirks
michael@0: 
michael@0: - There is no built-in browser function for `window.confirm`, but you can bind it by assigning:
michael@0: 
michael@0:         window.confirm = navigator.notification.confirm;
michael@0: 
michael@0: - Calls to `alert` and `confirm` are non-blocking, so the result is only available asynchronously.
michael@0: 
michael@0: ### Windows Quirks
michael@0: 
michael@0: - On Windows8/8.1 it is not possible to add more than three buttons to MessageDialog instance.
michael@0: 
michael@0: - On Windows Phone 8.1 it's not possible to show dialog with more than two buttons.
michael@0: 
michael@0: ### Firefox OS Quirks:
michael@0: 
michael@0: Both native-blocking `window.confirm()` and non-blocking `navigator.notification.confirm()` are available.
michael@0: 
michael@0: ## navigator.notification.prompt
michael@0: 
michael@0: Displays a native dialog box that is more customizable than the browser's `prompt` function.
michael@0: 
michael@0:     navigator.notification.prompt(message, promptCallback, [title], [buttonLabels], [defaultText])
michael@0: 
michael@0: - __message__: Dialog message. _(String)_
michael@0: 
michael@0: - __promptCallback__: Callback to invoke with index of button pressed (1, 2, or 3) or when the dialog is dismissed without a button press (0). _(Function)_
michael@0: 
michael@0: - __title__: Dialog title _(String)_ (Optional, defaults to `Prompt`)
michael@0: 
michael@0: - __buttonLabels__: Array of strings specifying button labels _(Array)_ (Optional, defaults to `["OK","Cancel"]`)
michael@0: 
michael@0: - __defaultText__: Default textbox input value (`String`) (Optional, Default: empty string)
michael@0: 
michael@0: ### promptCallback
michael@0: 
michael@0: The `promptCallback` executes when the user presses one of the buttons
michael@0: in the prompt dialog box. The `results` object passed to the callback
michael@0: contains the following properties:
michael@0: 
michael@0: - __buttonIndex__: The index of the pressed button. _(Number)_ Note that the index uses one-based indexing, so the value is `1`, `2`, `3`, etc.
michael@0: 
michael@0: 
michael@0: 
michael@0: - __input1__: The text entered in the prompt dialog box. _(String)_
michael@0: 
michael@0: ### Example
michael@0: 
michael@0:     function onPrompt(results) {
michael@0:         alert("You selected button number " + results.buttonIndex + " and entered " + results.input1);
michael@0:     }
michael@0: 
michael@0:     navigator.notification.prompt(
michael@0:         'Please enter your name',  // message
michael@0:         onPrompt,                  // callback to invoke
michael@0:         'Registration',            // title
michael@0:         ['Ok','Exit'],             // buttonLabels
michael@0:         'Jane Doe'                 // defaultText
michael@0:     );
michael@0: 
michael@0: ### Supported Platforms
michael@0: 
michael@0: - Amazon Fire OS
michael@0: - Android
michael@0: - Firefox OS
michael@0: - iOS
michael@0: - Windows Phone 7 and 8
michael@0: 
michael@0: ### Android Quirks
michael@0: 
michael@0: - Android supports a maximum of three buttons, and ignores any more than that.
michael@0: 
michael@0: - On Android 3.0 and later, buttons are displayed in reverse order for devices that use the Holo theme.
michael@0: 
michael@0: ### Firefox OS Quirks:
michael@0: 
michael@0: Both native-blocking `window.prompt()` and non-blocking `navigator.notification.prompt()` are available.
michael@0: 
michael@0: ## navigator.notification.beep
michael@0: 
michael@0: The device plays a beep sound.
michael@0: 
michael@0:     navigator.notification.beep(times);
michael@0: 
michael@0: - __times__: The number of times to repeat the beep. _(Number)_
michael@0: 
michael@0: ### Example
michael@0: 
michael@0:     // Beep twice!
michael@0:     navigator.notification.beep(2);
michael@0: 
michael@0: ### Supported Platforms
michael@0: 
michael@0: - Amazon Fire OS
michael@0: - Android
michael@0: - BlackBerry 10
michael@0: - iOS
michael@0: - Tizen
michael@0: - Windows Phone 7 and 8
michael@0: - Windows 8
michael@0: 
michael@0: ### Amazon Fire OS Quirks
michael@0: 
michael@0: - Amazon Fire OS plays the default __Notification Sound__ specified under the __Settings/Display & Sound__ panel.
michael@0: 
michael@0: ### Android Quirks
michael@0: 
michael@0: - Android plays the default __Notification ringtone__ specified under the __Settings/Sound & Display__ panel.
michael@0: 
michael@0: ### Windows Phone 7 and 8 Quirks
michael@0: 
michael@0: - Relies on a generic beep file from the Cordova distribution.
michael@0: 
michael@0: ### Tizen Quirks
michael@0: 
michael@0: - Tizen implements beeps by playing an audio file via the media API.
michael@0: 
michael@0: - The beep file must be short, must be located in a `sounds` subdirectory of the application's root directory, and must be named `beep.wav`.
michael@0: