# GNOME 辅助功能开发者指南

GNOME 辅助功能指南是为那些想确保自己的程序能为更广泛的用户使用的开发人员准备的。本指南同时涵盖了许多第508节的要求。

2008
Vincent Alexander
2001, 2002
Calum Benson, Brian Cameron, Bill Haneman, Padraig O'Briain, Sharon Snider
GNOME 文档项目

在自由软件基金会发表的 GNU 自由文档许可证(GFDL)条款的约束下，此文档可以复制、分发和修改。许可证版本应为 1.1 或更新，章节应未加篡改，封面未经涂写。您可以从 这里下载一份 GFDL，或从本手册附带的 COPYING-DOCS 文件中获取它。

此手册是 GNOME 手册系列的一部分，依照 GFDL 发布。如果想单独分发此手册，您需要向手册添加一份许可证协议，如许可证第 6 节所述。

许多名字被各公司注册为商标，以区别它们的产品和服务。任何 GNOME 文档中出现这些名字时，Gnome 文档项目作者都对它们加以留意，将其全名大写或首字母大写。

DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER UNDERSTANDING THAT:

1. DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND

2. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.

Vincent
Alexander
GNOME 文档项目
Calum
Benson
GNOME 文档项目
Brian
Cameron
GNOME 文档项目
Bill
Haneman
GNOME 文档项目
Padraig
O'Briain
GNOME 文档项目
Sharon
Snider
GNOME 文档项目
GNOME 2.24 辅助功能开发者指南 V2.24.0
2008年9月

GNOME 文档项目

GNOME 文档项目

GNOME 2.24 辅助功能开发者指南 V2.24.0
2008年9月

GNOME 文档项目

GNOME 文档项目

本手册描述 GNOME 2.24 桌面。

## 反馈

报告 bug 或者为 GNOME 桌面和本手册提供建议, 请点击 GNOME 反馈页面.

keyring
keyrings@163.com
2013
keyring

## 什么是辅助功能？

辅助功能是指协助残疾人士参与大量日常活动，包括日常工作以及服务、产品、资讯的使用。GNOME 包含一系列库与支持框架能让残疾人士使用 GNOME 用户环境的所有功能。

因此，必要时综合利用辅助技术——语音接口，屏幕阅读器，复用输入设备等等——可以帮助那些永久性或暂时性残疾人士便捷地使用 GNOME 桌面和应用程序。辅助技术对那些不在家里或办公室中使用电脑的人也非常有用。比如，如果你被堵在车流之中，你可以使用语音输入和输出来查阅你的电子邮件。

辅助技术通过使用辅助工具包 (ATK) 的 API 接收来自应用程序的信息，ATK 可以在 GNOME 仓库中找到。由于辅助 API 内置到了 GNOME 的 widgets 中，所以你不需做额外工作就可以让你的 GNOME 程序合理运行在辅助技术上。例如，辅助技术能够自动读取你设置在程序中的部件的标签（比如 GTK 的函数调用：`gtk_label_set_text()` 或者 `gtk_button_new_with_label()`）。它们也能找到与某个部件相关联的任何提示文本，然后使用该文本来向用户描述那个部件。

当然，你也可以多花点心思，利用辅助技术来让你的程序运行的更加流畅。这除了可以帮助个人用户，也可以让你的产品在政府部门和教育市场中更具吸引力，因为如今法律要求这个领域的很多应用必须得无障碍。

### 残疾类型

仅在美国，大约有3000万人因为不合理设计而无法便利使用电脑。在全球范围下，大约有8%的互联网使用者有不同程度的残疾。残疾可分为以下几种：

- 视觉障碍 ——包括弱视（视力昏暗模糊，远/近视，色盲和视力狭窄）到完全失明。一些糟糕的文本字体颜色选择和需要手眼协调的任务（比如移动鼠标）都可能为这些用户造成困难。

- 运动障碍 ——肌肉控制力差或虚弱到不足以使用标准键鼠。例如，他们可能无法同时按住两个键，或者更容易意外按错。

- 听觉障碍 —— 包括弱听而听不懂到完全失聪。那些单靠声音来传达重要信息的应用程序会对这部分用户造成困难。

- 认知与语言障碍 ——包括阅读障碍与记忆障碍，只靠说写来处理与理解事物。复杂或不一致的显示，或者拙劣的词汇选择都会造成这部分用户使用电脑困难。

- 癫痫疾病——对一些敏感的用户，某些光或声音会造成癫痫发作。

### 辅助功能在 GNOME 中如何工作

辅助工具包 (ATK) 描述了一组接口，要访问它们就需要通过 GUI 组件自行实现。这些接口是工具包无关的，意思就是你可以用任意部件集来实现，比如 GTK，Motif 或者 Qt 。

The implementation for the GTK widgets is in a module called GAIL (GNOME Accessibility Implementation Library), which is dynamically loadable at runtime by a GTK application. Once loaded, those parts of your application that use standard GTK widgets will have a basic level of accessibility, without you having to modify your application at all. If GAIL is not loaded, GTK widgets will have a default accessibility implementation that essentially returns no information, though it nominally conforms to the ATK API. Applications which use Bonobo controls, particularly out-of-process ones, also load accessibility support code from module libgail-gnome. Whether or not applications on the GNOME desktop automatically load these accessibility support libraries depends on the value of a gconf key, "/desktop/gnome/interface/accessibility"; a boolean value of "true" enables support for assistive technologies and applications which call gnome_program_init will automatically load the appropriate accessibility libraries at runtime. "Pure GTK+ applications", e.g. those that use gtk+ but do not link to libgnome, rely on the value of the GTK_MODULES environment variable, which must be set to "gail:atk-bridge" in order to enable assistive technology support.

长久以来，大部分其他桌面平台所使用的辅助技术必须为桌面应用维护一个复杂的离屏模式，这种模式基于对操作系统事件的监听，使用不受支持的操作系统、应用程序特性和 API，还有一些其他高度不可移植的技术。这就使得辅助技术支持有点 "不健壮"，需要特定的操作系统和指定的应用程序，甚至还要指定的应用程序版本。相反，在 GNOME 桌面，通过 GNOME 辅助功能框架，使用服务提供者接口（SPI）独立工具包，AT（辅助技术） 需要的所有信息均可由运行的应用程序提供。SPI 为基于 UNIX 的 AT 提供一些内置服务，比如屏幕阅读器和屏幕放大镜。通过一致而稳定的 API 从运行的程序中获取辅助信息，可以在大多数情况下避免使用离屏模式。对应用程序的辅助功能支持一般通过合适的 API （比如，ATK 多用于原生C程序而Java辅助 API 用于Java 应用）内置在应用程序工具包中，然后通过相应的 "bridge" 导出成通用 "AT-SPI" 接口（见下图）。

#### GNOME 辅助功能架构

GNOME 辅助功能架构图解

GNOME 内置辅助功能支持意味着使用 GNOME 部件创建应用程序可以 "免费" 获得辅助技术的支持，而不用额外使用与内置支持相冲突的迂回方法。

如果一个 gtk+/GNOME 部件遵循本文档中的普遍辅助指南，实现了 ATK 接口并在用户界面上扮演合适的角色，则它是具有辅助性的。 ATK 的执行由 "stock" GNOME 部件工具集提供，而且大多数情况下，由现有 GTK+/GNOME 部件派生出来的新部件同时也会继承合适的辅助功能支持。

Though GNOME's built-in accessibility support provides significant functionality without any accessibility-specific code changes on the part of the application, applications can often improve on the default descriptions provided for some of the widgets, and tailor them to that widget's specific purpose in your application, via straightforward calls to ATK methods in the application. For instance, in most cases applications should add or change the textual descriptions for these widgets with the appropriate ATK function call, so that an assistive technology can describe their purpose or state to the user. See Coding Guidelines for Supporting Accessibility for more information.

如果你的程序使用自定义部件，可能需要做些工作让它们得以使用辅助技术。参阅 让自定义组件获得辅助功能 和 使用辅助 API 的示例 获取更多信息。

此外，关于 GTK/GTK+ 更多深入内容，请参阅 GTK+ 参考手册 , ATK 指南的 GTK 章节, GNOME 网站托管的 GTK+ 2.0 教程 和官方 GTK+ FAQ。

### 开发者快速指南

这有一些常用出发点：

#### 如何确定应用程序是否具有辅助功能？

To start right in, see Making a GNOME Application Accessible - Overview. For a pre-coding perspective, see User Interface Guidelines for Supporting Accessibility or Coding Guidelines for Supporting Accessibility. For a checklist of post-design test items, see User Interface Checklist.

#### 有哪些常见陷阱？

用户界面审查清单涵盖了所有设计阶段容易被忽略的地方。

#### 如何实现常见的 ATK 功能？

可以在这里找到一份常见 ATK 调用的简短列表。

#### 如何实现更复杂的 ATK 功能？

参考 让自定义组件获得辅助功能 和 使用辅助功能 API 的示例 来获取更多信息。

#### ATK,、AT-SPI、 GAIL 和 GTK+ 介绍

GNOME 辅助功能架构

ATK 工具包可以提供额外辅助功能支持让 GNOME 使用者充分利用电脑。ATK 用于诸如屏幕阅读器、放大镜和输入设备等工具来允许通过其他方式与桌面进行富交互。详情可参阅 ATK SourceForge 的项目 和 ATK 库。

AT-SPI 是基础服务接口，用于辅助技术查询和接收来自正在运行的程序的通知。全部 API 可以查阅 here。额外材料可参阅 KDE 辅助功能开发者社区 。

GAIL (GNOME Accessibility Implementation Library) 是 ATK 辅助功能接口的默认实现。GTK 工具集早已通过 GAIL 模块与 ATK 进行了绑定。许可条款、下载中心和其他信息可参阅 这里 。 GAIL 源码 也提供了一份出色的教程来说明 ATK 的高级用法。此外，你也可能对 GAIL 参考手册 感兴趣。

GTK+ 是个创建图形用户界面的 UI 库。可运行于多种类UNIX平台、Windows和基于帧缓存的设备。GTK+ 在 GNU Library General Public License (GNU LGPL)许可下发行。

此外，关于 GTK/GTK+ 更多深入内容，请参阅 GTK+ 参考手册,ATK 指南的 GTK+ 章节, GNOME 网站托管的GTK+ 2.0 教程 和官方GTK+ FAQ。

### 让一个 GNOME 应用程序具有辅助功能 - 综述

如果你的应用程序只使用标准 GTK 部件，你可以做很少甚至不做任何事情就能让程序获得（适当的）辅助功能。但要注意那些没有文字说明的GUI对象，比如没有文本标签的图形按钮或者没有工具提示信息的状态指示器。

You can probably also improve on the default descriptions provided for some of the widgets, and tailor them to that widget's specific purpose in your application. You should add or change the textual descriptions for these widgets with the appropriate ATK function call, so that an assistive technology can describe their purpose or state to the user. See Coding Guidelines for Supporting Accessibility for more information.

如果你的程序使用自定义部件，可能需要做些工作以使这些部件利用辅助技术。参阅 让自定义组件获得辅助功能 和 使用辅助功能 API 的示例 获取更多信息。更多详细内容也可参见 Marc Mulcahy 的 2002 GUADEC 演示文档, “制作具有辅助功能的 GNOME 应用程序”。

### 获取辅助功能的编程指南

这里列出了一些可以在代码里做的事情，让程序更好的利用辅助技术。（当你想设计GUI的时候，可以看看后文里提到的这份列表 支持辅助功能的UI ）：

- 用于那些不显示短字符串的组件（比如图形按钮），使用 `atk_object_set_name()`为它指定一个名字。你可以用于纯图片按钮、具有逻辑分组的面板、文本区域等等。

- 如果你没有为组件提供提示信息，使用 `atk_object_set_description()` 函数为用户提供一个辅助说明。例如，为一个 关闭 按钮提供辅助说明：

  #### 为 GtkButton 提供辅助性说明

      {
        AtkObject *obj;
        obj = gtk_widget_get_accessible(button);
        atk_object_set_description(obj,_("Closes the window"));
      }

- 使用 `atk_image_set_description()` 可以为程序中所有图片图标提供一个文本说明。

- 如果多个组件逻辑上是一组的，建议将它们放在一个容器里。

- Whenever you have a label that describes another component, use `atk_relation_set_add_relation()` so that assistive technologies can find the component with which the label is associated. (If you associate the label with the component using `gtk_label_set_mnemonic_widget()`, the `ATK_RELATION_LABEL_FOR` relation is generated automatically, so the following code would not be necessary):

  #### 为一个 GtkWidget 关联一个 GtkLabel

      {
        GtkWidget *widget;
        GtkLabel *label;

        AtkObject *atk_widget, *atk_label;
        AtkRelationSet *relation_set;
        AtkRelation *relation;
        AtkObject *targets[1];

        atk_widget = gtk_widget_get_accessible(widget);
        atk_label = gtk_widget_get_accessible (GTK_WIDGET(label));

        relation_set = atk_object_ref_relation_set (atk_label);
        targets[0] = atk_widget;

        relation = atk_relation_new(targets,1, ATK_RELATION_LABEL_FOR);
        atk_relation_set_add(relation_set,relation);
        g_object_unref(G_OBJECT(relation));
      }

- 如果创建了一个自定义 widget，要确认是否支持辅助功能。自定义组件通常继承于其他 GTK 部件，所以必要时得重写辅助功能信息。更多信息请参考 让自定义组件获得辅助功能 。

- 不要重复造轮子！如果你的 GUI 有一个非辅助性的容器，那么该容器内的任何组件都可能失去辅助性。

### 辅助功能 API

这里是一部分基础 API 调用，你可以用来确认程序是否利用辅助技术并工作良好。全部的辅助功能 API 非常全面，比如可以让你写出自定义辅助部件。

#### 常用 ATK API 调用

API | 描述
--- | ---
`AtkObject* gtk_widget_get_accessible (GtkWidget*)` | Returns the accessible object that describes the specified GTK widget to an assistive technology.
`void atk_object_set_name (AtkObject*, const gchar*)` | 为辅助对象命名。例如，如果对象是个图形按钮，按下会使得程序退出，那你可以为它命名为 "退出"。
`void atk_object_set_description (AtkObject*, const gchar*)` | 为辅助对象设置文字说明。例如，如果对象是个图形化的"关闭"按钮，那文字说明可以写成"关闭窗口"。
`AtkRelation* atk_relation_new (AtkObject**, gint, AtkRelationType)` | 在指定的键与指定的目标对象列表之间创建一个新的关系。这个关系通常指的是一个部件以某种方式关联到另一个之间的辅助技术。例如，同一个窗口下，有一个特定的 GtkLabel 才是 GtkTreeView 的标题。
`void atk_image_set_description (AtkImage*, const gchar*)` | 为图片辅助对象设置文字说明。例如，如果对象是面板内的一个虚拟桌面的缩略图，这个文字说明可以写成 "桌面 1 内的窗口排列图"。

### 使用辅助功能 API 的示例

前文提过，如果使用标准 GTK 部件或者任何其他实现了 ATK 接口的部件库，你可以只做一点甚至不做任何事情就可以让你的应用程序获得辅助功能。这样的话，通常只需做两件事：

- 使用 `atk_object_set_description()` 或者 `atk_image_set_description():` 为控件和图片提供文字说明

  #### 为按钮设置辅助功能说明

      {
         AtkObject *obj;
         obj = gtk_widget_get_accessible(button);
         atk_object_set_description(obj,_("Opens Preferences dialog"));
      }

- 使用 `atk_relation_new()` and `atk_relation_set_add()` 在任意特殊组合中的部件之间指定关系

  #### 在两个控件之间指定辅助关系

      {
        GtkWidget *widget;
        GtkLabel *label;

        AtkObject *atk_widget, *atk_label;
        AtkRelationSet *relation_set;
        AtkRelation *relation;
        AtkObject *targets[1];

        atk_widget = gtk_widget_get_accessible (widget);
        atk_label = gtk_widget_get_accessible (GTK_WIDGET(label));

        relation_set = atk_object_ref_relation_set (atk_label);
        targets[0] = atk_widget;

        relation = atk_relation_new(targets,1, ATK_RELATION_LABEL_FOR);
        atk_relation_set_add(relation_set,relation);
        g_object_unref(G_OBJECT(relation));
      }

The examples in the rest of this section are mostly to give you a flavor of the scope of the ATK. They cover techniques that you may never need to use as an application developer, although they may be of interest if you are writing your own custom widgets (see Making Custom Components Accessible) or if you want to write an assistive technology application. Whatever the purpose, the GAIL source code serves as an excellent tutorial for advanced ATK usage. Please note that since GTK+ 3.1.10, Gail has been merged into GTK+ and is no longer a module on its own.

#### Gtk 模块

程序使用 GAIL（GTK 部件的辅助功能实现库）时，它会被当作 GTK 模块引入程序。GTK 模块在 `GTK_MODULES` 环境变量指定了模块名称时，会被加载到程序空间。如果有多个模块库，以冒号间隔。例如：

`setenv GTK_MODULES "libgail:libtestprops"`

所有 GTK 模块都有一个`gtk_module_init()` 函数。

#### 收集一个应用程序的辅助信息

程序若想利用 ATK 调用，需要做下列一件（或以上）的事情：

1. 创建一个事件监视器，比如使用 `atk_add_focus_tracker()` 函数：

       atk_add_focus_tracker (_my_focus_tracker);

   `_my_focus_tracker()` 函数原型：

       void _my_focus_tracker (AtkObject *aobject);

2. 建立一个全局事件监听器，使用 atk_add_global_event_listener()：

       mouse_watcher_focus_id =   atk_add_global_event_listener(_my_global_listener,"Gtk:GtkWidget:enter_notify_event");

   `_my_global_listener` 拥有一个 Glib GSignalEmissionHook 原型。这个例子说明，一个 GtkWidget 对象无论何时触发一个 enter_notify_even 信号，都会调用 `_my_global_listener()`。

3. 下列函数调用可以访问 ATK 顶层对象。

       AtkObject *root_obj = atk_get_root();

   This returns an AtkObject which contains all toplevel windows in the currently running program. The user could then navigate through the object hierarchy by accessing the root object's children, which corresponds to the toplevel windows.

#### 查询一个 AtkObject 的接口

在程序中定位到具有辅助性 AtkObject 的对象后 (比如使用 `gtk_widget_get_accessible()`)，你可以用不同方式查到哪些接口已被实现：

1. 可以使用提供的 `ATK_IS_...` 宏，例如：

   - `ATK_IS_ACTION(atkobj)`

   - `ATK_IS_COMPONENT(atkobj)`

   - 等等。（每个接口都有一个）

   如果宏返回 `TRUE`，则该接口可安全用于那个 ATK 对象上。

2. 调用 `atk_object_get_role()` 来测试 AtkObject 的角色。任何已知角色均有一个指定数字对应 ATK API。

#### 建立一个 ATK 信号处理函数

使用 `column_inserted` 信号来举例：

    table_column_inserted_id = g_signal_connect_closure_by_id (my_atk_obj,
    g_signal_lookup("column_inserted", G_OBJECT_TYPE(my_atk_obj)), 0,
    g_cclosure_new(G_CALLBACK (_my_table_column_inserted_func), NULL, NULL), FALSE);

这会使无论何时 AtkObject `my_atk_object` 发出一个 column_inserted 信号，都会调用 `_my_table_column_inserted_func()`。

Connecting to a signal is slightly different if the signal supports detail. The `children_changed` signal supports the `add` detail. To connect to a signal when the `add` detail is also specified, this technique is used:

    child_added_id = g_signal_connect_closure (my_atk_obj,"children_changed::add",
    g_cclosure_new (G_CALLBACK(_my_children_changed_func), NULL, NULL), FALSE);

This will cause `_my_children_changed_func()` to be called whenever a `children_changed` signal with the `add` detail is emitted on the AtkObject `my_atk_obj`.

#### 实现一个 ATK 对象

你可能需要为那些未在 GAIL（或者其他部件集中的同等库） 中实现辅助功能的部件亲自动手实现 ATK 对象。该实现应该作为一个 GTK 模块，而且要被包含在 `GTK_MODULES` 环境变量中，以使之在运行时被加载。

##### 注册

这个例子中，我们假设一个对象叫 GTK_TYPE_MYTYPE，ATK 的实现叫 MYATKIMP_TYPE_MYTYPE，需要的工厂叫 MYATKIMP_TYPE_MYTYPE_FACTORY。

为 GTK 对象注册一个 ATK 实现，需要在模块的 `gtk_module_init()` 函数中做以下步骤：

1. 访问默认注册表：

       default_registry = atk_get_default_registry();

2. 在该模块的 `gtk_module_init()`函数中注册 ATK 对象，函数调用如下：

       atk_registry_set_factory_type (default_registry, GTK_TYPE_MYTYPE,
       MYATKIMP_TYPE_MYTYPE_FACTORY);

这样将把 AtkObject 的实现 GTK_TYPE_MYTYPE 注册到 MYATKIMP_TYPE_MYTYPE_FACTORY中。工厂实现后就知道如何构建 MYATKIMP_TYPE_MYTYPE类型的对象了。

##### 工厂

The factory must be implemented as a child of class type ATK_TYPE_OBJECT_FACTORY and must implement the function `create_accessible()`. This function must create an appropriate AtkObject. A factory can be used to create more than one type of object, in which case its `create_accessible()` function will need to be smart enough to build and return the correct AtkObject.

##### ATK Implementation for a Specific Object

所有 GObject 均要实现一个 `get_type()` 函数。使用上面的命名惯例将函数命名为 `myatkimp_mytype_get_type()`。

In this function, you specify which interfaces your object implements. If the following logic were included in this `get_type()` function, this object would implement the ATK_TEXT interface:

###### `get_type()` 函数示例

    static const GInterfaceInfo atk_text_info =
    {
       (GInterfaceInitFunc) atk_text_interface_init,
       (GInterfaceFinalizeFunc) NULL,
       NULL
    };

    g_type_add_interface_static (type, ATK_TYPE_TEXT,
                                 &atk_text_info);

函数 `atk_text_interface_init()` 需要实现的函数原型如下：

    void atk_text_interface_init (AtkTextIface *iface);

This function would connect the interface function calls to the specific implementation as follows:

###### 连接自定义接口与一个 AtkObject 实现

    void
    atk_text_interface_init (AtkTextIface *iface)
    {
       g_return_if_fail (iface != NULL);
       iface->get_text = myatkimp_mytype_get_text;
       iface->get_character_at_offset = myatkimp_mytype_get_character_at_offset;
       ...
    }

Then the functions `myatkimp_mytype_get_text()`, `myatkimp_mytype_get_character_at_offset()`, and the rest of the ATK_TEXT interface functions would need to be implemented.

##### AtkObject 实现

AtkObjects are GObjects, and all GObjects need to specify the `get_type()` function. Here is an example that sets up a class and instance initializer. This `get_type()` function also specifies that the object implements ATK_TEXT and specifies the parent object to be MYATKIMP_MYPARENTTYPE.

###### `get_type()` 的实现示例

    GType
    myatkimp_mytype_get_type (void)
    {
       static GType type = 0;

       if (!type)
       {
          static const GTypeInfo tinfo =
          {
             sizeof (GailLabelClass),
             (GBaseInitFunc) NULL,                              /* base init */
             (GBaseFinalizeFunc) NULL,                          /* base finalize */
             (GClassInitFunc) myatkimp_mytype_class_init,       /* class init */
             (GClassFinalizeFunc) NULL,                         /* class finalize */
             NULL,                                              /* class data */
             sizeof (GailLabel),                                /* instance size */
             0,                                                 /* nb preallocs */
             (GInstanceInitFunc) myatkimp_mytype_instance_init, /* instance init */
             NULL                                               /* value table */
          };

          /* Set up atk_text_info structure used below */
          static const GInterfaceInfo atk_text_info =
          {
             (GInterfaceInitFunc) atk_text_interface_init,
             (GInterfaceFinalizeFunc) NULL,
             NULL
          };

          /* Set up typename and specify parent type */
          type = g_type_register_static (MYATKIMP_MYPARENTTYPE,
                "MyatkimpMytype", &tinfo, 0);

          /* This class implements interface ATK_TYPE_TEXT */
          g_type_add_interface_static (type, ATK_TYPE_TEXT,
                                       &atk_text_info);
       }
       return type;
    }

##### 类/实例初始化

不管是 GObject 还是你自己的 AtkObject 实现，都得进行类初始化：

1. Redefines any function calls defined by the object's parent. This is typically necessary when an object needs to implement a function like `atk_object_get_n_accessible_children()`. This is necessary if the object has children, but they are not represented with widgets.

   For example, if your ATK implementation needs to over-ride the AtkObject function `get_name()`, then the class initializer would look like:

   ###### 类初始化将覆写父类的 `get_name()` 函数

       myatkimp_mytype_class_init (GailLabelClass *klass)
       {
         AtkObjectClass *class = ATK_OBJECT_CLASS (klass);
         class->get_name = myatkimp_mytype_get_name;
       }

2. Requires a `parent->init`, `parent->notify_gtk`, or `parent->finalize` function. This example defines all three:

   ###### Class initializer that defines its own `init()`, `notify_gtk()` and `finalize()` functions

       static ParentObjectType *parent_class = NULL;

       myatkimp_mytype_class_init (GailLabelClass *klass)
       {
          ParentObjectType *parent_class = (ParentObjectType*)klass;

          /*
           * Caching the parent_class is necessary if the init,
           * notify_gtk, or finalize functions are set up.
           */
           parent_class = g_type_class_ref (MYATKIMP_TYPE_PARENT);

           parent_class->init = myatkimp_mytype_widget_init;
           parent_class->notify_gtk = myatkimp_mytype_real_notify_gtk;
           parent_class->finalize = myatkimp_mytype_finalize;
       }

   1. parent->init

      A `parent->init()` function may be necessary if the ATK implementation needs to do either of the following:

      1. Cache any data obtained from a backing GTK widget.

      2. Listen to any signals from the backing GTK widget.

      Here is an example of both:

      ###### 自定义 `init()` 函数

          void
          gail_tree_view_widget_init (MyatkimpMytype  *mytype,
                                      GtkWidget       *gtk_widget)
          {
             /* Make sure to call the parent's init function */
             parent_class->init (widget, gtk_widget);

             /* Cache a value in the ATK implementation */
             mytype->cached_value = gtk_widget_function_call();

             /* Listen to a signal */
             gtk_signal_connect (GTK_OBJECT (gtk_widget),
                                 "signal-type",
                                 GTK_SIGNAL_FUNC (_myatkimp_mytype_signal_type),
                                 NULL);
          }

      In this example, if the specified signal-type signal were generated on the backing `gtk_widget`, then the `_myatkimp_mytype_signal_type()` function would be called.

   2. parent->notify_gtk

      If the ATK implementation needs to listen to any property notifications on the backing GTK object, a `parent->notify_gtk()` function may be necessary. For example:

      ###### 自定义 `notify_gtk()` 函数

          void
          myatkimp_mytype_real_notify_gtk (GObject    *obj,
                                           GParamSpec *pspec)
          {
             GtkWidget *widget = GTK_WIDGET (obj);
             AtkObject* atk_obj = gtk_widget_get_accessible (widget);

             if (strcmp (pspec->name, "property-of-interest") == 0)
             {
                /* Handle the property change. */
             }
             else
             {
                parent_class->notify_gtk (obj, pspec);
             }
          }

   3. parent->finalize

      If it is necessary to free any data when a GObject instance is destroyed, then a `finalize()` function is needed to free the memory. For example:

      ###### 自定义 `finalize()` 函数

          void
          myatkimp_mytype_finalize (GObject *object)
          {
             MyAtkimpMyType *my_type = MYATKIMP_MYTYPE (object);

             g_object_unref (my_type->cached_value);
             G_OBJECT_CLASS (parent_class)->finalize (object);
          }

### 让自定义组件获得辅助功能

Adding ATK support to your custom widget will assure its cooperation with the accessibility infrastructure. These are the general steps that are required:

- assess a custom widget according to the applicable User Interface Guidelines;

- determine which ATK interfaces a custom widget should implement, according to the widget's feature set and function;

- 访问 ATK interfaces 可以继承父部件类；

- 部件类的 ATK 接口可以两种方式实现：

  - 直接由自定义部件，或者

  - in an AtkObject subtype created by a new AtkObjectFactory subclass

  如果使用第二种方法，则在运行时必须使用 AtkObjectFactoryRegistry 来注册合适的 factory 类型。

GAIL source code 提供了一个优秀的教程讲解高级 ATK 用法。

### 获取辅助功能支持的用户界面指南

When designing your application's GUI, there are a number of simple guidelines you should follow to ensure that it can be used by as wide an audience as possible, whether in conjunction with assistive technologies or not. Don't be fooled into thinking that this is just a case of "making your GUI usable by people with disabilities", though, and that you shouldn't bother if you know a disabled person is never going to use your application. Following these guidelines will improve the overall usability of your application for everyone who uses it - including you!

#### 综述

We all get frustrated if we can't find a feature in an application, or make a mistake from which it takes a couple of minutes to recover, if it's possible to recover at all. If you have some sort of disability, the chances are the effort and time penalties involved will be several times worse. Following a few basic guidelines can help prevent these sorts of situations for all users.

- Provide Undo for every action that changes the user's data or the application's settings. If possible, provide more than one level of undo and redo, and a history list to allow preview of what actions will be undone.

- Provide commands to restore default settings. If a particular setting could make the application completely unusable for an individual, e.g. by making the fonts very small, it would be useful to provide an option to restore the default settings outside the application itself. This could be done using a command line switch, for example.

- Help prevent users from doing the wrong thing. This is particularly important for actions that could be done by accident (e.g. mouse actions) or that cannot easily be undone (e.g. overwriting a file). Consider using confirmation dialogs or forcing the user to go into a particular mode to perform potentially destructive actions.

- Minimize users' memory load. For example, let the user view multiple documents at the same time, and ensure online help or other instructions can remain visible while they carry out the procedure being described. Allow them to copy any information that is displayed, and paste it anywhere that data can be entered.

- Don't make users insert disks. Depending on a user's particular disability, they may find it difficult to physically insert or change a disk, or they may find it hard to identify the correct disk in the first place. If your application is installed from CD-ROM, provide an option to copy all the files that will be required onto the user's hard drive.

- Don't place frequently used functions deep in a menu structure. Whether you're using a mouse, keyboard or some other input device, deeply-nested menu items are best avoided. As well as the burden of remembering where to find them, they are always more difficult and time-consuming to access.

- Don't lead users through unnecessary steps. For example, wizards are useful for users who have trouble handling large numbers of options at one time, but other users may need to minimize the amount of time or keystrokes they use. Such users benefit from being able to skip unnecessary steps or go directly to the one they need. Consider providing a Finish button in wizards that skips right to the end and assumes default responses for the intermediate steps. If the process has many steps, consider asking the user at the start if they want to run through all the steps, or just the most commonly-used ones.

#### 键盘导航

A well-designed keyboard user interface plays a key role when you are designing accessible software. Blind users can navigate software more effectively using the keyboard, because using the mouse depends on visual feedback of the mouse pointer location. Also, mobility impairments can prevent a user from successfully navigating using the mouse, because of the fine motor control skills required.

It is therefore important to make all mouse actions available from the keyboard, and include keyboard access to all toolbars, menus, links and buttons. Every function your application provides should be available using the keyboard alone. Hide your mouse while you're testing your application if you have to!

Most functionality should be easy to make accessible by using keyboard mnemonics and accelerators, and the toolkit's built-in navigation features. However, operations that rely on drag-and-drop, for example, may require more thought.

- Provide efficient keyboard access to all application features. Some users may be unable to use a mouse, and many "power-users" prefer to use the keyboard anyway. Also, some specialized assistive technology input devices may simulate keyboard events rather than mouse events. Since typing is difficult or even painful for some users, it is important to provide a keyboard interface that minimizes the number of keystrokes required for any given task.

- Use a logical keyboard navigation order. When navigating around a window with the Tab key, keyboard focus should move between controls in a predictable order. In Western locales, this is normally left to right and top to bottom.

- Ensure correct tab order for controls whose enabled state is dependent on checkbox, radio button or toggle button state. When such a button is selected, all its dependent controls should be enabled, and all the dependent controls of any other button in the group should be disabled. When the user selects a checkbox, radio button or toggle button that has dependent controls, do not automatically give focus to the first dependent control, but instead leave the focus on the button.

- Don't override existing system-level accessibility features. For example, AccessX is an Xserver extension that has been supported since X11R6. The MouseKeys feature of this extension allows mouse movement and button clicks to be simulated using the keypad. Therefore you should not add features to your application that can only be accessed by pressing keys on the keypad, as users relying on the MouseKeys feature will not be able to use them.

- Provide more than one method to perform keyboard tasks where possible. Some users may find some keys and key combinations easier to use than others.

- Provide both keyboard and mouse access to functions where possible. Some users may only be able to use either the mouse or the keyboard, but not both.

- Don't assign awkward reaches to frequently performed keyboard operations. Some people may only be able to use one hand on the keyboard, so shortcuts that can be easily used with one hand are preferable for common operations. In any case, having to frequently perform long or difficult reaches on the keyboard can increase muscle strain for all users, increasing the risk of pain or injury.

- Don't require repetitive use of simultaneous keypresses. Some users are only able to press and hold one key at a time. Assistive technologies such as AccessX may allow users to press the keys sequentially rather than simultaneously, but this of course means the operation will take longer for them.

- Ensure that any text that can be selected with the mouse can also be selected with the keyboard. This is a convenience for all users, but especially for those for whom fine control of the mouse is difficult.

- Ensure that objects that can be resized or moved by drag and drop can also be resized or moved with the keyboard. For example, icons and windows on the desktop. Where precision sizing and placement is potentially important, e.g. shapes in a diagram, also consider providing a dialog into which you can type co-ordinates, or a means of snapping objects to a user-definable grid.

- Don't use general navigation functions to trigger operations. For example, do not use basic Tab keyboard navigation in a dialog to activate any actions associated with a control.

- Show keyboard-invoked menus, windows and tooltips near the object they relate to. In GNOME 2.0, users can call up popup menus with Shift F10, and tooltips with Shift F1. Do not completely hide or obscure the object to which the menu or tooltip refers, however.

#### 鼠标交互

记住，不是所有人都能灵巧使用鼠标，某些用户可能很难看见或跟随鼠标指针。

- Don't depend on input from mouse button 2 or button 3. As well as being physically more difficult to click, some pointing devices and many assistive technology devices only support button 1. Some assistive technologies may not emulate the mouse at all, but generate keyboard events instead.

- Allow all mouse operations to be cancelled. Pressing the Esc key should cancel any mouse operation in progress, such as dragging and dropping a file in a file manager, or drawing a shape in a drawing program.

- Provide visual feedback throughout a drag and drop operation. As the mouse passes over valid targets, highlight them and change the mouse pointer. Use the "no drop" mouse pointer when passing over invalid drop targets. See Mouse Interaction Examples.

- Don't warp the mouse pointer, or restrict mouse movement to part of the screen. This can interfere with assistive technologies, and is usually confusing even for users who don't rely on ATs.

- Don't make mouse targets too small. In general, mouse targets should be at least the size of the "hot area" around the resizable window border in the current window manager/theme - bearing in mind that a user with impaired dexterity or vision may be using a window manager with larger areas than the default.

##### 鼠标交互示例

###### 来自 CDE/Motif 的指针 "no-drop" 示例

Example of an "invalid drop target" pointer shape

#### 图形元素

Provide options to customize the presentation of all the important graphical elements in your application. This will make it easier for people with visual or cognitive impairments to use.

- Don't hard-code graphic attributes such as line, border or shadow thickness. These elements should ideally be read from the GTK or window manager theme. If this is not possible, provide options within your application to change them.

- Provide descriptive names for all interface components. The GAIL library provides default accessible descriptions for many GTK widgets, but you will still need to add your own in some cases, such as for widgets that use graphics instead of text (e.g. a well in a color palette, or an icon without a label). Consider overriding the defaults with more helpful or application-specific descriptions where possible.

- Allow multi-color graphical elements (e.g. toolbar icons) to be shown in monochrome only, if possible. These monochrome images should be shown in the system foreground and background colors, which the user will have chosen for themselves (by their choice of GTK theme) for maximum legibility.

- Make interactive GUI elements easily identifiable. For example, do not make the user hover the mouse over an object to determine whether it is clickable or not. Leave sufficient space between objects and clearly delineate object boundaries. Don't show GUI elements that look pretty but don't actually do anything, unless you also provide an option to switch them off.

- Provide an option to hide graphics that don't convey essential information. Graphical images can be distracting to users with some cognitive disorders. The icons on the GNOME foot menu, for example, can be switched off whilst still leaving the menus fully functional.

#### 字体与文本

Even to a user with normal vision, textual output provides the majority of the information and feedback in most applications. It is therefore critical to choose and position text carefully on the screen, and leave the choice of font and size to the user, to ensure that people with vision impairments can also use your application effectively.

- Don't hard-code font styles and sizes. The user should be able to adjust all sizes and typefaces. If for some reason you cannot make this functionality available, never hardcode any font sizes smaller than 10 points.

- Provide options to turn off any graphical backdrops or "watermarks" behind text. Such images interfere with the contrast between the text and its background, which can cause difficulty for users with visual impairments.

- Label objects with names that make sense when taken out of context. Users relying on screen readers or similar assistive technologies will not necessarily be able to immediately understand the relationship between a control and those surrounding it.

- Don't use the same label more than once in the same window. If you use the same label in different windows, it will help if it means the same thing in both windows. Also, don't use labels that are spelled differently but sound the same, e.g. "Read" and "Red", as this could be confusing for users relying on screen-readers.

- Position labels consistently throughout your application. This normally means immediately below large icons, immediately to the right of small icons, and immediately above or to the left of other controls. See Fonts and Text Examples.

- When you use static text to label a control, end the label with a colon. For example, Username: to label a text field into which the user should type their username. This helps identify it as a control's label rather than an independent item of text.

- When you use static text to label a control, ensure that the label immediately precedes that control in the Tab order. This will ensure that the mnemonic (underlined character) you assign to the label will move focus to or activate the correct control when pressed.

- Provide alternatives to WYSIWYG. Some users may need to print text in a small font but edit in a larger screen font, for example. Possible alternatives include displaying all text in the same font and size (both of which are chosen by the user); a "wrap-to-window" option that allows you to read all the text in a window without scrolling horizontally; a single column view that shows the window's contents in a single column even if they will be printed in multiple columns; and a text-only view, where graphics are shown as placeholders or text descriptions. If the application has panels with child controls, consider allowing the panels to resize along with the parent window.

##### 字体与文本示例

###### 各种 GUI 元素的正确标签布局

List control with label above List control with label above | Large file manager icon with label underneath Large file manager icon with label underneath | Small toolbar icon with label to its right Small toolbar icon with label to its right | Spinbox control with label to its left Spinbox control with label to its left

#### 颜色与对比度

Poor choice of colors on the screen can cause problems for users with color blindness (for whom hue is important) or low-vision (for whom brightness/contrast is important). Generally, you should allow the user to customize the colors in any part of your application that conveys important information.

Users with visual impairments may require a high level of contrast between the background and text colors. Often a black background and white text is used to prevent the background from "bleeding" over. These settings are critical for users with visual impairments.

- Don't hard-code application colors. Some users need to use particular combinations of colors and levels of contrast to be able to read the screen comfortably. Therefore all the main colors you use in your GNOME application should be taken from the GTK theme, so the user can set the colors for all their applications to something legible just by changing the theme. If for some reason you do need to use colors that are not available in the theme, ensure they are customizable within the application itself.

- Don't use color as the only means to distinguish items of information. All such information should be provided by at least one other method, such as shape, position or textual description. See Color and Contrast Examples.

- Support all the high contrast GNOME themes. Ensure that when one of these themes is selected, all the text in your application appears in the high contrast foreground and background colors specified by the theme.

- Ensure your application is not dependent on a particular high-contrast theme. Test it with different high-contrast themes to ensure your application respects the settings.

##### 颜色与对比度示例

###### 过度使用颜色的图例

Example showing changes in stock price using color only | This display could cause problems for a red-green color-blind user (color-blindness affects as many as 1 in 7 males in some parts of the world). The lack of contrast between the red text and black background would also make it hard to read for a user with low vision, even with a screen magnifier.

Example showing changes in stock price using both color and arrows

This display reinforces the color-coding with arrows to show the stock price movement, and uses darker shades of green and red on a lighter background to provide higher contrast. This needn't be the default color scheme if testing were to show it to be too distracting for the majority of users, but it should be possible to customize it in this way either by theming or via the application's Preferences dialog.

#### 放大镜

Many users, even those not visually impaired, benefit from magnification of text and graphics. However, without magnification, a visually impaired user may not be able to access and use the program at all.

- 让用户能放大工作区。

- Provide options in the application to scale the work area. Users need to have an option to magnify the work area 150% to 400% or more. Test the application to confirm the object you are viewing is not affected by changing the magnification settings.

#### 音频

People who have difficulty hearing, as well as those who work with the sound on their computers turned off, will be disadvantaged if your application relies on sound to convey information. In general, make sure that the user is able to have any audible information conveyed in other ways.

- Don't assume that a user will hear audio information. This applies as much to users with broken soundcards as it does to those with hearing impairments!

- Don't use audio as the only means of conveying information. Give the user the option to have all audio information provided in a visual way as well. This includes providing closed captioning or transcripts for any important spoken sound clips.

- Allow users to configure frequency and volume of all warning beeps and other sounds. This includes being able to turn off sound altogether.

#### 动画

Used sparingly, animation can be useful for drawing attention to important information in your application - and it can look cool, too. However, it can be problematic for some users, so make sure they can turn it off.

- Don't use flashing or blinking elements having a frequency greater than 2 Hz and lower than 55 Hz. This includes text as well as any graphical objects. Anything in this frequency range may cause particular problems for users susceptible to visually-induced seizures. Note that there is no "safe" frequency, though. If flashing is essential, you should use the system's cursor blink frequency (which should itself be customizable), or allow users to configure the frequency themselves.

- Don't flash or blink large areas of the screen. Small areas are less likely to trigger seizures in those susceptible to them.

- Make all animations optional. The animated information should be available in at least one non-animated format, at the user's request.

#### 键盘焦点

Showing the keyboard focus position clearly at all times is important, both for users with vision impairments as well as "power-users" who prefer to use the keyboard rather than the mouse. There should never be any confusion as to which control on the desktop has focus at any given time. You ought to be able to leave your computer with the focus on any widget in your application, then go off and phone your girlfriend or walk the dog until you've forgotten which widget you left it on. When you return, you should be able to tell straight away exactly which widget it was.

A visual focus indicator is an audio representation of the cursor position relative to the other objects on the desktop. This allows the user to move among objects interactively as the focus changes. The visual focus must be programmatically exposed to assistive technologies. Note that in most cases, this is handled automatically by the ATK, without requiring you to do any additional work. However, you will need to be aware of this requirement when writing your own custom widgets, for example.

- Start focus at the most commonly used control. If no control in a window is deemed to be the "most" useful, start the focus at the first control in the window when that window is opened. Focus should not be started on the OK or Cancel buttons of a dialog even if they are the most commonly used controls, as they can always be activated immediately by pressing Enter or Escape.

- Show current input focus clearly at all times. Remember that in controls that include a scrolling element, it is not always sufficient to highlight just the selected element inside that scrolling area, as it may not be visible. See Keyboard Focus Examples.

- Show input focus only in the active window. Hide all primary visual focus indicators in all windows that do not have the focus and activation. If a single window has separate panes, only one pane should have the focus indicator, and focus indicators should be hidden in all other panes. If it's important to continue showing which item in an unfocused list is selected, for example, use a secondary focus indicator. See Keyboard Focus Examples.

- Provide appropriate feedback when the user attempts to navigate past the end of a group of related objects. When navigating a list, for example, stopping with audio feedback is usually preferable to moving the focus back to the first object in the list. Otherwise, users who are blind or have low vision may not realize they have returned to the beginning. In the case of a text search in a document, a dialog may pop up to indicate that the end of the document has been reached, and ask if you want to resume the search at the start of the document.

- Play the system default audio or visual warning signal when the user presses an inappropriate key, or when a navigation key fails to move the focus. For example, when the focus is on the first character in a text field and the user presses left arrow key, or the user tries to perform multiple selection in a single selection dialog. (Note that users with hearing difficulties should be able to configure a system-wide visual equivalent to the default warning sound.)

##### 键盘焦点示例

###### Example illustrating need to show focus clearly

无法看见该窗口的焦点项，因为它已被滚动离屏 | 该窗口某个控件获得焦点，但不知道是谁...
滚动列表让焦点项出现在视野中 | ...直到滚动列表，让当前被选的焦点项露出来。
无论当前被选项是否可见，该 list 控件始终拥有一个实边框指示焦点 | If the list control itself is given a "focused" border, it's easy to tell it has focus even when the currently-selected item isn't visible.

###### Example illustrating use of secondary focus

Split-paned window in which both panes seem to have focus | In this example, it's impossible to tell just by looking which of the two panes actually has keyboard focus.
Split-pane window in which secondary highlighting is used to show which pane has focus | By using a secondary selection highlight color in the inactive pane, it's immediately obvious that the tree control has focus here...
Split-pane window in which secondary highlighting is used to show which pane has focus | ...and that the list control has focus here.

#### 计时器

Interfaces in which things appear, disappear or happen according to some hard-coded time limit are often a hindrance to accessibility. Some users may read, type or react very slowly in comparison to others. If information they require is hidden before they are finished with it, or obscured by other information popping up which they didn't explicitly request, then your application will become very frustrating or even impossible to use.

- Don't hard-code timeouts or other time-based features. Examples include automatic scrolling when dragging an object towards the edge of a window, holding down a scrollbar button, or automatically expanding a tree node when an object is dragged over it and held for a short time. These should either be customizable in the application, the GNOME control center, or at worst, manually editable from the command line via a configuration file or GConf entry.

- Don't briefly show or hide information based on the movement of the mouse pointer. (Exception: system-provided features such as tooltips, which the user can configure on a system-wide level). If you must provide such features, make them optional so users can turn them off when a screen-review utility is installed.

#### 文档

People with disabilities cannot use the application effectively if they do not have access to the required manuals and help files. Of particular importance is keyboard navigation, since this is the only way many users can navigate the application.

- Provide all documentation in an accessible format. ASCII text and HTML are both excellent formats for assistive technologies.

- Provide alternative text descriptions for all graphics in the documentation.

- Document all your application's accessibility features. Keyboard navigation and shortcuts are particularly important to document. Include an accessibility section in your documentation, where information on all the accessibility features can be found.

## 测试

There are several points of review to conduct before declaring an application accessible. Over the course of development you may want to consider automated testing techniques. LDTP, for example, may complement your automated testing plan.

This section describes a number of tests you can perform manually on an application to test its accessibility. Passing all the tests does not necessarily imply that the application is fully accessible, but if the application fails any of these tests, then further work may need to be done to improve that aspect of its accessibility.

### 键盘导航

The following keyboard operations should be tested. Do not use the mouse in any part of this test.

- Using only keyboard commands, move the focus through all menu bars in the application.

- 确认：

  - 上下文敏感的菜单显示正确。

  - 工具栏上列出的任何功能均能使用键盘执行。

  - 你可以在应用程序和对话框中的客户区操作每一个控件。

  - 文本和客户区内的对象可被选取。

  - Any keyboard enhancements or shortcuts are working as designed.

### 图形元素

测试并验证使用屏幕阅读器的应用程序：

- 标签与文本被正确读入，包括菜单与工具栏。

- 对象信息可正确读取。

### 视觉焦点指示器

- Verify that when moving among objects that the visual focus indicator is easy to identify.

- Keyboard navigation through the software and menus should be clearly visible when the focus moves.

- Confirm that the screen reader is tracking the visual focus indicator as you navigate using a keyboard.

- Run a screen magnification program (if available) and verify that the magnifier can track the visual focus indicator as you navigate using the keyboard and mouse.

### 字体与文本

- Change the font in the application and confirm that the settings are maintained.

- Test the application by changing colors and confirm that all settings are maintained.

- If magnification is available, test the font, color, and size using the magnification option.

### 颜色与对比度

- Print screenshots to a black and white printer and confirm that all information is visible.

- Test applications using only black and white, high-contrast settings and confirm that all information is conveyed correctly.

- Test that the application provides at least three combinations of color schemes and that high-contrast schemes are available (e.g. white on black or yellow on blue).

- Turn on high-contrast settings in the GNOME Control Center and confirm that the application respects these settings.

- Test various themes to ensure that the software is working for all the available settings.

### 音频

There should be an option in the application to show audio alerts visually.

Test that the audio is working correctly by enabling sound in the GNOME Control Center and then perform the following actions:

- Perform an action that should generate an audio alert and confirm that the application is working as designed.

- Verify that the application works correctly when increasing or decreasing the volume.

- Confirm that warning messages and alerts can be heard correctly in a noisy work environment.

### 动画

Verify that an option is available to stop animation and that it is working as designed.

Turn the animation off. Confirm that all information is still conveyed correctly.

### 键盘焦点

- Test all messages to confirm that the user is notified before a message times out and is given the option to indicate that more time is needed.

- Make sure an option has been included to adjust the response time and confirm that it is working as designed.

### 文档

Test ASCII text documentation with a screen reader to confirm that it is clear and precise and can be read by assistive technologies.

Test HTML applications using a web browser and screen reader to confirm that the documentation is accessible to assistive technologies.

Note: There are web accessibility guidelines available at http://www.w3.org/TR/WAI-WEBCONTENT/.

Confirm the following information is included in the documentation:

- State if the application does not support the standard keyboard access used by the OS.

- Identify if there are unique keyboard commands.

- Identify any unique accessibility features.

- If an action is documented for the mouse, make sure there is an alternative for using the keyboard.

### 用户界面检查清单

This section summarizes the guidelines given in User Interface Guidelines for Supporting Accessibility. You should refer to that section of the guide for more detailed information on any of the checklist items given here.

When testing an application for accessibility, you should go through each of the items in the list. Note whether the application passes or fails each test, or does not apply to that application.

#### 通用原则列表

GP | 通用原则 | 通过/失败/NA
--- | --- | ---
GP.1 | 每一个改变用户数据或程序设置的操作均可被撤消。
GP.2 | 所有应用程序设置均可被恢复默认值，而不需要用户记住默认值是什么。
GP.3 | 安装完成后，应用程序随时都可运行而不需用户插入磁盘/CD。
GP.4 | 最频繁的操作要放在菜单结构的最顶层。

#### 键盘导航检查清单

KN | 键盘导航 | 通过/失败/NA
--- | --- | ---
KN.1 | 为所有应用程序特性提供高效地键盘访问。
KN.2 | 所有窗口拥有一个逻辑键盘导航顺序。
KN.3 | The correct tab order is used for controls whose enabled state is dependent on checkboxes, radio buttons or toggle buttons.
KN.4 | 键盘访问的应用程序指定函数不能覆盖已存在的系统辅助功能特性。
KN.5 | 应用程序应尽可能提供一种以上的方法来执行键盘执行的任务。
KN.6 | 尽可能拥有可选组合键。
KN.7 | 频繁执行的键盘操作用起来应该顺手(译注：考虑键位)。
KN.8 | 应用程序不应使用重复、同时的按键。
KN.9 | 应用程序应赋予键盘所有的鼠标功能。
KN.10 | 任何文本或对象，可分别用鼠标或键盘选中。
KN.11 | 任何可调整大小或移动的对象可分别用鼠标或键盘单独控制。
KN.12 | 应用程序不应使用任何通用导航功能来触发操作。
KN.13 | 所有键盘绑定的菜单、窗口和提示信息均要出现在与之相关联的对象旁边。

#### 鼠标交互检查清单

MI | 鼠标交互 | 通过/失败/NA
--- | --- | ---
MI.1 | 避免依靠来自鼠标 右键 或 中键 输入的操作。
MI.2 | 所有的鼠标操作在确定之前均可被取消。
MI.3 | 为拖放操作提供视觉反馈
MI.4 | 鼠标指针不能在程序控制下反常，或者它的移动不因程序而受限于屏幕某个区域。

#### 图形元素检查清单

GE | 图形元素 | 通过/失败/NA
--- | --- | ---
GE.1 | 避免对图形属性，比如线、边框或阴影度进行硬编码。
GE.2 | 尽可能让多色图形元素也能显示在单色环境下。
GE.3 | 能非常容易区分可交互 GUI 元素与静态 GUI 元素。
GE.4 | 提供一个隐藏非必需图形的选项。

#### 字体与文本检查清单

FT | 字体与文本 | 通过/失败/NA
--- | --- | ---
FT.1 | 避免字体风格或大小是硬编码的。
FT.2 | 提供一个关闭文本图形背景的选项。
FT.3 | 所有标签的名字在失去上下文后仍有意义。
FT.4 | 同一个窗口不应重复使用同一个标签名。
FT.5 | 标签的位置在整个程序中应始终如一。
FT.6 | All static text labels that identify other controls end in a colon (:).
FT.7 | Static text labels that identify other controls immediately precede those controls in the tab order.
FT.8 | An alternative to WYSIWYG is provided. For example, the ability to specify different screen and printer fonts in a text editor.

#### 颜色与对比度检查清单

CC | 颜色与对比度 | 通过/失败/NA
--- | --- | ---
CC.1 | 应用程序的颜色避免硬编码，而应根据当前桌面主题或程序设置来确定并绘制。
CC.2 | 颜色仅用于增强说明，而不能用于传达信息或活动。
CC.3 | 应用程序应支持所有可用的高对比度主题和设置。
CC.4 | 软件不应依赖任何特殊的高对比度主题或设置。

#### 放大功能检查清单

MG | 放大镜 | 通过/失败/NA
--- | --- | ---
MG.1 | 应用程序应提供放大工作区域的能力。
MG.2 | 应用程序应提供缩放工作区域的选项。
MG.3 | 应用程序的功能不受放大或缩小改变的影响。

#### 音频检查清单

AU | 音频 | 通过/失败/NA
--- | --- | ---
AU.1 | 声音不能是传达任何物体信息的唯一方法。
AU.2 | 用户可以配置所有声音和警告音的频率与音量。

#### 动画检查清单

AN | 动画 | 通过/失败/NA
--- | --- | ---
AN.1 | 避免使用频率范围在 2Hz—55Hz 间的闪烁元素。
AN.2 | 任何闪烁应限制在屏幕的某个小区域里。
AN.3 | 如果动画已被启用，至少应提供一个可以在它第一次展示前关闭的选项。

#### 键盘焦点检查清单

KF | 键盘焦点 | 通过/失败/NA
--- | --- | ---
KF.1 | 当窗口打开后，焦点应位于最常用的控件上。
KF.2 | 当前输入焦点位置总是清晰可见的。
KF.3 | 输入焦点总是明确显示在某个窗口上。
KF.4 | Appropriate audio or visual feedback is provided when the user attempts to navigate past either end of a group of related objects.
KF.5 | The default audio or visual warning signal is played when the user presses an inappropriate key.
KF.6 | There is sufficient audio information for the visual focus that the user can figure out what to do next.
KF.7 | When using assistive technologies, such as a screen reader or braille device, the current program indicates the position and content of the visual focus indicator.

#### Timing checklist

TM | 计时器 | 通过/失败/NA
--- | --- | ---
TM.1 | There are no hard-coded time-outs or time-based features in the application.
TM.2 | The display or hiding of important information is not triggered solely by movement of the mouse pointer.

#### Documentation checklist

DC | 文档 | 通过/失败/NA
--- | --- | ---
DC.1 | All documentation is in an accessible format, with textual alternate descriptions provided for all figures and diagrams.
DC.2 | The documentation includes a section that covers all the application's accessibility features.

### GOK (GNOME Onscreen Keyboard)

The information on this page is partially outdated: GNOME 3's Caribou has effectively replaced GNOME 2's gok.

Your application should be usable via gok; key input should be generated entirely by gok, not the keyboard. The aim here would be to work with your application and the desktop in general, ensuring any type of character input can be performed with the on-screen keyboard.

The gok application ships with the GNOME Desktop so should already be present. For full documentation, refer to the official gok site.

Follow these steps to verify the correct operation of gok with your application:

1. Login into the GNOME desktop

2. Run gok

3. 启动你的应用程序

4. Provide input to your application with a pointing device (e.g., mouse or head-tracker) and gok.

5. Work using the auto-completion and word prediction features of gok.

6. Verify that gok enables and disables the Menus and Toolbars buttons based on the kind of application invoked; for example, the Menus and Toolbars buttons are disabled for the 'Font properties' capplet, but the same buttons are enabled for the Gedit application.

7. Verify that the gok on-screen keyboard provided by the Compose button can be used to type in any text for the selected application; run Gedit, click on the text area, and then click on the Compose button in gok. Select the required keys from the on-screen keyboard. The characters should appear in the Gedit text area.

8. Verify that the Launcher button allows the user to launch any of the Terminal, Web Browser or Text Editor applications.

9. Verify that the Activate button allows the user to activate any of the currently running application windows on the user's desktop, including GNOME panels and the GNOME desktop.

10. Verify that the Menus button lists all the available menus in the current application. Verify that clicking on a menu button displays the sub-menu and menu items contained within the sub-menu. Finally, verify that clicking on a menu item activates the menu item. For example, click on the Help Browser application and click on the Menus button. The GOK window now displays the File, Go and Help buttons (the Help Browser menus). Click on the File button and it displays the New Window and Close Window buttons (menu items).

11. Verify that the Toolbars button lists all the available buttons in the application toolbar. For example, click on the Help Browser application and then click on the Toolbars button. The GOK window now displays the Back, Forward and Home buttons.

12. Verify that the UI Grab button displays all the button objects for the selected application window. For example, open the 'Font Properties' capplet and click on the UI Grab button in the GOK window. The GOK window should now display the names of the buttons in the capplet - Sans, Sans-serif, Close and Help.

### Accerciser

Accerciser and the GNOME Accessibility Architecture

Accerciser is an interactive Python accessibility explorer for the GNOME Desktop. It uses AT-SPI to inspect and control widgets, allowing you to check if an application is providing correct information to assistive technologies and automated test frameworks. Accerciser has a simple plugin framework which you can use to create custom views of accessibility information. Full documentation can be found in the Official Accerciser Manual. For a demonstration of Accerciser and PyATSPI (Python-wrappered access and usage of AT-SPI), see this article. For an excellent walkthrough from the author, see the article titled Make Your Application Accessible with Accerciser.

Accerciser 事实上已经取代了 at-poke 工具。