# Manual de Zenity

## Introdución

Zenity permítelle crear os seguintes tipos de diálogos sinxelos:

- Calendario

- Seleccionador de ficheiros

- Lista

- Icona de notificación

- Mensaxe

  - Erro

  - Información

  - Pregunta

  - Advertencia

- Progreso

- Entrada de texto

- Información de texto

## Uso

When you write scripts, you can use Zenity to create simple dialogs that interact graphically with the user, as follows:

- You can create a dialog to obtain information from the user. For example, you can prompt the user to select a date from a calendar dialog, or to select a file from a file selection dialog.

- You can create a dialog to provide the user with information. For example, you can use a progress dialog to indicate the current status of an operation, or use a warning message dialog to alert the user.

When the user closes the dialog, Zenity prints the text produced by the dialog to standard output.

When you write Zenity commands, ensure that you place quotation marks around each argument.

For example, use:

    zenity --calendar --title="Holiday Planner"

Do not use:

    zenity --calendar --title=Holiday Planner

If you do not use quotation marks, you might get unexpected results.

### Combinacións de teclas

An access key is a key that enables you to perform an action from the keyboard rather than use the mouse to choose a command from a menu or dialog. Each access key is identified by an underlined letter on a menu or dialog option.

Some Zenity dialogs support the use of access keys. To specify the character to use as the access key, place an underscore before that character in the text of the dialog. The following example shows how to specify the letter 'C' as the access key:

    "_Seleccione un nome".

### Códigos de saída

Zenity retorna os seguintes códigos de erro:

Código de saída | Descrición
`0` | O usuario premeu ou Aceptar ou Pechar.
`1` | O usuario premeu ou Cancelar ou usou as funcións de xanela para pechar o diálogo.
`-1` | Produciuse un erro inesperado.
`5` | O diálogo pechouse porque o tempo de espera alcanzouse.

### Opcións xerais

Tódolos diálogos de Zenity son compatíbeis coas seguintes opcións xerais:

`--title`=`título`

- Especifica o título dun diálogo.

`--window-icon`=`ruta_de_icona`

- Especifica a icona que se mostra no marco da xanela do diálogo. Hai 4 iconas dispoñíbeis, fornecendo as palabras chave seguintes - «info», «warning», «question» e «erro».

`--width`=`ancho`

- Especifica o ancho dun diálogo

`--height`=`alto`

- Especifica o alto dun diálogo

`--timeout`=`tempo de espera`

- Especifica o tempo de espera en segundos despois do cal o diálogo se pechará.

### Opcións de axuda

Zenity fornece as seguintes opcións de axuda

`--help`

- Mostra un texto de axuda abreviado.

`--help-all`

- Mostra o texto de axuda para os diálogos

`--help-general`

- Mostra o texto de axuda para as opcións de diálogo xerais.

`--help-calendar`

- Mostra o texto de axuda para as opcións do diálogo do calendario.

`--help-entry`

- Mostra o texto de axuda para as opcións do diálogo de entrada de texto.

`--help-error`

- Mostra o texto de axuda para as opcións do diálogo de erro.

`--help-info`

- Mostra o texto de axuda para as opcións do diálogo de información.

`--help-file-selection`

- Mostra o texto de axuda para as opcións do diálogo de selección de ficheiros.

`--help-list`

- Mostra o texto de axuda para as opcións do diálogo de lista.

`--help-notification`

- Mostra o texto de axuda para as opcións de iconas de notificación.

`--help-progress`

- Mostra o texto de axuda para as opcións do diálogo de progreso.

`--help-question`

- Mostra o texto de axuda para as opcións do diálogo de pregunta.

`--help-warning`

- Mostra o texto de axuda para as opcións do diálogo de avisos.

`--help-text-info`

- Mostra o texto de axuda para as opcións de diálogo de información.

`--help-misc`

- Mostra axuda para opcións varias.

`--help-gtk`

- Mostra axuda para as opcóns de GTK+

### Opcións varias

Zenity tamén fornece as seguintes opcións varias:

`--about`

- Mostra o diálogo Sobre Zenity, que contén información da versión de Zenity, información de copyright e información do desenvolvedor.

`--version`

- Mostra o número de versión de Zenity.

### Opcións de GTK+

Zenity admite as opcións GTK+ estándar. Para obter máis información sobre as opcións de GTK+, execute a orde `zenity -?`.

### Variábeis de contorno

Normally, Zenity detects the terminal window from which it was launched and keeps itself above that window. This behavior can be disabled by unsetting the `WINDOWID` environment variable.

## Diálogo de calendario

Use a opción `--calendar` para crear un diálogo de calendario. Zenity devolve a data seleccionada á entrada estándar. Se non se selecciona ningunha data na liña de ordes, o diálogo use a data actual.

O diálogo de calendario admite as seguintes opcións:

`--text`=`texto`

- Especifica o texto que se mostra no diálogo de calendario.

`--day`=`día`

- Especifica o día que está seleccionado no diálogo de calendario. `día` debe ser un número entre 1 e 31 ámbolos dous incluídos.

`--month`=`mes`

- Especifica o mes que está seleccionado no diálogo de calendario. `mes` debe ser un número entre 1 e 12 ámbolos dous incluídos.

`--year`=`ano`

- Especifica o ano que está seleccionado no diálogo de calendario.

`--date-format`=`formato`

- Specifies the format that is returned from the calendar dialog after date selection. The default format depends on your locale. `format` must be a format that is acceptable to the `strftime` function, for example `%A %d/%m/%y`.

O seguinte script de exemplo mostra como se crea un diálogo de calendario:

            #!/bin/sh

            if zenity --calendar \
            --title="Seleccione unha data" \
            --text="Prema nunha data para seleccionala." \
            --day=10 --month=8 --year=2004
              then echo $?
              else echo "Non se seleccionou ningunha data"
            fi

### Diálogo de calendario de exemplo

Zenity exemplo dun diálogo de calendario

## Diálogo de selección de ficheiro

Use the `--file-selection` option to create a file selection dialog. Zenity returns the selected files or directories to standard output. The default mode of the file selection dialog is open.

O diálogo de selección de ficheiros admite as seguintes opcións:

`--filename`=`filename`

- Specifies the file or directory that is selected in the file selection dialog when the dialog is first shown.

`--multiple`

- Permite a selección de múltiples nomes de ficheiro no diálogo de selección de ficheiro.

`--directory`

- Permite só a selección de cartafoles no diálogo de selección de ficheiro.

`--save`

- Estabelece o diálogo de selección de modo no modo gardar.

`--separator`=`separador`

- Especifica a cadea que se usará para dividir a lista de nomes de ficheiro devolta.

O seguinte script de exemplo mostra como crear un diálogo de selección de ficheiro:

            #!/bin/sh

            FILE=`zenity --file-selection --title="Seleccione un ficheiro"`

            case $? in
                     0)
                            echo "\"$FILE\" seleccionado.";;
                     1)
                            echo "Non se seleccionou ningún ficheiro.";;
                    -1)
                            echo "Non se seleccionou ningún ficheiro.";;
            esac

### Exemplo de diálogo de selección de ficheiros

Zenity exemplo de selección de ficheiro

## Icona de notificación

`--text`=`texto`

- Especifica o texto que se mostra na área de notificación.

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

            #!/bin/sh

            zenity --notification\
              --window-icon="info" \
              --text="Non hai anovacións do sistema necesarios!"

### Exemplo de icona de notificación

Zenity exemplo da icona de notificación

## Diálogo de lista

Use the `--list` option to create a list dialog. Zenity returns the entries in the first column of text of selected rows to standard output.

Data for the dialog must specified column by column, row by row. Data can be provided to the dialog through standard input. Each entry must be separated by a newline character.

If you use the `--checklist` or `--radiolist` options, each row must start with either 'TRUE' or 'FALSE'.

O diálogo de lista admite as seguintes opcións:

`--columna`=`columna`

- Specifies the column headers that are displayed in the list dialog. You must specify a `--column` option for each column that you want to display in the dialog.

`--checklist`

- Especifica que a primeira columna no diálogo de lista contén caixas de verificación.

`--radiolist`

- Especifica que a primeira columna no diálogo de lista contén caixas de opción.

`--editable`

- permite editar os elementos mostrados.

`--separator`=`separador`

- Specifies what string is used when the list dialog returns the selected entries.

`--print-column`=`columna`

- Specifies what column should be printed out upon selection. The default column is '1'. 'ALL' can be used to print out all columns in the list.

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

            #!/bin/sh

            zenity --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 "GNOME Dictionary does not handle proxy" \
                393823 Critical "Menu editing does not work in GNOME 2.0"

### Exemplo de diálogo de lista

Zenity list dialog example

## Message Dialogs

Zenity can create four types of message dialog:

- Erro

- Información

- Pregunta

- Advertencia

For each type, use the `--text` option to specify the text that is displayed in the dialog.

### Error Dialog

Use the `--error` option to create an error dialog.

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

              #!/bin/bash

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

#### Error Dialog Example

Zenity error dialog example

### Information Dialog

Use the `--info` option to create an information dialog.

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

              #!/bin/bash

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

#### Information Dialog Example

Zenity information dialog example

### Question Dialog

Use the `--question` option to create a question dialog.

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

              #!/bin/bash

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

#### Exemplo do diálogo de pregunta

Zenity exemplo do diálogo de pregunta

### Diálogo de advertencia

Use a opción `--warning` para crear un diálogo de pregunta.

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

              #!/bin/bash

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

#### Warning Dialog Example

Zenity warning dialog example

## Diálogo de progreso

Use the `--progress` option to create a progress dialog.

Zenity reads data from standard input line by line. If a line is prefixed with #, the text is updated with the text on that line. If a line contains only a number, the percentage is updated with that number.

The progress dialog supports the following options:

`--text`=`texto`

- Specifies the text that is displayed in the progress dialog.

`--percentage`=`percentage`

- Specifies the initial percentage that is set in the progress dialog.

`--auto-close`

- Closes the progress dialog when 100% has been reached.

`--pulsate`

- Specifies that the progress bar pulsates until an EOF character is read from standard input.

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
            ) |
            zenity --progress \
              --title="Update System Logs" \
              --text="Scanning mail logs..." \
              --percentage=0

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

### Progress Dialog Example

Zenity progress dialog example

## Text Entry Dialog

Use the `--entry` option to create a text entry dialog. Zenity returns the contents of the text entry to standard output.

The text entry dialog supports the following options:

`--text`=`texto`

- Specifies the text that is displayed in the text entry dialog.

`--entry-text`=`text`

- Specifies the text that is displayed in the entry field of the text entry dialog.

`--hide-text`

- Hides the text in the entry field of the text entry dialog.

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

            #!/bin/sh

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

### Text Entry Dialog Example

Zenity text entry dialog example

## Text Information Dialog

Use the `--text-info` option to create a text information dialog.

The text information dialog supports the following options:

`--filename`=`filename`

- Specifies a file that is loaded in the text information dialog.

`--editable`

- Allows the displayed text to be edited. The edited text is returned to standard output when the dialog is closed.

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

            #!/bin/sh

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

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

### Text Information Dialog Example

Zenity text information dialog example