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: Este plugin proporciona acceso a algunos elementos de la interfaz nativa de diálogo.
michael@0: 
michael@0: ## Instalación
michael@0: 
michael@0:     cordova plugin add org.apache.cordova.dialogs
michael@0:     
michael@0: 
michael@0: ## Métodos
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: Muestra un cuadro de alerta o diálogo personalizado. La mayoría de las implementaciones de Cordova utilizan un cuadro de diálogo nativa para esta característica, pero algunas plataformas utilizan el navegador `alert` la función, que es típicamente menos personalizable.
michael@0: 
michael@0:     navigator.notification.alert(message, alertCallback, [title], [buttonName])
michael@0:     
michael@0: 
michael@0: *   **message**: mensaje de diálogo. *(String)*
michael@0: 
michael@0: *   **alertCallback**: Callback para invocar al diálogo de alerta es desestimada. *(Función)*
michael@0: 
michael@0: *   **title**: título de diálogo. *(String)* (Opcional, el valor predeterminado de `Alert`)
michael@0: 
michael@0: *   **buttonName**: nombre del botón. *(String)* (Opcional, por defecto `Aceptar`)
michael@0: 
michael@0: ### Ejemplo
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: 
michael@0: ### Plataformas soportadas
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 y 8
michael@0: *   Windows 8
michael@0: 
michael@0: ### Windows Phone 7 y 8 rarezas
michael@0: 
michael@0: *   No hay ninguna alerta del navegador integrado, pero puede enlazar uno proceda a llamar `alert()` en el ámbito global:
michael@0:     
michael@0:         window.alert = navigator.notification.alert;
michael@0:         
michael@0: 
michael@0: *   `alert` y `confirm` son non-blocking llamadas, cuyos resultados sólo están disponibles de forma asincrónica.
michael@0: 
michael@0: ### Firefox OS rarezas:
michael@0: 
michael@0: Dos nativos de bloqueo `window.alert()` y no-bloqueo `navigator.notification.alert()` están disponibles.
michael@0: 
michael@0: ## navigator.notification.confirm
michael@0: 
michael@0: Muestra un cuadro de diálogo de confirmación personalizables.
michael@0: 
michael@0:     navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])
michael@0:     
michael@0: 
michael@0: *   **message**: mensaje de diálogo. *(String)*
michael@0: 
michael@0: *   **confirmCallback**: Callback para invocar con índice de botón pulsado (1, 2 o 3) o cuando el diálogo es despedido sin la presión del botón (0). *(Función)*
michael@0: 
michael@0: *   **title**: título de diálogo. *(String)* (Opcional, por defecto a `confirmar`)
michael@0: 
michael@0: *   **buttonLabels**: matriz de cadenas especificando las etiquetas de botón. *(Matriz)* (Opcional, por defecto [`OK, cancelar`])
michael@0: 
michael@0: ### confirmCallback
michael@0: 
michael@0: El `confirmCallback` se ejecuta cuando el usuario presiona uno de los botones en el cuadro de diálogo de confirmación.
michael@0: 
michael@0: La devolución de llamada toma el argumento `buttonIndex` *(número)*, que es el índice del botón presionado. Tenga en cuenta que el índice utiliza uno basado en la indexación, así que el valor es `1`, `2`, `3`, etc..
michael@0: 
michael@0: ### Ejemplo
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: 
michael@0: ### Plataformas soportadas
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 y 8
michael@0: *   Windows 8
michael@0: 
michael@0: ### Windows Phone 7 y 8 rarezas
michael@0: 
michael@0: *   No hay ninguna función de navegador incorporado para `window.confirm`, pero lo puede enlazar mediante la asignación:
michael@0:     
michael@0:         window.confirm = navigator.notification.confirm;
michael@0:         
michael@0: 
michael@0: *   Llamadas de `alert` y `confirm` son non-blocking, así que el resultado sólo está disponible de forma asincrónica.
michael@0: 
michael@0: ### Firefox OS rarezas:
michael@0: 
michael@0: Dos nativos de bloqueo `window.confirm()` y no-bloqueo `navigator.notification.confirm()` están disponibles.
michael@0: 
michael@0: ## navigator.notification.prompt
michael@0: 
michael@0: Muestra un cuadro de diálogo nativa que es más personalizable que del navegador `prompt` función.
michael@0: 
michael@0:     navigator.notification.prompt(message, promptCallback, [title], [buttonLabels], [defaultText])
michael@0:     
michael@0: 
michael@0: *   **message**: mensaje de diálogo. *(String)*
michael@0: 
michael@0: *   **promptCallback**: Callback para invocar con índice del botón pulsado (1, 2 ó 3) o cuando el cuadro de diálogo es despedido sin la presión del botón (0). *(Función)*
michael@0: 
michael@0: *   **title**: título *(String)* (opcional, por defecto `puntual` de diálogo)
michael@0: 
michael@0: *   **buttonLabels**: matriz de cadenas especificando el botón etiquetas *(Array)* (opcional, por defecto `["OK", "Cancelar"]`)
michael@0: 
michael@0: *   **defaultText**: valor de la entrada predeterminada textbox ( `String` ) (opcional, por defecto: cadena vacía)
michael@0: 
michael@0: ### promptCallback
michael@0: 
michael@0: El `promptCallback` se ejecuta cuando el usuario presiona uno de los botones en el cuadro de diálogo pronto. El objeto de `resultados` pasado a la devolución de llamada contiene las siguientes propiedades:
michael@0: 
michael@0: *   **buttonIndex**: el índice del botón presionado. *(Número)* Tenga en cuenta que el índice utiliza uno basado en la indexación, así que el valor es `1`, `2`, `3`, etc..
michael@0: 
michael@0: *   **input1**: el texto introducido en el cuadro de diálogo pronto. *(String)*
michael@0: 
michael@0: ### Ejemplo
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: 
michael@0: ### Plataformas soportadas
michael@0: 
michael@0: *   Amazon fire OS
michael@0: *   Android
michael@0: *   Firefox OS
michael@0: *   iOS
michael@0: *   Windows Phone 7 y 8
michael@0: 
michael@0: ### Rarezas Android
michael@0: 
michael@0: *   Android soporta un máximo de tres botones e ignora nada más.
michael@0: 
michael@0: *   En Android 3.0 y posteriores, los botones se muestran en orden inverso para dispositivos que utilizan el tema de Holo.
michael@0: 
michael@0: ### Firefox OS rarezas:
michael@0: 
michael@0: Dos nativos de bloqueo `window.prompt()` y no-bloqueo `navigator.notification.prompt()` están disponibles.
michael@0: 
michael@0: ## navigator.notification.beep
michael@0: 
michael@0: El dispositivo reproduce un sonido sonido.
michael@0: 
michael@0:     navigator.notification.beep(times);
michael@0:     
michael@0: 
michael@0: *   **times**: el número de veces a repetir la señal. *(Número)*
michael@0: 
michael@0: ### Ejemplo
michael@0: 
michael@0:     / / Pitido dos veces! 
michael@0:     navigator.notification.beep(2);
michael@0:     
michael@0: 
michael@0: ### Plataformas soportadas
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 y 8
michael@0: *   Windows 8
michael@0: 
michael@0: ### Amazon fuego OS rarezas
michael@0: 
michael@0: *   Amazon fuego OS reproduce el **Sonido de notificación** especificados en el panel de **configuración/pantalla y sonido** por defecto.
michael@0: 
michael@0: ### Rarezas Android
michael@0: 
michael@0: *   Android juega el **tono de notificación** especificados en el panel **ajustes de sonido y pantalla** por defecto.
michael@0: 
michael@0: ### Windows Phone 7 y 8 rarezas
michael@0: 
michael@0: *   Se basa en un archivo de sonido genérico de la distribución de Cordova.
michael@0: 
michael@0: ### Rarezas Tizen
michael@0: 
michael@0: *   Tizen implementa pitidos por reproducir un archivo de audio a través de los medios de comunicación API.
michael@0: 
michael@0: *   El archivo de sonido debe ser corto, debe estar ubicado en un `sounds` subdirectorio del directorio raíz de la aplicación y deben ser nombrados`beep.wav`.