# 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.

Por exemplo, use:

    matedialog --calendar --title="Planejador de feriado"

Não use:

    matedialog --calendar --title=Planejador de feriado

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:

    "_Escolha um nome".

### 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`.

O script de exemplo a seguir mostra como criar um diálogo de calendário:

            #!/bin/sh

            if matedialog --calendar \
            --title="Selecione uma data" \
            --text="Clique em uma data para selecioná-la." \
            --day=10 --month=8 --year=2004
              then echo $?
              else echo "Nenhuma data foi selecionada"
            fi

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

MateDialog exemplo de diálogo de calendário

## 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.

O script de exemplo a seguir mostra como criar um diálogo de seleção de arquivo:

            #!/bin/sh

            FILE=`matedialog --file-selection --title="Selecione um arquivo"`

            case $? in
                     0)
                            echo "\"$FILE\" foi selecionado.";;
                     1)
                            echo "Nenhum arquivo foi selecionado.";;
                    -1)
                            echo "Nenhum arquivo foi selecionado.";;
            esac

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

MateDialog exemplo de diálogo de seleção de arquivo

## Ícone de notificação

`--text`=`texto`

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

O script de exemplo a seguir mostra como criar um ícone de notificação:

            #!/bin/sh

            matedialog --notification\
              --window-icon="info" \
              --text="Existem importantes atualizações do sistema!"

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

MateDialog exemplo de ícone de notificação

## 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.

O script de exemplo a seguir mostra como criar um diálogo de lista:

            #!/bin/sh

            matedialog --list \
              --title="Escolha os defeitos que deseja ver" \
              --column="Número do defeito" --column="Gravidade" --column="Descrição" \
                992383 Normal "GtkTreeView quebra com seleções múltiplas" \
                293823 Alta "O Dicionário do MATE não faz uso do proxy" \
                393823 Crítica "A edição do menu não funciona no MATE 2.0"

### Exemplo de diálogo de lista

MateDialog exemplo de diálogo de lista

## 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.

O script de exemplo a seguir mostra como criar um diálogo de erro:

              #!/bin/bash

              matedialog --error \
              --text="Não conseguiu localizar /var/log/syslog."

#### Exemplo de diálogo de erro

MateDialog exemplo de diálogo de erro

### Diálogo de informação

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

O script de exemplo a seguir mostra como criar um diálogo de informação:

              #!/bin/bash

              matedialog --info \
              --text="Mesclagem completa. Foram atualizados 3 de 10 arquivos."

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

MateDialog exemplo de diálogo de informação

### Diálogo de pergunta

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

O script de exemplo a seguir mostra como criar um diálogo de pergunta:

              #!/bin/bash

              matedialog --question \
              --text="Tem certeza de que quer prosseguir?"

#### Exemplo de diálogo de pergunta

MateDialog exemplo de diálogo de pergunta

### Diálogo de aviso

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

O script de exemplo a seguir mostra como criar um diálogo de aviso:

#### Exemplo de diálogo de aviso

MateDialog exemplo de diálogo de aviso

## 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.

O script de exemplo a seguir mostra como criar um diálogo indicador de progresso:

            #!/bin/sh
            (
            echo "10" ; sleep 1
            echo "# Atualizando os registros do correio" ; sleep 1
            echo "20" ; sleep 1
            echo "# Reconfigurando os trabalhos do cron" ; sleep 1
            echo "50" ; sleep 1
            echo "Esta linha será simplesmente ignorada" ; sleep 1
            echo "75" ; sleep 1
            echo "# Reiniciando o sistema" ; sleep 1
            echo "100" ; sleep 1
            ) |
            matedialog --progress \
              --title="Registro de atualizações do sistema" \
              --text="Varrendo os registros de correio..." \
              --percentage=0

            if [ "$?" = -1 ] ; then
                    matedialog --error \
                      --text="Atualização cancelada."
            fi

### Exemplo de diálogo indicador de progresso

MateDialog exemplo de diálogo indicador de progresso

## 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.

O script de exemplo a seguir mostra como criar um diálogo de entrada de texto:

            #!/bin/sh

            if matedialog --entry \
            --title="Adicionar um item" \
            --text="Digite sua _senha:" \
            --entry-text "senha" \
            --hide-text
              then echo $?
              else echo "Nenhuma senha foi digitada"
            fi

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

MateDialog exemplo de diálogo de entrada de texto

## 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.

O script de exemplo a seguir mostra como criar um diálogo de informação textual:

            #!/bin/sh

            FILE=`matedialog --file-selection \
              --title="Selecione um arquivo"`

            case $? in
                     0)
                            matedialog --text-info \
                              --title=$FILE \
                              --filename=$FILE \
                              --editable 2>/tmp/tmp.txt;;
                     1)
                            echo "Nenhum arquivo foi selecionado.";;
                    -1)
                            echo "Nenhum arquivo foi selecionado.";;
            esac

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

MateDialog exemplo de diálogo de informação textual