• file
• revisions
• annotate
• diff
• comparison
• raw

Touchgui/plugins/org.apache.cordova.dialogs/doc/index.md@e8ccd40d0ef6 (annotated)

Touchgui/plugins/org.apache.cordova.dialogs/doc/index.md

Thu, 04 Jun 2015 14:50:33 +0200

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Thu, 04 Jun 2015 14:50:33 +0200

changeset 0

e8ccd40d0ef6

permissions

-rw-r--r--

Genesis of lecture sources for Droidcon Berlin 2015 in Postbahnhof.

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