# Руководство MateDialog

## Введение

MateDialog позволяет вам создавать следующие типы простых диалоговых окон:

- Календарь

- Выбор файла

- Список

- Значок уведомления

- Сообщение

  - Ошибка

  - Информация

  - Вопрос

  - Предупреждение

- Прогресс

- Ввод текста

- Текстовая информация

## Использование

Когда вы пишите сценарии, вы можете использовать MateDialog, чтобы создавать простые диалоговые окна, которые графически взаимодействуют с пользователем, как в следующих случаях:

- Вы можете создать диалоговое окно, чтобы получить информацию от пользователя. Например, вы можете попросить пользователя выбрать дату из календаря или выбрать файл из окна выбора файла.

- Вы можете создать диалоговое окно, чтобы предоставить информацию пользователю. Например, вы можете использовать окно с индикатором прогресса, чтобы указать текущее состояние операции или использовать окно предупреждения, чтобы оповестить пользователя.

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

Когда вы пишите команды MateDialog, убедитесь, что вы помещаете каждый аргумент в кавычки.

For example, use:

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

Do not use:

    matedialog --calendar --title=Holiday Planner

Если вы не используете кавычки, вы можете получить неожиданные результаты.

### Клавиша доступа

Клавиша доступа это клавиша, которая позволяет вам выполнять действие с клавиатуры, нежели используя мышь для выбора команды из меню или диалогового окна. Каждая клавиша доступа устанавливается с помощью подчёркнутой буквы в параметре, задающем текст меню или диалогового окна.

Некоторые окна MateDialog поддерживают использование клавиш доступа. Чтобы указать символ, который нужно использовать для клавиши доступа, поместите знак подчёркивания перед тем символом в тексте диалогового окна. Следующий пример показывает, как установить букву 'В' для клавиши доступа:

    "_Choose a name".

### Коды Выхода

MateDialog возвращает следующие коды выхода:

Код выхода | Описание
`0` | Пользователь нажал либо OK, либо Закрыть.
`1` | Пользователь либо нажал Отмена, либо использовал функции окна, чтобы закрыть диалоговое окно.
`-1` | Произошла неожиданная ошибка.
`5` | The dialog has been closed because the timeout has been reached.

### Общие параметры

Все диалоговые окна MateDialog поддерживают следующие общие параметры:

`--title`=`заголовок`

- Указывает заголовок диалогового окна.

`--window-icon`=`путь_к_значку`

- Указывает значок, который изображается в рамке диалогового окна. Существуют 4 запасных значка, доступных по следующим ключевым словам - 'info', 'warning', 'question' и 'error'.

`--width`=`ширина`

- Указывает ширину диалогового окна.

`--height`=`высота`

- Указывает высоту диалогового окна.

`--timeout`=`timeout`

- Specifies the timeout in seconds after which the dialog is closed.

### Параметры вызова справки

MateDialog предоставляет следующие параметры справки:

`--help`

- Показывает сокращённый текст помощи.

`--help-all`

- Показывает полный текст помощи для всех диалоговых окон.

`--help-general`

- Показывает текст помощи по общим параметрам диалоговых окон.

`--help-calendar`

- Показывает текст помощи по параметрам диалогового окна календаря.

`--help-entry`

- Показывает текст помощи по параметрам диалогового окна ввода текста.

`--help-error`

- Показывает текст помощи по параметрам диалогового окна сообщения об ошибке.

`--help-info`

- Показывает текст помощи по параметрам диалогового окна информации.

`--help-file-selection`

- Показывает текст помощи по параметрам диалогового окна выбора файла.

`--help-list`

- Показывает текст помощи по параметрам диалогового окна списка.

`--help-notification`

- Показывает текст помощи по параметрам значка уведомлений.

`--help-progress`

- Показывает текст помощи по параметрам диалогового окна индикатора прогресса.

`--help-question`

- Показывает текст помощи по параметрам диалогового окна вопроса.

`--help-warning`

- Показывает текст помощи по параметрам диалогового окна предупреждения.

`--help-text-info`

- Показывает текст помощи по параметрам диалогового окна текстовой информации.

`--help-misc`

- Показывает помощь по разнообразным параметрам.

`--help-gtk`

- Показывает помощь по параметрам GTK+ .

### Разнообразные параметры

MateDialog также может запускаться со следующими дополнительными параметрами:

`--about`

- Изображает диалоговое окно О программе MateDialog, которое содержит информацию о версии MateDialog, информацию об авторских правах и информацию о разработчике.

`--version`

- Изображает номер версии MateDialog.

### Параметры GTK+

MateDialog поддерживает стандартные параметры программ GTK+ . Для получения большей информации о GTK+ параметрах, выполните команду `matedialog -?`.

### Environment Variables

Normally, MateDialog 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.

## Диалоговое окно календарь

Use the `--calendar` option to create a calendar dialog. MateDialog returns the selected date to standard output. If no date is specified on the command line, the dialog uses the current date.

Диалоговое окно календарь поддерживает следующие параметры:

`--text`=`текст`

- Указывает текст, который будет изображён в диалоговом окне календаря.

`--day`=`день`

- Указывает день, который будет выделен в диалоговом окне календаря. `День` должен быть числом между 1 и 31 включительно.

`--month`=`месяц`

- Указывает месяц, который будет выделен в диалоговом окне календаря. `Месяц` должен быть числом между 1 и 12 включительно.

`--year`=`год`

- Указывает год, который будет выбран в диалоговом окне календаря.

`--date-format`=`формат`

- Указывает формат даты, в котором она будет возвращена после выбора из диалогового окна. Формат даты по умолчанию зависит от локальных настроек. `Формат` должен иметь вид, приемлемый функцией `strftime`, например `%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

### Пример диалогового окна календарь

MateDialog calendar dialog example

## Диалоговое окно выбора файла

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

Диалоговое окно выбора файлов поддерживает следующие параметры:

`--filename`=`имя_файла`

- Указывает файл или директорию, которая будет выбрана в диалоговом окне, когда оно впервые появится.

`--multiple`

- Позволяет выбирать сразу несколько файлов в окне выбора.

`--directory`

- Позволяет выбирать только директории в диалоговом окне выбора файла.

`--save`

- Устанавливает диалоговое окно в режим сохранения файла.

`--separator`=`разделитель`

- Указывает строку, которая будет использована для разделения возвращённого списка имён файлов.

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

### Пример диалогового окна выбора файла

MateDialog file selection dialog example

## Значок уведомления

`--text`=`текст`

- Указывает текст, который будет изображён в области уведомления.

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

            #!/bin/sh

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

### Пример значка уведомления

MateDialog notification icon example

## Диалоговое окно списка

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

Данные для этого диалогового окна должны указываться столбец за столбцом, строка за строкой. Данные могут быть поданы диалоговому окну через стандартный ввод. Каждая запись должна быть отделена символом новой строки.

Если вы используете параметр `--checklist` или `--radiolist`, каждая строка должна начинаться либо с 'TRUE', либо с 'FALSE'.

Диалоговое окно списка поддерживает следующие параметры:

`--column`=`столбец`

- Указывает заголовки столбцов, которые будут изображены в диалоговом окне списка. Вы должны указать параметр `--column` для каждого столбца, который вы хотите отобразить в диалоговом окне.

`--checklist`

- Указывает, что первый столбец в диалоговом окне списка содержит флажки.

`--radiolist`

- Указывает, что первый столбец в диалоговом окне содержит поля выбора.

`--editable`

- Позволяет редактирование изображаемых элементов.

`--separator`=`разделитель`

- Указывает строку-разделитель, используемую, когда диалоговое окно возвращает выбранные элементы.

`--print-column`=`столбец`

- Указывает, какой столбец нужно печатать при выборе элемента. По умолчания это 1-й столбец. Можно использовать 'ALL', чтобы печатать все столбцы из списка.

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"

### Пример диалогового окна списка

MateDialog list dialog example

## Диалоговое окно сообщений

MateDialog может создавать четыре типа диалоговых окон сообщений:

- Ошибка

- Информация

- Вопрос

- Предупреждение

Для каждого типа используйте параметр `--text`, чтобы задать текст в диалоге.

### Диалоговое окно ошибки

Используйте параметр `--error`, чтобы создать диалоговое окно ошибки.

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

              #!/bin/bash

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

#### Пример диалогового окна ошибки

MateDialog error dialog example

### Диалоговое окно информации

Используйте параметр `--info`, чтобы создать диалоговое окно информации.

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

              #!/bin/bash

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

#### Пример диалогового окна информации

MateDialog information dialog example

### Диалоговое окно вопроса

Используйте параметр `--question`, чтобы создать диалоговое окно вопроса.

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

              #!/bin/bash

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

#### Пример диалогового окна вопроса

MateDialog question dialog example

### Диалоговое окно предупреждения

Используйте параметр `--warning`, чтобы создать диалоговое окно предупреждения.

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

              #!/bin/bash

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

#### Пример диалогового окна предупреждения

MateDialog warning dialog example

## Диалоговое окно индикатора прогресса

Используйте параметр `--progress`, чтобы создать диалоговое окно индикатора прогресса.

MateDialog считывает данные из стандартного ввода строка за строкой. Если строка начинается с #, то текст, следующий за этим префиксом размещается в диалоговом окне. Если строка содержит только число, то индикатор прогресса устанавливается на этот процент выполнения.

Диалоговое окно индикатора прогресса поддерживает следующие параметры:

`--text`=`текст`

- Указывает текст, который будет изображён в диалоговом окне.

`--percentage`=`процент`

- Указывает начальное состояние индикатора прогресса.

`--auto-close`

- Диалоговое окно закрывается, когда процент выполнения достиг 100% .

`--pulsate`

- Указывает, что индикатор прогресса пульсирует до тех пор, пока из стандартного ввода не будет прочитан символ конца файла EOF.

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

### Пример диалогового окна индикатора прогресса\

MateDialog progress dialog example

## Диалоговое окно ввода текста

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

Диалоговое окно ввода текста поддерживает следующие параметры:

`--text`=`текст`

- Указывает текст, который будет изображён в диалоговом окне (но не в поле ввода).

`--entry-text`=`текст`

- Указывает текст, который будет изображён в поле ввода диалогового окна.

`--hide-text`

- Скрывает текст в поле ввода диалогового окна.

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

### Пример диалогового окна ввода текста

MateDialog text entry dialog example

## Диалоговое окно текстовой информации

Используйте параметр `--text-info`, чтобы создать диалоговое окно текстовой информации.

Диалоговое окно текстовой информации поддерживает следующие параметры:

`--filename`=`имя_файла`

- Указывает имя файла, который будет загружен в окно текстовой информации.

`--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=`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

### Пример диалогового окна текстовой информации

MateDialog text information dialog example