# Manual do MateDialog

## Introdução

O MateDialog lhe habilita a criar os seguintes tipos de diálogo simples:

- Calendário

- Seleção de arquivo

- Lista

- Ícone de notificação

- Mensagem

  - Erro

  - Informação

  - Pergunta

  - Aviso

- Indicador de progresso

- Entrada de texto

- Informação de texto

## Modo de uso

Quando se escreve scripts, é possível usar o MateDialog para criar diálogos simples que interajam graficamente com o usuário:

- Você pode criar um diálogo para obter informações do usuáro. Por exemplo, você pedir ao usuário que selecione uma data em um diálogode calendário ou para escolher um arquivo por um diálogo de seleção de arquivo.

- Você pode criar um diálogo para prover informações ao usuário. Por exemplo, você pode usar um diálogo indicador de progresso para indicar o estado atual de uma operação ou usar um diálogo de mensagem de aviso para alertar o usuário.

Quando o usuário fecha um diálogo, o MateDialog emite o texto produzido por ele para a saída padrão.

Quando você escreve os comandos do MateDialog, assegure-se de fazer uso das aspas em torno de cada argumento.

For example, use:

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

Do not use:

    matedialog --calendar --title=Holiday Planner

Se você não utilizar as aspas, pode obter resultados inesperados.

### Teclas de acesso

Uma tecla de acesso é aquela que lhe habilita desempenhar uma ação a partir do teclado, em vez de usar o mouse, para escolher um comando de um menu ou de um diálogo. Cada tecla de acesso é identificada por uma letra sublinhada em uma opção do menu ou do diálogo.

Alguns diálogos do MateDialog oferecem suporte para o uso de teclas de acesso. Para especificar o caractere a usar como tecla de acesso, coloque um sublinhado antes de tal caractere no texto do diálogo. Os exemplos a seguir mostram como especificar a letra "E" como tecla de acesso:

    "_Choose a name".

### Códigos de saída

O MateDialog retorna os seguintes códigos de saída:

Código de saída | Descrição
`0` | O usuário pressionou ou OK ou Fechar.
`1` | O usuário ou pressionou Cancelar ou usou as funções da janela para fechar o diálogo.
`-1` | Ocorreu um erro inesperado.
`5` | O diálogo foi fechado porque o tempo de espera se esgotou.

### Opções gerais

Todos os diálogos do MateDialog dão suporte às seguintes opções gerais:

`--title`=`título`

- Especifica o título de um diálogo.

`--window-icon`=`caminho_ao_ícone`

- Especifica o ícone que é exibido na moldura do diálogo. Existem 4 ícones pré-definidos que também estão disponíveis ao usar as seguintes palavras-chave - "info", "warning" (aviso), "question" (pergunta) e "error" (erro).

`--width`=`largura`

- Especifica a largura do diálogo.

`--height`=`altura`

- Especifica a altura do diálogo.

`--timeout`=`tempo_de_espera`

- Especifica o tempo de espera em segundos depois do qual o diálogo será fechado.

### Opções de ajuda

O MateDialog fornece as seguintes opções de ajuda:

`--help`

- Exibe o texto resumido de ajuda.

`--help-all`

- Exibe o texto completo de ajuda para todos os diálogos.

`--help-general`

- Exibe os textos de ajuda para opções gerais de diálogos.

`--help-calendar`

- Exibe o texto de ajuda para as opções do diálogo de calendário.

`--help-entry`

- Exibe o texto de ajuda para as opções do diálogo de entrada de texto.

`--help-error`

- Exibe o texto de ajuda para as opções do diálogo de erro.

`--help-info`

- Exibe o texto de ajuda para as opções do diálogo de informação.

`--help-file-selection`

- Exibe o texto de ajuda para as opções do diálogo de seleção de arquivo.

`--help-list`

- Exibe o texto de ajuda para as opções do diálogo de lista.

`--help-notification`

- Exibe o texto de ajuda para as opções de ícones de notificação.

`--help-progress`

- Exibe o texto de ajuda para as opções do diálogo indicador de progresso.

`--help-question`

- Exibe o texto de ajuda para as opções do diálogo de pergunta.

`--help-warning`

- Exibe o texto de ajuda para as opções do diálogo de aviso.

`--help-text-info`

- Exibe o texto de ajuda para as opções do diálogo de informação de texto.

`--help-misc`

- Exibe o texto de ajuda para outras opções.

`--help-gtk`

- Exibe ajuda para as opções do GTK+.

### Outras opções

O MateDialog também fornece as seguintes opções:

`--about`

- Exibe o diálogo Sobre o matedialog, que contém asinformações da versão do MateDialog, dos direitos autorais e dos desenvolvedores.

`--version`

- Exibe o número da versão do MateDialog.

### Opções do GTK+

O MateDialog oferece suporte às opções padrões do GTK+. Para mais informações sobre elas, execute o comando `matedialog -?`.

### Variáveis de ambiente

Normalmente, o MateDialog detecta a janela de terminal pela qual foi lançado e se mantém acima dessa janela. Esse comportamento pode ser desativado desconfigurando a variável de ambiente `WINDOWID`.

## Diálogo de calendário

Use a opção `--calendar` para criar um diálogo decalendário. O MateDialog returna a data selecionada para a saída padrão. Se nenhuma data for especificada na linha de comando, o diálogo usa a data atual como valor inicial.

O diálogo de calendário dá suporte às seguintes opções:

`--text`=`texto`

- Especifica o texto que é exibido no diálogo de calendário.

`--day`=`dia`

- Especifica o dia que começa selecionado no diálogo de calendário. `dia` deve ser um número entre 1 e 31 inclusive.

`--month`=`mês`

- Especifica o mês que começa selecionado no diálogo de calendário.`mês` deve ser um número entre 1 e 12 inclusive.

`--year`=`ano`

- Especifica o ano que começa selecionado no diálogo de calendário.

`--date-format`=`formato`

- Especifica o formato que é utilizado no retorno do diálogo de calendário depois da seleção da data. O formato padrão depende de sua localidade. `formato` deve ser um formato que seja aceitável pela função `strftime`, por exemplo `%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

### Exemplo de diálogo de calendário

MateDialog calendar dialog example

## Diálogo de seleção de arquivo

Use a opção `--file-selection` para criar um diálogo de seleção de arquivo. O MateDialog retorna os arquivos ou diretórios selecionados para a saída padrão. O modo padrão para o diálogo de seleção de arquivo é aberto.

O diálogo de seleção de arquivo suporta as seguintes opções:

`--filename`=`nome_de_arquivo`

- Especifica o arquivo ou o diretório que começa selecionado no diálogo quando ele é mostrado pela primeira vez.

`--multiple`

- Permite a seleção de múltiplos arquivos no diálogo de seleção de arquivos.

`--directory`

- Permite apenas a seleção de diretórios no diálogo de seleção de arquivos.

`--save`

- Ajusta o diálogo de seleção de arquivos para o modo de salvamento.

`--separator`=`separador`

- Especifica o texto que será usado para dividir a lista de nomes de arquivos retornada.

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

### Exemplo de diálogo de seleção de arquivo

MateDialog file selection dialog example

## Ícone de notificação

`--text`=`texto`

- Especifica o texto que é exibido na área de notificação

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

            #!/bin/sh

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

### Exemplo de ícone de notificação

MateDialog notification icon example

## Diálogo de lista

Use a opção `--list` para criar um diálogo de lista. O MateDialog retorna para a saída padrão os itens na primeira coluna de texto das linhas selecionadas.

Os dados para o diálogo devem ser especificados coluna por coluna, linha por linha. Eles podem ser fornecidos através da entrada padrão. Cada item deve ser separado por um caractere de nova-linha.

Se você usar as opções `--checklist` ou `--radiolist`, cada linha deve começar ou com "TRUE" (verdadeiro) ou com "FALSE" (falso).

O diálogo de lista oferece suporte às seguintes opções:

`--column`=`coluna`

- Especifica o cabeçalho das colunas que são exibidas no diálogo de lista. Você deve especificar a opção `--column` para cada coluna que queira exibir no diálogo.

`--checklist`

- Especifica que a primeira coluna no diálogo de lista contém caixas de seleção.

`--radiolist`

- Especifica que a primeira coluna no diálogo de lista contém botões de opção.

`--editable`

- Permite que os itens exibidos sejam editados.

`--separator`=`separador`

- Especifica que texto é usado quando o diálogo de lista retorna os itens selecionados.

`--print-column`=`coluna`

- Especifica que coluna deveria ser emitida após seleção. A coluna padrão é "1". "ALL" (tudo) pode ser usado para emitir todas as colunas na lista.

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"

### Exemplo de diálogo de lista

MateDialog list dialog example

## Diálogos de mensagem

O MateDialog pode criar quarto tipos de diálogos de mensagem:

- Erro

- Informação

- Pergunta

- Aviso

Para cada tipo, use a opção `--text` para especificar o texto que será exibido no diálogo.

### Diálogo de erro

Use a opção `--error` para criar um diálogo de erro.

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

              #!/bin/bash

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

#### Exemplo de diálogo de erro

MateDialog error dialog example

### Diálogo de informação

Use a opção `--info` para criar um diálogo de informação.

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

              #!/bin/bash

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

#### Exemplo de diálogo de informação

MateDialog information dialog example

### Diálogo de pergunta

Use a opção `--question` para criar um diálogo de pergunta.

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

              #!/bin/bash

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

#### Exemplo de diálogo de pergunta

MateDialog question dialog example

### Diálogo de aviso

Use a opção `--warning` para criar um diálogo de aviso.

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

              #!/bin/bash

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

#### Exemplo de diálogo de aviso

MateDialog warning dialog example

## Diálogo indicador de progresso

Use a opção `--progress` para criar um diálogo indicador de progresso.

O MateDialog lê dados da entrada padrão linha por linha. Se uma linha for prefixada com #, o texto é atualizado com o texto dessa linha. Se uma linha contiver apenas um número, o percentual é atualizado com tal número.

O diálogo indicador de progresso oferece suporte às seguintes opções:

`--text`=`texto`

- Especifica o texto que é exibido no diálogo indicador de progresso.

`--percentage`=`porcentagem`

- Especifica a porcentagem inicial definida para o diálogo indicador de progresso.

`--auto-close`

- Fecha o diálogo indicador de progresso quando atinge os 100%.

`--pulsate`

- Especifica que a barra de progresso pulse até que um caractere EOF (fim de arquivo) seja lido da entrada padrão.

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

### Exemplo de diálogo indicador de progresso

MateDialog progress dialog example

## Diálogo de entrada de texto

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

O diálogo de entrada de texto oferece suporte às seguintes opções:

`--text`=`texto`

- Especifica o texto que é exibido no diálogo de entrada de texto.

`--entry-text`=`texto`

- Especifica o texto que é exibido no campo de entrada do diálogo de entrada de texto.

`--hide-text`

- Oculta o texto no campo de entrada do 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

### Exemplo de diálogo de entrada de texto

MateDialog text entry dialog example

## Diálogo de informação textual

Use a opção `--text-info` para criar um diálogo de informação textual.

O diálogo de informação textual oferece suporte às seguintes opções:

`--filename`=`nome_de_arquivo`

- Especifica um arquivo que será carregado no diálogo de informação textual.

`--editable`

- Permite que o texto exibido seja editado. O texto editado é retornado para a saída padrão quando o diálogo é fechado.

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

### Exemplo de diálogo de informação textual

MateDialog text information dialog example