comparison: Touchgui/plugins/org.apache.cordova.dialogs/doc/index.md
Touchgui/plugins/org.apache.cordova.dialogs/doc/index.md
- changeset 0
- e8ccd40d0ef6
equal
deleted
inserted
replaced
| -1:000000000000 | 0:ec14024af899 |
|---|---|
| 1 <!--- | |
| 2 Licensed to the Apache Software Foundation (ASF) under one | |
| 3 or more contributor license agreements. See the NOTICE file | |
| 4 distributed with this work for additional information | |
| 5 regarding copyright ownership. The ASF licenses this file | |
| 6 to you under the Apache License, Version 2.0 (the | |
| 7 "License"); you may not use this file except in compliance | |
| 8 with the License. You may obtain a copy of the License at | |
| 9 | |
| 10 http://www.apache.org/licenses/LICENSE-2.0 | |
| 11 | |
| 12 Unless required by applicable law or agreed to in writing, | |
| 13 software distributed under the License is distributed on an | |
| 14 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| 15 KIND, either express or implied. See the License for the | |
| 16 specific language governing permissions and limitations | |
| 17 under the License. | |
| 18 --> | |
| 19 | |
| 20 # org.apache.cordova.dialogs | |
| 21 | |
| 22 This plugin provides access to some native dialog UI elements | |
| 23 via a global `navigator.notification` object. | |
| 24 | |
| 25 Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event. | |
| 26 | |
| 27 document.addEventListener("deviceready", onDeviceReady, false); | |
| 28 function onDeviceReady() { | |
| 29 console.log(navigator.notification); | |
| 30 } | |
| 31 | |
| 32 ## Installation | |
| 33 | |
| 34 cordova plugin add org.apache.cordova.dialogs | |
| 35 | |
| 36 ## Methods | |
| 37 | |
| 38 - `navigator.notification.alert` | |
| 39 - `navigator.notification.confirm` | |
| 40 - `navigator.notification.prompt` | |
| 41 - `navigator.notification.beep` | |
| 42 | |
| 43 ## navigator.notification.alert | |
| 44 | |
| 45 Shows a custom alert or dialog box. Most Cordova implementations use a native | |
| 46 dialog box for this feature, but some platforms use the browser's `alert` | |
| 47 function, which is typically less customizable. | |
| 48 | |
| 49 navigator.notification.alert(message, alertCallback, [title], [buttonName]) | |
| 50 | |
| 51 - __message__: Dialog message. _(String)_ | |
| 52 | |
| 53 - __alertCallback__: Callback to invoke when alert dialog is dismissed. _(Function)_ | |
| 54 | |
| 55 - __title__: Dialog title. _(String)_ (Optional, defaults to `Alert`) | |
| 56 | |
| 57 - __buttonName__: Button name. _(String)_ (Optional, defaults to `OK`) | |
| 58 | |
| 59 | |
| 60 ### Example | |
| 61 | |
| 62 function alertDismissed() { | |
| 63 // do something | |
| 64 } | |
| 65 | |
| 66 navigator.notification.alert( | |
| 67 'You are the winner!', // message | |
| 68 alertDismissed, // callback | |
| 69 'Game Over', // title | |
| 70 'Done' // buttonName | |
| 71 ); | |
| 72 | |
| 73 ### Supported Platforms | |
| 74 | |
| 75 - Amazon Fire OS | |
| 76 - Android | |
| 77 - BlackBerry 10 | |
| 78 - Firefox OS | |
| 79 - iOS | |
| 80 - Tizen | |
| 81 - Windows Phone 7 and 8 | |
| 82 - Windows 8 | |
| 83 - Windows | |
| 84 | |
| 85 ### Windows Phone 7 and 8 Quirks | |
| 86 | |
| 87 - There is no built-in browser alert, but you can bind one as follows to call `alert()` in the global scope: | |
| 88 | |
| 89 window.alert = navigator.notification.alert; | |
| 90 | |
| 91 - Both `alert` and `confirm` are non-blocking calls, results of which are only available asynchronously. | |
| 92 | |
| 93 ### Firefox OS Quirks: | |
| 94 | |
| 95 Both native-blocking `window.alert()` and non-blocking `navigator.notification.alert()` are available. | |
| 96 | |
| 97 ### BlackBerry 10 Quirks | |
| 98 `navigator.notification.alert('text', callback, 'title', 'text')` callback parameter is passed the number 1. | |
| 99 | |
| 100 ## navigator.notification.confirm | |
| 101 | |
| 102 Displays a customizable confirmation dialog box. | |
| 103 | |
| 104 navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels]) | |
| 105 | |
| 106 - __message__: Dialog message. _(String)_ | |
| 107 | |
| 108 - __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)_ | |
| 109 | |
| 110 - __title__: Dialog title. _(String)_ (Optional, defaults to `Confirm`) | |
| 111 | |
| 112 - __buttonLabels__: Array of strings specifying button labels. _(Array)_ (Optional, defaults to [`OK,Cancel`]) | |
| 113 | |
| 114 | |
| 115 ### confirmCallback | |
| 116 | |
| 117 The `confirmCallback` executes when the user presses one of the | |
| 118 buttons in the confirmation dialog box. | |
| 119 | |
| 120 The callback takes the argument `buttonIndex` _(Number)_, which is the | |
| 121 index of the pressed button. Note that the index uses one-based | |
| 122 indexing, so the value is `1`, `2`, `3`, etc. | |
| 123 | |
| 124 ### Example | |
| 125 | |
| 126 function onConfirm(buttonIndex) { | |
| 127 alert('You selected button ' + buttonIndex); | |
| 128 } | |
| 129 | |
| 130 navigator.notification.confirm( | |
| 131 'You are the winner!', // message | |
| 132 onConfirm, // callback to invoke with index of button pressed | |
| 133 'Game Over', // title | |
| 134 ['Restart','Exit'] // buttonLabels | |
| 135 ); | |
| 136 | |
| 137 ### Supported Platforms | |
| 138 | |
| 139 - Amazon Fire OS | |
| 140 - Android | |
| 141 - BlackBerry 10 | |
| 142 - Firefox OS | |
| 143 - iOS | |
| 144 - Tizen | |
| 145 - Windows Phone 7 and 8 | |
| 146 - Windows 8 | |
| 147 - Windows | |
| 148 | |
| 149 ### Windows Phone 7 and 8 Quirks | |
| 150 | |
| 151 - There is no built-in browser function for `window.confirm`, but you can bind it by assigning: | |
| 152 | |
| 153 window.confirm = navigator.notification.confirm; | |
| 154 | |
| 155 - Calls to `alert` and `confirm` are non-blocking, so the result is only available asynchronously. | |
| 156 | |
| 157 ### Windows Quirks | |
| 158 | |
| 159 - On Windows8/8.1 it is not possible to add more than three buttons to MessageDialog instance. | |
| 160 | |
| 161 - On Windows Phone 8.1 it's not possible to show dialog with more than two buttons. | |
| 162 | |
| 163 ### Firefox OS Quirks: | |
| 164 | |
| 165 Both native-blocking `window.confirm()` and non-blocking `navigator.notification.confirm()` are available. | |
| 166 | |
| 167 ## navigator.notification.prompt | |
| 168 | |
| 169 Displays a native dialog box that is more customizable than the browser's `prompt` function. | |
| 170 | |
| 171 navigator.notification.prompt(message, promptCallback, [title], [buttonLabels], [defaultText]) | |
| 172 | |
| 173 - __message__: Dialog message. _(String)_ | |
| 174 | |
| 175 - __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)_ | |
| 176 | |
| 177 - __title__: Dialog title _(String)_ (Optional, defaults to `Prompt`) | |
| 178 | |
| 179 - __buttonLabels__: Array of strings specifying button labels _(Array)_ (Optional, defaults to `["OK","Cancel"]`) | |
| 180 | |
| 181 - __defaultText__: Default textbox input value (`String`) (Optional, Default: empty string) | |
| 182 | |
| 183 ### promptCallback | |
| 184 | |
| 185 The `promptCallback` executes when the user presses one of the buttons | |
| 186 in the prompt dialog box. The `results` object passed to the callback | |
| 187 contains the following properties: | |
| 188 | |
| 189 - __buttonIndex__: The index of the pressed button. _(Number)_ Note that the index uses one-based indexing, so the value is `1`, `2`, `3`, etc. | |
| 190 | |
| 191 | |
| 192 | |
| 193 - __input1__: The text entered in the prompt dialog box. _(String)_ | |
| 194 | |
| 195 ### Example | |
| 196 | |
| 197 function onPrompt(results) { | |
| 198 alert("You selected button number " + results.buttonIndex + " and entered " + results.input1); | |
| 199 } | |
| 200 | |
| 201 navigator.notification.prompt( | |
| 202 'Please enter your name', // message | |
| 203 onPrompt, // callback to invoke | |
| 204 'Registration', // title | |
| 205 ['Ok','Exit'], // buttonLabels | |
| 206 'Jane Doe' // defaultText | |
| 207 ); | |
| 208 | |
| 209 ### Supported Platforms | |
| 210 | |
| 211 - Amazon Fire OS | |
| 212 - Android | |
| 213 - Firefox OS | |
| 214 - iOS | |
| 215 - Windows Phone 7 and 8 | |
| 216 | |
| 217 ### Android Quirks | |
| 218 | |
| 219 - Android supports a maximum of three buttons, and ignores any more than that. | |
| 220 | |
| 221 - On Android 3.0 and later, buttons are displayed in reverse order for devices that use the Holo theme. | |
| 222 | |
| 223 ### Firefox OS Quirks: | |
| 224 | |
| 225 Both native-blocking `window.prompt()` and non-blocking `navigator.notification.prompt()` are available. | |
| 226 | |
| 227 ## navigator.notification.beep | |
| 228 | |
| 229 The device plays a beep sound. | |
| 230 | |
| 231 navigator.notification.beep(times); | |
| 232 | |
| 233 - __times__: The number of times to repeat the beep. _(Number)_ | |
| 234 | |
| 235 ### Example | |
| 236 | |
| 237 // Beep twice! | |
| 238 navigator.notification.beep(2); | |
| 239 | |
| 240 ### Supported Platforms | |
| 241 | |
| 242 - Amazon Fire OS | |
| 243 - Android | |
| 244 - BlackBerry 10 | |
| 245 - iOS | |
| 246 - Tizen | |
| 247 - Windows Phone 7 and 8 | |
| 248 - Windows 8 | |
| 249 | |
| 250 ### Amazon Fire OS Quirks | |
| 251 | |
| 252 - Amazon Fire OS plays the default __Notification Sound__ specified under the __Settings/Display & Sound__ panel. | |
| 253 | |
| 254 ### Android Quirks | |
| 255 | |
| 256 - Android plays the default __Notification ringtone__ specified under the __Settings/Sound & Display__ panel. | |
| 257 | |
| 258 ### Windows Phone 7 and 8 Quirks | |
| 259 | |
| 260 - Relies on a generic beep file from the Cordova distribution. | |
| 261 | |
| 262 ### Tizen Quirks | |
| 263 | |
| 264 - Tizen implements beeps by playing an audio file via the media API. | |
| 265 | |
| 266 - 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`. | |
| 267 |
