# Manual de MateDialog

## Introducción

MateDialog le permite crear los siguientes tipos de diálogos simples:

- Calendario

- Seleccionador de archivos

- Lista

- Icono de notificación

- Mensajes

  - Error

  - Información

  - Pregunta

  - Advertencia

- Progreso

- Entrada de texto

- Información de texto

## Uso

Cuando escriba scripts, puede usar MateDialog para crear diálogos simples que interactúen gráficamente con el usuario, como por ejemplo:

- Puede crear un diálogo para obtener información del usuario. Por ejemplo, puede pedir al usuario seleccionar una fecha de un diálogo del calendario, o seleccionar un archivo de un diálogo de selección de archivo.

- Usted puede crear un diálogo para proporcionar información al usuario. Por ejemplo, puede usar un diálogo de progreso para indicar el estado actual de una operación, o usar un diálogo de advertencia para alertar al usuario.

Cuando el usuario cierra el diálogo, MateDialog imprime el texto producido por diálogo a la salida estándar de error.

Cuando usted escriba comandos de MateDialog, asegúrese de poner comillas alrededor de cada argumento.

For example, use:

    matedialog --calendar --title="Holiday Planner"

Do not use:

    matedialog --calendar --title=Holiday Planner

Si no usa comillas, puede que consiga resultados inesperados.

### Combinaciones de teclas

Una combinación de teclas le permite realizar una acción desde el teclado en lugar de utilizar el ratón para elegir un comando de un menú o un diálogo. Cada combinación de teclas se identifica por una letra subrayada en una opción del menú o de un diálogo.

Algunos diálogos de MateDialog soportan el uso de combinaciones de teclas. Para especificar el carácter que se utilizará como combinación de teclas, ponga un guión bajo precediendo ese carácter en el texto del diálogo. El ejemplo siguiente muestra cómo especificar la letra 'E' como combinación de teclas:

    "_Choose a name".

### Códigos de salida

MateDialog devuelve los siguientes códigos de salida:

Código de salida | Descripción
`0` | El usuario ha presionado Aceptar o Cerrar.
`1` | El usuario ha presionado Cancelar, o ha utilizado la función de la ventana para cerrar el diálogo.
`-1` | Ha ocurrido un error inesperado.
`5` | El diálogo se ha cerrado porque se alcanzó el tiempo de expiración.

### Opciones generales

Todos los diálogos de MateDialog soportan las siguientes opciones generales:

`--title`=`título`

- Especifica el título de un diálogo.

`--window-icon`=`ruta_al_icono`

- Especifica el icono que se muestra en el marco de la ventana del diálogo. Hay 4 iconos disponibles, proporcionando las palabras claves siguientes - 'info', 'warning', 'question' y 'error'.

`--width`=`anchura`

- Especifica el ancho del diálogo.

`--height`=`altura`

- Especifica la altura del diálogo.

`--timeout`=`tiempo de expiración`

- Especifica el tiempo de expiración en segundos después del cual el diálogo se cierra.

### Opciones de ayuda

MateDialog proporciona las opciones de ayuda siguentes:

`--help`

- Muestra un texto de ayuda abreviado.

`--help-all`

- Muestra un texto de ayuda completo para todos los diálogos.

`--help-general`

- Muestra el texto de ayuda para los opciones de diálogo generales.

`--help-calendar`

- Muestra el texto de ayuda para las opciones de diálogo del calendario.

`--help-entry`

- Muestra el texto de ayuda para las opciones del diálogo de entrada de texto.

`--help-error`

- Muestra el texto de ayuda para las opciones del diálogo de error.

`--help-info`

- Muestra el texto de ayuda para las opciones del diálogo de información.

`--help-file-selection`

- Muestra el texto de ayuda para las opciones del diálogo de selección de archivos.

`--help-list`

- Muestra el texto de ayuda para las opciones del diálogo de lista.

`--help-notification`

- Muestra el texto de ayuda para las opciones de iconos de notificación.

`--help-progress`

- Muestra el texto de ayuda para las opciones del diálogo de progreso.

`--help-question`

- Muestra el texto de ayuda para las opciones del diálogo de pregunta.

`--help-warning`

- Muestra el texto de ayuda para las opciones del diálogo de advertencia.

`--help-text-info`

- Muestra el texto de ayuda para las opciones del diálogo de información.

`--help-misc`

- Muestra el texto de ayuda para las opciones misceláneas.

`--help-gtk`

- Muestra la ayuda para las opciones de GTK+.

### Opciones misceláneas

MateDialog también proporciona las siguientes opciones misceláneas:

`--about`

- Muestra el diálogo Acerca de MateDialog, que contiene la información de la versión de MateDialog, información del copyright, e información del desarrollador.

`--version`

- Muestra el número de versión de MateDialog.

### Opciones de GTK+

MateDialog soporta las opciones estándares de GTK+. Para más información acerca de las opciones de GTK+, ejecute el comando `matedialog -?`.

### Variables de entorno

Generalmente MateDialog detecta la ventana del terminal desde la que se ha lanzado y se mantiene por encima de esa ventana. Este comportamiento se puede desactivar con la variable de entorno `WINDOWID`.

## Diálogo de calendario

Use la opción `--calendar` para crear un diálogo de calendario. MateDialog devuelve la fecha seleccionada a la salida estándar. Si no se especifica una fecha en la línea de comando, el diálogo utilizará la fecha actual.

El diálogo de calendario soporta las siguientes opciones:

`--text`=`texto`

- Especifica el texto que se muestra en el diálogo del calendario.

`--day`=`día`

- Especifica el día que se selecciona en el diálogo del calendario.`día` debe ser un número entre 1 y 31 ambos incluídos.

`--month`=`mes`

- Especifica el mes que se selecciona en el diálogo del calendario. `mes` debe ser un número entre 1 y 12 ambos incluídos.

`--year`=`año`

- Especifica el año que se selecciona en el diálogo del calendario.

`--date-format`=`formato`

- Especifica el formato que se devuelve desde el diálogo de calendario después de la selección de la fecha. El formato predeterminado depende de configuración regional. `formato` debe ser un formato que sea compatible con la función `strftime`, por ejemplo `%A %d/%m/%y`.

The following example script shows how to create a calendar dialog:

            #!/bin/sh

            if matedialog --calendar \
            --title="Select a Date" \
            --text="Click on a date to select that date." \
            --day=10 --month=8 --year=2004
              then echo $?
              else echo "No date selected"
            fi

### Ejemplo de un diálogo de calendario

MateDialog calendar dialog example

## Diálogo de selección de archivos

Use la opción `--file-selection` para crear un diálogo de selección de archivos. MateDialog devuelve los archivos o directorios seleccionados a la salida estándar. El modo predefinido de un diálogo de selección de archivo es «abrir».

El diálogo de selección de archivo soporta las siguientes opciones:

`--filename`=`nombre_del_archivo`

- Especifica el archivo o directorio que se selecciona en el diálogo de selección de archivo cuando el diálogo se muestra por primera vez.

`--multiple`

- Permite seleccionar archivos múltiples en el diálogo de selección.

`--directory`

- Permite solamente la selección de directorios en el diálogo de selección de archivos.

`--save`

- Establece el diálogo de selección de archivo en el modo «guardar».

`--separator`=`separador`

- Especifica la cadena que se usará para dividir la lista de nombres de archivo devuelta.

The following example script shows how to create a file selection dialog:

            #!/bin/sh

            FILE=`matedialog --file-selection --title="Select a File"`

            case $? in
                     0)
                            echo "\"$FILE\" selected.";;
                     1)
                            echo "No file selected.";;
                    -1)
                            echo "No file selected.";;
            esac

### Ejemplo del diálogo de selección de archivos

MateDialog file selection dialog example

## Icono de notificación

`--text`=`texto`

- Especifica el texto que se mostrara en el área de la notificación.

The following example script shows how to create a notification icon:

            #!/bin/sh

            matedialog --notification\
              --window-icon="info" \
              --text="There are system updates necessary!"

### Ejemplo de icono de notificación

MateDialog notification icon example

## Diálogo de lista

Use la opción `--list` para crear un diálogo de lista. MateDialog devuelve las entradas en la primera columna de texto de las filas seleccionadas a la salida estándar.

Los datos para el diálogo deben especificarse columna por columna, fila por fila. Puede proporcionar datos al diálogo a través de la entrada estándar. Cada entrada se debe separar por un carácter de línea nueva.

Si usa la opción `--checklist` o `--radiolist`, cada fila debe comenzar con 'TRUE' o 'FALSE'.

El diálogo de lista soporta las siguientes opciones:

`--column`=`columna`

- Especifica el encabezado de la columna mostrada en el diálogo de lista. Usted debe especificar una opción `--column` por cada columna que usted desea mostrar en el diálogo.

`--checklist`

- Especifica que la primera columna en el diálogo de lista contiene casillas de marcado.

`--radiolist`

- Especifica que la primera columna en el diálogo de lista contiene casillas de opción.

`--editable`

- Permite editar los elementos mostrados.

`--separator`=`separador`

- Especifica qué cadena de caracteres se utilizará cuando el diálogo de lista devuelva las entradas seleccionadas.

`--print-column`=`columna`

- Especifica qué columna debería imprimirse hasta la selección. La columna predeterminada es '1', 'ALL' puede usarse para imprimir todas las columnas.

The following example script shows how to create a list dialog:

            #!/bin/sh

            matedialog --list \
              --title="Choose the Bugs You Wish to View" \
              --column="Bug Number" --column="Severity" --column="Description" \
                992383 Normal "GtkTreeView crashes on multiple selections" \
                293823 High "MATE Dictionary does not handle proxy" \
                393823 Critical "Menu editing does not work in MATE 2.0"

### Ejemplo del diálogo de lista

MateDialog list dialog example

## Diálogos de mensaje

MateDialog puede crear cuatro tipos de diálogos de mensajes:

- Error

- Información

- Pregunta

- Advertencia

Para cada tipo, use la opción `--text` para especificar el texto que se muestra en el diálogo.

### Diálogo de error

Use la opción `--error` para crear un diálogo de error.

The following example script shows how to create an error dialog:

              #!/bin/bash

              matedialog --error \
              --text="Could not find /var/log/syslog."

#### Ejemplo de diálogo de error

MateDialog error dialog example

### Diálogo de información

Use la opción `--info` para crear un diálogo de información.

The following example script shows how to create an information dialog:

              #!/bin/bash

              matedialog --info \
              --text="Merge complete. Updated 3 of 10 files."

#### Ejemplo de diálogo de información

MateDialog information dialog example

### Diálogo de pregunta

Use la opción `--question` para crear un diálogo de pregunta.

The following example script shows how to create a question dialog:

              #!/bin/bash

              matedialog --question \
              --text="Are you sure you wish to proceed?"

#### Ejemplo del diálogo de pregunta

MateDialog question dialog example

### Diálogo de advertencia

Use la opción `--warning` para crear un diálogo de advertencia.

The following example script shows how to create a warning dialog:

              #!/bin/bash

              matedialog --warning \
              --text="Disconnect the power cable to avoid electrical shock."

#### Ejemplo del diálogo de advertencia

MateDialog warning dialog example

## Diálogo de progreso

Use la opción `--progress` para crear un diálogo de progreso.

MateDialog lee línea por línea los datos desde la entrada estándar. Si una línea se antepone con #, el texto se actualiza con el texto en esa línea. Si una línea contiene solamente un número, el porcentaje se actualiza con ese número.

El diálogo de progreso soporta las siguientes opciones:

`--text`=`texto`

- Especifica el texto que se muestra en el diálogo de progreso.

`--percentage`=`porcentaje`

- Especifica el porcentaje inicial que se establece en el diálogo de progreso.

`--auto-close`

- Cierra el diálogo de progreso cuando se ha alcanzado 100%.

`--pulsate`

- Especifica que la barra de progreso pulse hasta que se lea un carácter EOF desde la entrada estándar.

The following example script shows how to create a progress dialog:

            #!/bin/sh
            (
            echo "10" ; sleep 1
            echo "# Updating mail logs" ; sleep 1
            echo "20" ; sleep 1
            echo "# Resetting cron jobs" ; sleep 1
            echo "50" ; sleep 1
            echo "This line will just be ignored" ; sleep 1
            echo "75" ; sleep 1
            echo "# Rebooting system" ; sleep 1
            echo "100" ; sleep 1
            ) |
            matedialog --progress \
              --title="Update System Logs" \
              --text="Scanning mail logs..." \
              --percentage=0

            if [ "$?" = -1 ] ; then
                    matedialog --error \
                      --text="Update canceled."
            fi

### Ejemplo de diálogo de progreso

MateDialog progress dialog example

## Diálogo para la entrada de texto

Use la opción `-entry` para crear un diálogo de entrada de texto. MateDialog devuelve a la salida estándar el contenido del texto introducido.

El diálogo de entrada de texto soporta las siguientes opciones:

`--text`=`texto`

- Especifica el texto que se muestra en el diálogo de entrada de texto.

`--entry-text`=`texto`

- Especifica el texto que se muestra en el campo de entrada del diálogo de entrada.

`--hide-text`

- Oculta el texto en el campo de entrada del diálogo de entrada de texto.

The following example script shows how to create a text entry dialog:

            #!/bin/sh

            if matedialog --entry \
            --title="Add an Entry" \
            --text="Enter your _password:" \
            --entry-text "password" \
            --hide-text
              then echo $?
              else echo "No password entered"
            fi

### Ejemplo de diálogo de entrada de texto

MateDialog text entry dialog example

## Diálogo para la texto de información

Use la opción `--text-info` para crear un diálogo de texto de información.

El diálogo de texto de información soporta las siguientes opciones:

`--filename`=`nombre_del_archivo`

- Especifica un archivo que se carga en el diálogo de texto de información.

`--editable`

- Permite que el texto mostrado sea editado. El texto editado se devuelve por la salida estándar cuando el diálogo se cierra.

The following example script shows how to create a text information dialog:

            #!/bin/sh

            FILE=`matedialog --file-selection \
              --title="Select a File"`

            case $? in
                     0)
                            matedialog --text-info \
                              --title=$FILE \
                              --filename=$FILE \
                              --editable 2>/tmp/tmp.txt;;
                     1)
                            echo "No file selected.";;
                    -1)
                            echo "No file selected.";;
            esac

### Ejemplo del diálogo de texto de información

MateDialog text information dialog example