# MateDialog 手册

## 介绍

MateDialog 可以创建下列类型的简单对话框：

- 日历

- 文件选择框

- 列表框

- 提示图标

- 消息框

  - 错误框

  - 信息框

  - 询问框

  - 警告框

- 进度框

- 文本框

- 文本信息框

## 用法

在您写脚本时，可以使用MateDialog 创建简单的交互式对话框，例如：

- 您可以创建从用户那儿获得信息的对话框。例如，您可以提示用户从日历对话框中选择日期，或者从文件选择框里选择一个文件。

- 您可以创建向用户提供信息的对话框。例如，您可以用进度条来显示一个操作的当前运行状态，或者用一个警告框提醒用户。

当用户关闭了对话框，MateDialog 将输出对话框操作的文本到显示器。

当您写了 MateDialog 命令，确保每个参数用双引号括起来。

例如，使用 :

    matedialog --calendar --title="假期安排"

不要用:

    matedialog --calendar --title=假期安排

如果您没有使用双引号，可能会产生不可预料的结果。

### 访问键

访问键允许您用键盘来执行一个操作，而不是用鼠标点击菜单命令或对话框按钮。每个访问键有一个标识符，是一个在菜单或对话框选项上的带下划线的字母。

一些 MateDialog 对话框支持使用访问键，要指定一个字符用于访问键，在对话框的文本字符前面加一个下划线，下面的例子是如何让字母“C”作为访问键：

    "选择(_C)".

### 退出代码

MateDialog 返回以下退出代码：

退出代码 | 描述
`0` | 用户按了 确定 或 关闭。
`1` | 用户按了 取消，或者点了窗口关闭按钮。
`-1` | 发生了一个有异常。
`5` | 对话框因超时而关闭。

### 常规选项

所有 MateDialog 对话框支持以下常规选项：

`--title`=`标题`

- 指定对话框的标题。

`--window-icon`=`图标路径`

- 指定显示在窗口框架上的图标，有四个图标也可以用下列关键字 - 'info'， 'warning'， 'question' 和 'error'。

`--width`=`宽度`

- 指定对话框的宽度。

`--height`=`高度`

- 指定对话框的高度。

`--timeout`=`超时`

- 指定超出时间(秒)后对话框自动关闭。

### 帮助选项

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 -?` 命令。

### 环境变量

通常，MateDialog 会检测启动它的终端窗口，并保持在它之上。这个行为也可以通过不设置 `WINDOWID` 环境变量来禁用。

## 日历对话框

使用 `--calendar` 选项来创建日历对话框。MateDialog 返回选定的日期，并把它输出到显示器，如果没有在命令行指定日期，就使用当前系统日期。

日历对话框支持以下选项：

`--text`=`文本`

- 指定日历对话框里显示的文本。

`--day`=`日`

- 指定日历对话框中的天数，`day` 必须是介于 1~31 之间的数字。

`--month`=`月`

- 指定日历对话框中的月份，`month` 必须是介于 1~12 之间的数字。

`--year`=`年`

- 指定日历对话框中的年份。

`--date-format`=`日期格式`

- 指定选定的日期返回时的样式，默认的格式取决于您的区域设置，`日期格式` 必须可以被 `strftime` 函数接受，例如 `%A %d/%m/%y`。

下面的脚本示范了如何创建一个日历对话框：

            #!/bin/sh

            if matedialog --calendar \
            --title="选择日期" \
            --text="通过点击选择日期。" \
            --day=10 --month=8 --year=2004
              then echo $?
              else echo "没有选择日期"
            fi

### 日历对话框范例

MateDialog 日历对话框范例

## 文件选择对话框

使用 `--file-selection` 选项创建一个文件选择对话框，MateDialog 在标准输出返回选中的文件或目录。默认的文件选择对话框模式是打开对话框。

文件对话框支持以下选项：

`--filename`=`文件名`

- 指定文件选择对话框在第一次显示时，选定的文件或文件夹。

`--multiple`

- 允许在文件选择对话框里选中多个文件。

`--directory`

- 在文件选择对话框里只允许选中文件夹

`--save`

- 设置文件选择对话框模式为保存对话框。

`--separator`=`分隔符`

- 指定用于分隔返回的文件名列表的字符。

下面的脚本示范了如何创建一个文件选择对话框：

            #!/bin/sh

            FILE=`matedialog --file-selection --title="选择文件"`

            case $? in
                     0)
                            echo "\"$FILE\" 被选中。";;
                     1)
                            echo "没有选择文件。";;
                    -1)
                            echo "没有选择文件。";;
            esac

### 文件选择对话框范例

MateDialog 文件选择对话框范例

## 通知区域图标

`--text`=`文本`

- 指定显示在通知区域的文本。

下面的脚本示范了如何创建一个通知区域图标：

            #!/bin/sh

            matedialog --notification\
              --window-icon="info" \
              --text="有系统更新软件包！"

### 通知区域图标范例

MateDialog 通知图标范例

## 列表框

使用 `--list` 选项创建一个列表框，MateDialog 在标准输出返回选中行的第一列项目。

对话框里的数据必须指定行和列，可以由标准输入提供，每一项都必须由换行符分隔。

如果您使用 `--checklist` 或 `--radiolist` 选项，每一行必须由“TRUE”或“FALSE”开始。

列表框支持以下选项：

`--column`=`列`

- 指定列表框显示的列标题，您必须为每个要显示的列，用 `--column` 指定一个列标题。

`--checklist`

- 指定列表框的第一列包含一个复选框。

`--radiolist`

- 指定列表框的第一列包含单选按钮。

`--editable`

- 指定显示的项可以编辑。

`--separator`=`分隔符`

- 指定当列表框返回选中项时，使用什么字符。

`--print-column`=`列`

- 指定选择列上显示什么，默认是“1”，“ALL”用于在列表上显示所有列。

下面的例子示范了如何创建一个列表框：

            #!/bin/sh

            matedialog --list \
              --title="选择您想查看的 Bugs" \
              --column="Bug 编号" --column="严重" --column="描述" \
                992383 Normal "多选时 GtkTreeView 崩溃" \
                293823 High "MATE 字典不能使用代理" \
                393823 Critical "菜单编辑器在 MATE 2.0 中不能运行"

### 列表框范例

MateDialog 列表框范例

## 消息框

MateDialog 可以创建四种消息框：

- 错误框

- 信息框

- 询问框

- 警告框

对于每一种类型，使用 `--text` 选项来指定显示在对话框里的文本。

### 错误框

使用 `--error` 选项创建一个错误框。

下面的脚本示范了如何创建一个错误框：

              #!/bin/bash

              matedialog --error \
              --text="找不到 /var/log/syslog."

#### 错误框范例

MateDialog 错误框范例

### 信息框

使用 `--info` 选项创建一个信息框。

下面的脚本示范了如何创建一个信息框：

              #!/bin/bash

              matedialog --info \
              --text="全部合并。更新第 3 个文件，总共 10 个。"

#### 信息框范例

MateDialog 信息框范例

### 询问框

使用 `--question` 选项创建一个询问框。

下面的脚本示范了如何创建一个询问框：

              #!/bin/bash

              matedialog --question \
              --text="您确定要执行吗？"

#### 询问框范例

MateDialog 询问框范例

### 警告框

使用 `--warning` 选项创建一个警告框。

下面的脚本示范了如何创建一个警告框：

              #!/bin/bash

              matedialog --warning \
              --text="断开电源以防止冲击电流。"

#### 警告框范例

MateDialog 警告框范例

## 进度框

使用 `--progress` 选项创建一个进度框。

MateDialog 从标准输入一行行读取数据。如果某一行以 # 开头，进度框里的文本会被那一行上的文本替换，如果某一行只是一个数字，数字会被换成进度条的百分比。

进度框支持以下选项：

`--text`=`文本`

- 指定显示在进度框里的文本。

`--percentage`=`百分比`

- 指定进度框开始时的百分比设定。

`--auto-close`

- 当达到 100% 时自动关闭对话框。

`--pulsate`

- 指定进度条跳动，直到从标准输入读到一个 EOF 文件结束符。

下面的脚本示范了如何创建一个进度框：

            #!/bin/sh
            (
            echo "10" ; sleep 1
            echo "# 更新邮件日志" ; sleep 1
            echo "20" ; sleep 1
            echo "# 复位定时计划任务" ; sleep 1
            echo "50" ; sleep 1
            echo "这一行会被忽略" ; sleep 1
            echo "75" ; sleep 1
            echo "# 重启系统" ; sleep 1
            echo "100" ; sleep 1
            ) |
            matedialog --progress \
              --title="更新系统日志" \
              --text="扫描邮件日志..." \
              --percentage=0

            if [ "$?" = -1 ] ; then
                    matedialog --error \
                      --text="更新被取消。"
            fi

### 进度框范例

MateDialog 进度框范例

## 文本框

使用 `--entry` 选项，创建一个文本框，MateDialog 将文本框的内容返回到标准输出。

文本框支持以下选项：

`--text`=`文本`

- 指定在文本框中显示的文本。

`--entry-text`=`文本`

- 指定显示在文本框的文本域里的文本。

`--hide-text`

- 隐藏文本框中文本域中的内容。

下面的脚本示范了如何创建一个文本框：

            #!/bin/sh

            if matedialog --entry \
            --title="添加一项" \
            --text="请输入您的密码：" \
            --entry-text "密码" \
            --hide-text
              then echo $?
              else echo "没有输入密码"
            fi

### 文本框范例

MateDialog 文本框范例

## 文本信息框

使用 `--text-info` 选项来创建一个文本信息框。

文本信息框支持以下选项：

`--filename`=`文件名`

- 指定一个加载到文本信息框里的文件。

`--editable`

- 显示的文本允许编辑，当对话框关闭后，编辑后的文本显示到显示器上。

下面的脚本示范了如何创建一个文本信息框：

            #!/bin/sh

            FILE=`matedialog --file-selection \
              --title="选择一个文件"`

            case $? in
                     0)
                            matedialog --text-info \
                              --title=$FILE \
                              --filename=$FILE \
                              --editable 2>/tmp/tmp.txt;;
                     1)
                            echo "没有选择文件。";;
                    -1)
                            echo "没有选择文件.";;
            esac

### 文本信息框范例

MateDialog 文本信息框范例