1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Touchgui/plugins/org.apache.cordova.dialogs/doc/index.md Thu Jun 04 14:50:33 2015 +0200
1.3 @@ -0,0 +1,267 @@
1.4 +<!---
1.5 + Licensed to the Apache Software Foundation (ASF) under one
1.6 + or more contributor license agreements. See the NOTICE file
1.7 + distributed with this work for additional information
1.8 + regarding copyright ownership. The ASF licenses this file
1.9 + to you under the Apache License, Version 2.0 (the
1.10 + "License"); you may not use this file except in compliance
1.11 + with the License. You may obtain a copy of the License at
1.12 +
1.13 + http://www.apache.org/licenses/LICENSE-2.0
1.14 +
1.15 + Unless required by applicable law or agreed to in writing,
1.16 + software distributed under the License is distributed on an
1.17 + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1.18 + KIND, either express or implied. See the License for the
1.19 + specific language governing permissions and limitations
1.20 + under the License.
1.21 +-->
1.22 +
1.23 +# org.apache.cordova.dialogs
1.24 +
1.25 +This plugin provides access to some native dialog UI elements
1.26 +via a global `navigator.notification` object.
1.27 +
1.28 +Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event.
1.29 +
1.30 + document.addEventListener("deviceready", onDeviceReady, false);
1.31 + function onDeviceReady() {
1.32 + console.log(navigator.notification);
1.33 + }
1.34 +
1.35 +## Installation
1.36 +
1.37 + cordova plugin add org.apache.cordova.dialogs
1.38 +
1.39 +## Methods
1.40 +
1.41 +- `navigator.notification.alert`
1.42 +- `navigator.notification.confirm`
1.43 +- `navigator.notification.prompt`
1.44 +- `navigator.notification.beep`
1.45 +
1.46 +## navigator.notification.alert
1.47 +
1.48 +Shows a custom alert or dialog box. Most Cordova implementations use a native
1.49 +dialog box for this feature, but some platforms use the browser's `alert`
1.50 +function, which is typically less customizable.
1.51 +
1.52 + navigator.notification.alert(message, alertCallback, [title], [buttonName])
1.53 +
1.54 +- __message__: Dialog message. _(String)_
1.55 +
1.56 +- __alertCallback__: Callback to invoke when alert dialog is dismissed. _(Function)_
1.57 +
1.58 +- __title__: Dialog title. _(String)_ (Optional, defaults to `Alert`)
1.59 +
1.60 +- __buttonName__: Button name. _(String)_ (Optional, defaults to `OK`)
1.61 +
1.62 +
1.63 +### Example
1.64 +
1.65 + function alertDismissed() {
1.66 + // do something
1.67 + }
1.68 +
1.69 + navigator.notification.alert(
1.70 + 'You are the winner!', // message
1.71 + alertDismissed, // callback
1.72 + 'Game Over', // title
1.73 + 'Done' // buttonName
1.74 + );
1.75 +
1.76 +### Supported Platforms
1.77 +
1.78 +- Amazon Fire OS
1.79 +- Android
1.80 +- BlackBerry 10
1.81 +- Firefox OS
1.82 +- iOS
1.83 +- Tizen
1.84 +- Windows Phone 7 and 8
1.85 +- Windows 8
1.86 +- Windows
1.87 +
1.88 +### Windows Phone 7 and 8 Quirks
1.89 +
1.90 +- There is no built-in browser alert, but you can bind one as follows to call `alert()` in the global scope:
1.91 +
1.92 + window.alert = navigator.notification.alert;
1.93 +
1.94 +- Both `alert` and `confirm` are non-blocking calls, results of which are only available asynchronously.
1.95 +
1.96 +### Firefox OS Quirks:
1.97 +
1.98 +Both native-blocking `window.alert()` and non-blocking `navigator.notification.alert()` are available.
1.99 +
1.100 +### BlackBerry 10 Quirks
1.101 +`navigator.notification.alert('text', callback, 'title', 'text')` callback parameter is passed the number 1.
1.102 +
1.103 +## navigator.notification.confirm
1.104 +
1.105 +Displays a customizable confirmation dialog box.
1.106 +
1.107 + navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])
1.108 +
1.109 +- __message__: Dialog message. _(String)_
1.110 +
1.111 +- __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)_
1.112 +
1.113 +- __title__: Dialog title. _(String)_ (Optional, defaults to `Confirm`)
1.114 +
1.115 +- __buttonLabels__: Array of strings specifying button labels. _(Array)_ (Optional, defaults to [`OK,Cancel`])
1.116 +
1.117 +
1.118 +### confirmCallback
1.119 +
1.120 +The `confirmCallback` executes when the user presses one of the
1.121 +buttons in the confirmation dialog box.
1.122 +
1.123 +The callback takes the argument `buttonIndex` _(Number)_, which is the
1.124 +index of the pressed button. Note that the index uses one-based
1.125 +indexing, so the value is `1`, `2`, `3`, etc.
1.126 +
1.127 +### Example
1.128 +
1.129 + function onConfirm(buttonIndex) {
1.130 + alert('You selected button ' + buttonIndex);
1.131 + }
1.132 +
1.133 + navigator.notification.confirm(
1.134 + 'You are the winner!', // message
1.135 + onConfirm, // callback to invoke with index of button pressed
1.136 + 'Game Over', // title
1.137 + ['Restart','Exit'] // buttonLabels
1.138 + );
1.139 +
1.140 +### Supported Platforms
1.141 +
1.142 +- Amazon Fire OS
1.143 +- Android
1.144 +- BlackBerry 10
1.145 +- Firefox OS
1.146 +- iOS
1.147 +- Tizen
1.148 +- Windows Phone 7 and 8
1.149 +- Windows 8
1.150 +- Windows
1.151 +
1.152 +### Windows Phone 7 and 8 Quirks
1.153 +
1.154 +- There is no built-in browser function for `window.confirm`, but you can bind it by assigning:
1.155 +
1.156 + window.confirm = navigator.notification.confirm;
1.157 +
1.158 +- Calls to `alert` and `confirm` are non-blocking, so the result is only available asynchronously.
1.159 +
1.160 +### Windows Quirks
1.161 +
1.162 +- On Windows8/8.1 it is not possible to add more than three buttons to MessageDialog instance.
1.163 +
1.164 +- On Windows Phone 8.1 it's not possible to show dialog with more than two buttons.
1.165 +
1.166 +### Firefox OS Quirks:
1.167 +
1.168 +Both native-blocking `window.confirm()` and non-blocking `navigator.notification.confirm()` are available.
1.169 +
1.170 +## navigator.notification.prompt
1.171 +
1.172 +Displays a native dialog box that is more customizable than the browser's `prompt` function.
1.173 +
1.174 + navigator.notification.prompt(message, promptCallback, [title], [buttonLabels], [defaultText])
1.175 +
1.176 +- __message__: Dialog message. _(String)_
1.177 +
1.178 +- __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)_
1.179 +
1.180 +- __title__: Dialog title _(String)_ (Optional, defaults to `Prompt`)
1.181 +
1.182 +- __buttonLabels__: Array of strings specifying button labels _(Array)_ (Optional, defaults to `["OK","Cancel"]`)
1.183 +
1.184 +- __defaultText__: Default textbox input value (`String`) (Optional, Default: empty string)
1.185 +
1.186 +### promptCallback
1.187 +
1.188 +The `promptCallback` executes when the user presses one of the buttons
1.189 +in the prompt dialog box. The `results` object passed to the callback
1.190 +contains the following properties:
1.191 +
1.192 +- __buttonIndex__: The index of the pressed button. _(Number)_ Note that the index uses one-based indexing, so the value is `1`, `2`, `3`, etc.
1.193 +
1.194 +
1.195 +
1.196 +- __input1__: The text entered in the prompt dialog box. _(String)_
1.197 +
1.198 +### Example
1.199 +
1.200 + function onPrompt(results) {
1.201 + alert("You selected button number " + results.buttonIndex + " and entered " + results.input1);
1.202 + }
1.203 +
1.204 + navigator.notification.prompt(
1.205 + 'Please enter your name', // message
1.206 + onPrompt, // callback to invoke
1.207 + 'Registration', // title
1.208 + ['Ok','Exit'], // buttonLabels
1.209 + 'Jane Doe' // defaultText
1.210 + );
1.211 +
1.212 +### Supported Platforms
1.213 +
1.214 +- Amazon Fire OS
1.215 +- Android
1.216 +- Firefox OS
1.217 +- iOS
1.218 +- Windows Phone 7 and 8
1.219 +
1.220 +### Android Quirks
1.221 +
1.222 +- Android supports a maximum of three buttons, and ignores any more than that.
1.223 +
1.224 +- On Android 3.0 and later, buttons are displayed in reverse order for devices that use the Holo theme.
1.225 +
1.226 +### Firefox OS Quirks:
1.227 +
1.228 +Both native-blocking `window.prompt()` and non-blocking `navigator.notification.prompt()` are available.
1.229 +
1.230 +## navigator.notification.beep
1.231 +
1.232 +The device plays a beep sound.
1.233 +
1.234 + navigator.notification.beep(times);
1.235 +
1.236 +- __times__: The number of times to repeat the beep. _(Number)_
1.237 +
1.238 +### Example
1.239 +
1.240 + // Beep twice!
1.241 + navigator.notification.beep(2);
1.242 +
1.243 +### Supported Platforms
1.244 +
1.245 +- Amazon Fire OS
1.246 +- Android
1.247 +- BlackBerry 10
1.248 +- iOS
1.249 +- Tizen
1.250 +- Windows Phone 7 and 8
1.251 +- Windows 8
1.252 +
1.253 +### Amazon Fire OS Quirks
1.254 +
1.255 +- Amazon Fire OS plays the default __Notification Sound__ specified under the __Settings/Display & Sound__ panel.
1.256 +
1.257 +### Android Quirks
1.258 +
1.259 +- Android plays the default __Notification ringtone__ specified under the __Settings/Sound & Display__ panel.
1.260 +
1.261 +### Windows Phone 7 and 8 Quirks
1.262 +
1.263 +- Relies on a generic beep file from the Cordova distribution.
1.264 +
1.265 +### Tizen Quirks
1.266 +
1.267 +- Tizen implements beeps by playing an audio file via the media API.
1.268 +
1.269 +- 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`.
1.270 +
