Blame accessibility-devel-guide/sl/index.docbook

Packit 1470ea
Packit 1470ea
Packit 1470ea
Packit 1470ea
Packit 1470ea
Packit 1470ea
Packit 1470ea
Packit 1470ea
Packit 1470ea
]>
Packit 1470ea
Packit 1470ea
<book id="index" lang="sl">
Packit 1470ea
<title>GNOME Accessibility Developers Guide</title>
Packit 1470ea
<bookinfo>
Packit 1470ea
<abstract role="description">
Packit 1470ea
<para>
Packit 1470ea
The GNOME Accessibility Guide is for developers who want to ensure their programming efforts are accessible to the widest audience of users. This guide also covers many of the Section 508 requirements.
Packit 1470ea
</para>
Packit 1470ea
</abstract>
Packit 1470ea
<copyright> 
Packit 1470ea
<year>2008</year>
Packit 1470ea
<holder>Vincent Alexander</holder>
Packit 1470ea
</copyright>
Packit 1470ea
<copyright> 
Packit 1470ea
<year>2001, 2002</year>
Packit 1470ea
<holder>Calum Benson, Brian Cameron, Bill Haneman, Padraig O'Briain, Sharon Snider</holder>
Packit 1470ea
</copyright>
Packit 1470ea
<publisher role="maintainer"> 
Packit 1470ea
<publishername>
Packit 1470ea
GNOME Documentation Project
Packit 1470ea
</publishername> 
Packit 1470ea
</publisher>
Packit 1470ea
<legalnotice id="legalnotice">
Packit 1470ea
<para>
Packit 1470ea
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (GFDL), Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL 
Packit 1470ea
<ulink type="help" url="ghelp:fdl"> here</ulink> or in the file COPYING-DOCS distributed with this manual.
Packit 1470ea
</para>
Packit 1470ea
<para> 
Packit 1470ea
This manual is part of a collection of GNOME manuals distributed under the GFDL. If you want to distribute this manual separately from the collection, you can do so by adding a copy of the license to the manual, as 
Packit 1470ea
described in Section 6 of the license.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and the members of the GNOME Documentation Project are made aware of those trademarks, then the names are in capital letters or initial capital letters.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER UNDERSTANDING THAT:
Packit 1470ea
<orderedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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 
Packit 1470ea
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
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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 
Packit 1470ea
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, 
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</orderedlist>
Packit 1470ea
</para>
Packit 1470ea
</legalnotice>
Packit 1470ea
 
Packit 1470ea
<authorgroup> 
Packit 1470ea
<author>
Packit 1470ea
<firstname>Vincent</firstname>
Packit 1470ea
<surname>Alexander</surname>
Packit 1470ea
<affiliation>
Packit 1470ea
<orgname>GNOME Documentation Project</orgname>
Packit 1470ea
</affiliation>
Packit 1470ea
</author>
Packit 1470ea
<author>
Packit 1470ea
<firstname>Calum</firstname>
Packit 1470ea
<surname>Benson</surname>
Packit 1470ea
<affiliation>
Packit 1470ea
<orgname>GNOME Documentation Project</orgname>
Packit 1470ea
</affiliation>
Packit 1470ea
</author>
Packit 1470ea
<author>
Packit 1470ea
<firstname>Brian</firstname>
Packit 1470ea
<surname>Cameron</surname>
Packit 1470ea
<affiliation>
Packit 1470ea
<orgname>GNOME Documentation Project</orgname>
Packit 1470ea
</affiliation>
Packit 1470ea
</author>
Packit 1470ea
<author> 
Packit 1470ea
<firstname>Bill</firstname>
Packit 1470ea
<surname>Haneman</surname>
Packit 1470ea
<affiliation>
Packit 1470ea
<orgname>GNOME Documentation Project</orgname>  
Packit 1470ea
</affiliation>
Packit 1470ea
</author>
Packit 1470ea
<author>
Packit 1470ea
<firstname>Padraig</firstname> 
Packit 1470ea
<surname>O'Briain</surname> 
Packit 1470ea
<affiliation> 
Packit 1470ea
<orgname>GNOME Documentation Project</orgname>  
Packit 1470ea
</affiliation> 
Packit 1470ea
</author> 
Packit 1470ea
<author> 
Packit 1470ea
<firstname>Sharon</firstname> 
Packit 1470ea
<surname>Snider</surname> 
Packit 1470ea
<affiliation> 
Packit 1470ea
<orgname>GNOME Documentation Project</orgname>  
Packit 1470ea
</affiliation> 
Packit 1470ea
</author>
Packit 1470ea
</authorgroup>
Packit 1470ea
<revhistory>
Packit 1470ea
<revision> 
Packit 1470ea
<revnumber>
Packit 1470ea
GNOME 2.24
Packit 1470ea
Accessibility Developers Guide V2.24.0
Packit 1470ea
</revnumber> 
Packit 1470ea
<date>September 2008</date> 
Packit 1470ea
<revdescription> 
Packit 1470ea
<para role="author">
Packit 1470ea
GNOME Documentation Project
Packit 1470ea
</para> 
Packit 1470ea
<para role="publisher">
Packit 1470ea
GNOME Documentation Project
Packit 1470ea
</para> 
Packit 1470ea
</revdescription> 
Packit 1470ea
</revision>
Packit 1470ea
<revision> 
Packit 1470ea
<revnumber>
Packit 1470ea
GNOME 2.24 Accessibility Developers Guide V2.24.0
Packit 1470ea
</revnumber> 
Packit 1470ea
<date>September 2008</date> 
Packit 1470ea
<revdescription> 
Packit 1470ea
<para role="author">
Packit 1470ea
GNOME Documentation Project
Packit 1470ea
</para> 
Packit 1470ea
<para role="publisher">
Packit 1470ea
GNOME Documentation Project
Packit 1470ea
</para> 
Packit 1470ea
</revdescription> 
Packit 1470ea
</revision>
Packit 1470ea
</revhistory>
Packit 1470ea
<releaseinfo> 
Packit 1470ea
This manual describes version 2.24 of the GNOME Desktop.
Packit 1470ea
</releaseinfo>
Packit 1470ea
<legalnotice> 
Packit 1470ea
<title>Feedback</title> 
Packit 1470ea
<para> 
Packit 1470ea
To report a bug or make a suggestion regarding the GNOME Desktop or this manual, follow the directions in the <ulink type="help" url="ghelp:user-guide?feedback">GNOME Feedback Page</ulink>.
Packit 1470ea
</para>
Packit 1470ea
</legalnotice> 
Packit 1470ea
</bookinfo>
Packit 1470ea
<chapter id="gad" status="draft">
Packit 1470ea
<title>What is Accessibility?</title>
Packit 1470ea
<para>
Packit 1470ea
Accessibility means helping people with disabilities to participate in substantial life activities. That includes work, and the use of services, products, and information. GNOME includes libraries and a support framework that allow people with disabilities to utilize all of the functionality of the GNOME user environment.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
In conjunction with assistive technologies if necessary - voice interfaces, screen readers, alternate input devices, and so on - people with permanent or temporary disabilities can therefore use the GNOME desktop and applications. Assistive technologies are also useful for people using computers outside their home or office. For example, if you're stuck in traffic, you might use voice input and output to check your email.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Assistive technologies receive information from applications via the Accessibility Toolkit (ATK) API, which you can find in the atk module in the GNOME repositories. Because support for the accessibility API is built into the GNOME widgets, your GNOME program should function reasonably well with assistive technologies with no extra work on your part. For example, assistive technologies can automatically read the widget labels that you would normally set in your program anyway (e.g. with GTK function calls such as <function>gtk_label_set_text()</function> or <function>gtk_button_new_with_label()</function>). They can also find out if there is any tooltip text associated with a widget, and use that to describe the widget to the user.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
With a little extra effort, however, you can make your program function even more smoothly with assistive technologies. Besides helping individual users, this will also make your product more attractive to government and education markets, many of which now require their applications to be accessible by law.
Packit 1470ea
</para>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Types of Disability</title>
Packit 1470ea
<para>
Packit 1470ea
In the US alone, there are an estimated 30,000,000 people whose ability to use computers may be compromised by inaccessible design. Globally, around 8% of the people who use the worldwide web have some sort of disability. Disabilities fall into one of these categories:
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
<emphasis>Visual Impairments</emphasis> - these
Packit 1470ea
can range from low-vision (including dim or hazy vision, extreme far- or near-sightedness, color-blindness, and tunnel vision, amongst others) to complete blindness. Poor choice of text size and color, and tasks that involve good
Packit 1470ea
hand-eye coordination (such as moving the mouse) can cause problems for these users.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
<emphasis>Movement Impairments</emphasis> - users with poor muscle control or weaknesses can find it hard to use a standard keyboard or mouse. For example, they may be unable to hold down two keys simultaneously, or they may be more likely to strike keys accidentally.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
<emphasis>Hearing Impairments</emphasis> - these can range from being able to hear some sounds but not distinguish spoken words, to profound deafness. Applications that convey important information by sound alone will cause problems for these users.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
<emphasis>Cognitive and Language Impairments</emphasis> - these can range from dyslexia to difficulties remembering things, solving problems or comprehending and using spoken or written language. Complex or inconsistent displays, or poor choice of words can make using computers difficult for these users.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
<emphasis>Seizure disorders</emphasis> - certain light or sound patterns can cause epileptic seizures in some susceptible users.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="gad-how-it-works">
Packit 1470ea
<title>How Accessibility Works in GNOME</title>
Packit 1470ea
<para>
Packit 1470ea
The Accessibility Toolkit (ATK) describes a set of interfaces that need to be implemented by GUI components to make them accessible. The interfaces are toolkit-independent - implementations could be written for any widget set, such as GTK, Motif or Qt.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
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
Packit 1470ea
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
Packit 1470ea
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
Packit 1470ea
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 <application>gconf</application> 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.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Most assistive technologies running on other desktops have historically found it necessary to maintain a complex off-screen model of
Packit 1470ea
the desktop applications, based on snooping of OS events, use of unsupported OS and application features and API, and other highly
Packit 1470ea
non-portable techniques. This has made assistive technology support somewhat "brittle" and highly OS- and application-specific, even application-version specific. In contrast, on the GNOME Desktop, all the information required by the ATs is provided by the running applications, via the GNOME Accessibility Framework, to a toolkit-independent Service Provider Interface (SPI). The SPI provides a means for UNIX-based ATs, such as screen readers and screen magnifiers, to obtain accessibility information from running applications via a consistent, stable API, and can eliminate the need for an off-screen model in many cases. Accessibility support for applications is "built in" to application toolkits via toolkit-appropriate APIs (for instance, ATK for most native C applications and the Java Accessibility API for Java apps), and exported to the common "AT-SPI" interface via the relevant "bridge" (see diagram below).
Packit 1470ea
</para>
Packit 1470ea
<figure id="gad-architecture">
Packit 1470ea
<title>GNOME Accessibility Architecture</title>
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/GNOME_desktop_Accessibility.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Diagram of GNOME's accessibility architecture</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</figure>
Packit 1470ea
<para>
Packit 1470ea
GNOME's built-in accessibility support means that applications created using stock GNOME widgets get support for assistive technologies "for free", provided the widgets are not used in unusual ways which conflict with this built-in support.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
A gtk+/GNOME widget is accessible if its use follows the general accessibility guidelines elsewhere in this document, and it implements the ATK interfaces appropriate to its role in the	user interface. ATK implementations are provided for the "stock" GNOME toolkit widgets (i.e. non-deprecated gtk+ and GNOME widgets), and in many cases new widgets which derive
Packit 1470ea
trivially from existing GTK+ or GNOME widgets will also inherit suitable accessibility support.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
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 <link linkend="gad-coding-guidelines">Coding Guidelines for Supporting Accessibility</link> for more information.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
If your application uses custom widgets, you may have to do some work to expose those widgets' properties to assistive technologies. See <link linkend="gad-custom">Making Custom Components Accessible</link> and <link linkend="gad-api-examples">Examples that Use the Accessibility API</link> for more information.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
For additional, in-depth information regarding GTK/GTK+, see the <ulink url="http://library.gnome.org/devel/gtk">GTK+ Reference Manual</ulink>, <ulink url="http://live.gnome.org/GAP/AtkGuide/Gtk">the GTK section of the ATK Guide</ulink>, the GNOME-hosted <ulink url="http://library.gnome.org/devel/gtk-tutorial/stable/">GTK+ 2.0 Tutorial</ulink> and the official <ulink url="http://library.gnome.org/devel/gtk-faq/stable/">GTK+ FAQ</ulink>.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="dev-start">
Packit 1470ea
<title>Developer Quick Start</title>
Packit 1470ea
<para>
Packit 1470ea
Here are some common starting points:
Packit 1470ea
</para>
Packit 1470ea
Packit 1470ea
<section id="dev-start-1">
Packit 1470ea
<title>How do I check to see if my application is accessible or not?</title>
Packit 1470ea
<para>
Packit 1470ea
To start right in, see <link linkend="gad-overview">Making a GNOME Application Accessible - Overview</link>. For a pre-coding perspective, see <link linkend="gad-ui-guidelines">User Interface Guidelines for Supporting Accessibility</link> or <link linkend="gad-coding-guidelines">Coding Guidelines for Supporting Accessibility</link>. For a checklist of post-design test items, see <link linkend="gad-checklist">User Interface Checklist</link>.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="dev-start-2">
Packit 1470ea
<title>What are the common pitfalls?</title>
Packit 1470ea
<para>
Packit 1470ea
The <link linkend="gad-checklist">User Interface Checklist</link> covers all the areas that sometimes get overlooked in the design stage.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="dev-start-3">
Packit 1470ea
<title>How do I do common ATK things?</title>
Packit 1470ea
<para>
Packit 1470ea
An abbreviated listing of common ATK calls can be found <link linkend="gad-api">here</link>.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="dev-start-4">
Packit 1470ea
<title>How do I do more complex ATK things?</title>
Packit 1470ea
<para>
Packit 1470ea
See <link linkend="gad-custom">Making Custom Components Accessible</link> and <link linkend="gad-api-examples">Examples that Use the Accessibility API</link> for more information.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="dev-start-5">
Packit 1470ea
<title>Introducing ATK, AT-SPI, GAIL and GTK+</title>
Packit 1470ea
<screenshot>
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/gaa.jpg"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>
Packit 1470ea
GNOME Accessibility Architecture
Packit 1470ea
</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</screenshot>
Packit 1470ea
<para>
Packit 1470ea
ATK is the toolkit that GNOME uses to enable accessibility for users needing extra support to make the most of their computers. ATK is used by tools such as screen readers, magnifiers, and input devices to permit a rich interaction with the desktop through alternative means. See <ulink url="http://java-gnome.sourceforge.net/4.0/doc/api/org/gnome/atk/package-summary.html">the ATK SourceForge Project</ulink> and <ulink url="http://library.gnome.org/devel/atk/stable/">the ATK Library</ulink> for more information.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
AT-SPI is the primary service interface by which assistive technologies query and receive notifications from running applications. The full API can be explored <ulink url="http://library.gnome.org/devel/at-spi-cspi/stable/">here</ulink>. Additional material is available from <ulink url="http://accessibility.kde.org/developer/atk.php#coreclasses">the KDE Accessibility Development Community</ulink>.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
GAIL (GNOME Accessibility Implementation Library) is an implementation of the accessibility interfaces defined by ATK. GTK is a toolkit which is already mapped to ATK by the GAIL module. License, download and other information can be found <ulink url="http://www.t2-project.org/packages/gail.html">here</ulink>. The <ulink url="ftp://ftp.gnome.org/pub/GNOME/sources/gail/">GAIL source code</ulink> also serves as an excellent tutorial for advanced ATK usage. In addition, you may be interested in the <ulink url="http://library.gnome.org/devel/gail-libgail-util/stable/">GAIL Reference Manual</ulink>.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
GTK+ is a library for creating graphical user interfaces. It works on many UNIX-like platforms, Windows, and on framebuffer devices. GTK+ is released under the GNU Library General Public License (GNU LGPL), which allows for flexible licensing of client applications. GTK+ has a C-based object-oriented architecture that allows for maximum flexibility. Bindings for other languages have been written, including C++, Objective-C, Guile/Scheme, Perl, Python, TOM, Ada95, Free Pascal, and Eiffel.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
For additional, in-depth information regarding GTK/GTK+, see the <ulink url="http://library.gnome.org/devel/gtk">GTK+ Reference Manual</ulink>, <ulink url="http://wiki.gnome.org/Accessibility/Documentation/GNOME2/AtkGuide/Gtk">the GTK section of the ATK Guide</ulink>, the GNOME-hosted <ulink url="http://library.gnome.org/devel/gtk-tutorial/stable/">GTK+ 2.0 Tutorial</ulink> and the official <ulink url="http://library.gnome.org/devel/gtk-faq/stable/">GTK+ FAQ</ulink>.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="gad-overview">
Packit 1470ea
<title>Making a GNOME Application Accessible - Overview</title>
Packit 1470ea
<para>
Packit 1470ea
If your application only uses standard GTK widgets, you will probably have to do little or nothing to make your application (reasonably) accessible. But do watch out for objects in your GUI that don't have a textual description associated with them, such as graphical buttons or status indicators that don't have labels or tooltips.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
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 <link linkend="gad-coding-guidelines">Coding Guidelines for Supporting Accessibility</link> for more information.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
If your application uses custom widgets, you may have to do some work to expose those widgets' properties to assistive technologies.  See <link linkend="gad-custom">Making Custom Components Accessible</link> and <link linkend="gad-api-examples">Examples that Use the Accessibility API</link> for more information. Additional detailed information can be found in Marc Mulcahy's 2002 GUADEC presentation, <ulink url="https://projects.gnome.org/accessibility/talks/GUAD3C/making-apps-accessible/start.html">"Making GNOME Applications Accessible".</ulink>
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="gad-coding-guidelines">
Packit 1470ea
<title>Coding Guidelines for Supporting Accessibility</title>
Packit 1470ea
<para>
Packit 1470ea
Here are some things you can do in your code to make your program work as well as possible with assistive technologies. (You can find a list of things to consider when designing your GUI in the <link linkend="gad-ui-guidelines">User Interface Guidelines for Supporting Accessibility</link> section later in this document):
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
For components that don't display a short string (such as a graphical button), specify a name for it with <function>atk_object_set_name()</function>. You might want to do this for image-only buttons, panels that provide logical groupings, text areas, and so on.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
If you can't provide a tooltip for a component, use <function>atk_object_set_description()</function> instead to provide a description that assistive technologies can give the user. For example, to provide an accessible description for a <guibutton>Close</guibutton> button:
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>Providing an accessible description for a GtkButton</title>
Packit 1470ea
<programlisting>
Packit 1470ea
{
Packit 1470ea
  AtkObject *obj;
Packit 1470ea
  obj = gtk_widget_get_accessible(button);
Packit 1470ea
  atk_object_set_description(obj,_("Closes the window"));
Packit 1470ea
}
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Use <function>atk_image_set_description()</function> to provide a text description for all images and icons in your program.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
If several components form a logical group, try to put them in one container.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Whenever you have a label that describes another component, use <function>atk_relation_set_add_relation()</function> so that assistive technologies can find the component with which the label is associated. (If you associate the label with the component using <function>gtk_label_set_mnemonic_widget()</function>, the <constant>ATK_RELATION_LABEL_FOR</constant> relation is generated automatically, so the following code would not be necessary):
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>Relating a GtkLabel to a GtkWidget</title>
Packit 1470ea
<programlisting>
Packit 1470ea
{
Packit 1470ea
  GtkWidget *widget;
Packit 1470ea
  GtkLabel *label;
Packit 1470ea
Packit 1470ea
  AtkObject *atk_widget, *atk_label;
Packit 1470ea
  AtkRelationSet *relation_set;
Packit 1470ea
  AtkRelation *relation;
Packit 1470ea
  AtkObject *targets[1];
Packit 1470ea
Packit 1470ea
  atk_widget = gtk_widget_get_accessible(widget);
Packit 1470ea
  atk_label = gtk_widget_get_accessible (GTK_WIDGET(label));
Packit 1470ea
Packit 1470ea
  relation_set = atk_object_ref_relation_set (atk_label);
Packit 1470ea
  targets[0] = atk_widget;
Packit 1470ea
Packit 1470ea
  relation = atk_relation_new(targets,1, ATK_RELATION_LABEL_FOR);
Packit 1470ea
  atk_relation_set_add(relation_set,relation);
Packit 1470ea
  g_object_unref(G_OBJECT(relation));
Packit 1470ea
}
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
If you create a custom widget, make sure it supports accessibility. Custom components that are descendants of other GTK widgets should override inherited accessibility information as necessary. For more information, see <link linkend="gad-custom">Making Custom Components Accessible</link>.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Don't break what you get for free! If your GUI has an inaccessible container, any components inside that container may become inaccessible.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="gad-api">
Packit 1470ea
<title>The Accessibility API</title>
Packit 1470ea
<para>
Packit 1470ea
Here are a few of the basic API calls you may need to use in your application to ensure it works well with assistive technologies. The full accessibility API is extensive, to allow you to write your own accessible custom widgets, for example.
Packit 1470ea
</para>
Packit 1470ea
Packit 1470ea
<title>Commonly used ATK API calls</title>
Packit 1470ea
<tgroup cols="2" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>API</entry>
Packit 1470ea
<entry>Opis</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
<function>AtkObject* gtk_widget_get_accessible (GtkWidget*)</function>
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
Returns the accessible object that describes the specified GTK widget to an assistive technology.
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
<function>void atk_object_set_name (AtkObject*, const gchar*)</function>
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
Sets the name of the accessible object. For example, if the object is a graphical button that quits the application when pressed, the name might be "Quit".
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
<function>void atk_object_set_description (AtkObject*, const gchar*)</function>
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
Sets the textual description of the accessible object. For example, if the object is a graphical "Close" button, the description might be "Closes the window".
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
<function>AtkRelation* atk_relation_new (AtkObject**, gint, AtkRelationType)</function>
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
Creates a new relation between the specified key and the specified list of target objects.  A relationship normally indicates to the assistive technology that one widget is somehow related to another. For example, that a particular GtkLabel widget is the caption for a GtkTreeView in the same window.
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
<function>void atk_image_set_description (AtkImage*, const gchar*)</function>
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
<para>
Packit 1470ea
Sets the textual description of the accessible image object. For example, if the object is a thumbnail of a virtual desktop in a panel applet, the description might be "Image showing window arrangement on desktop 1".
Packit 1470ea
</para>
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="gad-api-examples">
Packit 1470ea
<title>Examples that Use the Accessibility API</title>
Packit 1470ea
<para>
Packit 1470ea
As noted earlier, you should have little or no work to do to make your application accessible if you use the GTK widget set, or any other widget library that implements the ATK interfaces. The two most common things you may have to do in this case are:
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
provide descriptions of some controls and images using <function>atk_object_set_description()</function> or <function>atk_image_set_description():</function>
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>Setting the accessible description for a button</title>
Packit 1470ea
<programlisting>
Packit 1470ea
{
Packit 1470ea
   AtkObject *obj;
Packit 1470ea
   obj = gtk_widget_get_accessible(button);
Packit 1470ea
   atk_object_set_description(obj,_("Opens Preferences dialog"));
Packit 1470ea
}
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
<para>
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Specify relationships between any unusual groupings of widgets using <function>atk_relation_new()</function> and <function>atk_relation_set_add()</function>:
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>Specifying accessible relationship between two controls</title>
Packit 1470ea
<programlisting>
Packit 1470ea
{
Packit 1470ea
  GtkWidget *widget;
Packit 1470ea
  GtkLabel *label;
Packit 1470ea
Packit 1470ea
  AtkObject *atk_widget, *atk_label;
Packit 1470ea
  AtkRelationSet *relation_set;
Packit 1470ea
  AtkRelation *relation;
Packit 1470ea
  AtkObject *targets[1];
Packit 1470ea
Packit 1470ea
  atk_widget = gtk_widget_get_accessible (widget);
Packit 1470ea
  atk_label = gtk_widget_get_accessible (GTK_WIDGET(label));
Packit 1470ea
Packit 1470ea
  relation_set = atk_object_ref_relation_set (atk_label);
Packit 1470ea
  targets[0] = atk_widget;
Packit 1470ea
Packit 1470ea
  relation = atk_relation_new(targets,1, ATK_RELATION_LABEL_FOR);
Packit 1470ea
  atk_relation_set_add(relation_set,relation);
Packit 1470ea
  g_object_unref(G_OBJECT(relation));
Packit 1470ea
}
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
<para>
Packit 1470ea
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 <link linkend="gad-custom">Making Custom Components Accessible</link>) or if you want to write an assistive technology application. Whatever the purpose, the <ulink url="ftp://ftp.gnome.org/pub/GNOME/sources/gail/">GAIL source code</ulink> 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.
Packit 1470ea
</para>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Gtk Modules</title>
Packit 1470ea
<para>
Packit 1470ea
Programs that make use of GAIL (the accessibility implementation library for GTK widgets) are written as GTK modules. GTK modules are loaded into the program space if the <varname>GTK_MODULES</varname> environment variable specifies the module library name(s). If there are multiple module libraries, separate them with colons. For example:
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
<userinput>setenv GTK_MODULES "libgail:libtestprops"</userinput>
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
All GTK modules have a <function>gtk_module_init()</function> function. 
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Gathering accessibility information from an application</title>
Packit 1470ea
<para>
Packit 1470ea
A program that wishes to make use of ATK calls would likely need to do one (or more) of the following things:
Packit 1470ea
</para>
Packit 1470ea
<orderedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Create an event watcher, for example with the <function>atk_add_focus_tracker()</function> function:
Packit 1470ea
</para>
Packit 1470ea
<programlisting>atk_add_focus_tracker (_my_focus_tracker);</programlisting>
Packit 1470ea
<para>
Packit 1470ea
where <function>_my_focus_tracker()</function> is a function with this prototype:
Packit 1470ea
</para>
Packit 1470ea
<programlisting>void _my_focus_tracker (AtkObject *aobject);</programlisting>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Set up a global event listener, with atk_add_global_event_listener():
Packit 1470ea
</para>
Packit 1470ea
<programlisting>
Packit 1470ea
mouse_watcher_focus_id =   atk_add_global_event_listener(_my_global_listener,"Gtk:GtkWidget:enter_notify_event");
Packit 1470ea
</programlisting>
Packit 1470ea
<para>
Packit 1470ea
where <function>_my_global_listener</function> has the prototype of a Glib <type>GSignalEmissionHook</type>. This example would cause the <function>_my_global_listener()</function> to be called whenever an enter_notify_even signal occurs on a <type>GtkWidget</type> object.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Access the ATK top-level object with the following function call.
Packit 1470ea
</para>
Packit 1470ea
<programlisting>AtkObject *root_obj = atk_get_root();</programlisting>
Packit 1470ea
<para>
Packit 1470ea
This returns an <type>AtkObject</type> 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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</orderedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Querying an <type>AtkObject</type>'s Interfaces</title>
Packit 1470ea
<para>
Packit 1470ea
Having located the <type>AtkObject</type> associated with an object in the application (e.g. by using <function>gtk_widget_get_accessible()</function>), you can find out what interfaces it implements in various ways:
Packit 1470ea
</para>
Packit 1470ea
<orderedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Use the supplied <function>ATK_IS_...</function> macros, for example:
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
<function>ATK_IS_ACTION(atkobj)</function>
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
<function>ATK_IS_COMPONENT(atkobj)</function>
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
etc. (there is one for each interface)
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
<para>
Packit 1470ea
If the macro returns <function>TRUE</function>, the interface calls can safely be made on that ATK object.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Test the role of the <type>AtkObject</type> by calling <function>atk_object_get_role()</function>. Any given role implements a specific number of ATK APIs.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</orderedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Setting up an ATK Signal Handler</title>
Packit 1470ea
<para>
Packit 1470ea
Using the <constant>column_inserted</constant> signal as an example:
Packit 1470ea
</para>
Packit 1470ea
<programlisting>
Packit 1470ea
table_column_inserted_id = g_signal_connect_closure_by_id (my_atk_obj, 
Packit 1470ea
g_signal_lookup("column_inserted", G_OBJECT_TYPE(my_atk_obj)), 0, 
Packit 1470ea
g_cclosure_new(G_CALLBACK (_my_table_column_inserted_func), NULL, NULL), FALSE);
Packit 1470ea
</programlisting>
Packit 1470ea
<para>This will cause <function>_my_table_column_inserted_func()</function> to be called whenever a column_inserted signal is emitted on the <type>AtkObject</type> <varname>my_atk_object</varname>.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Connecting to a signal is slightly different if the signal supports detail. The <constant>children_changed</constant> signal supports the <parameter>add</parameter> detail. To connect to a signal when the <parameter>add</parameter> detail is also specified, this technique is used:
Packit 1470ea
</para>
Packit 1470ea
<programlisting>
Packit 1470ea
child_added_id = g_signal_connect_closure (my_atk_obj,"children_changed::add",
Packit 1470ea
g_cclosure_new (G_CALLBACK(_my_children_changed_func), NULL, NULL), FALSE);
Packit 1470ea
</programlisting>
Packit 1470ea
<para>
Packit 1470ea
This will cause <function>_my_children_changed_func()</function> to be called whenever a <constant>children_changed</constant> signal with the <parameter>add</parameter> detail is emitted on the <type>AtkObject</type> <varname>my_atk_obj</varname>.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Implementing an ATK Object</title>
Packit 1470ea
<para>
Packit 1470ea
You will need to implement your own ATK objects for any widgets that do not already have an accessible implementation in GAIL (or the equivalent library for other widget sets).  This should be implemented as a GTK module, which, as before, should be included in the <envar>GTK_MODULES</envar> environment variable so it is loaded at runtime.
Packit 1470ea
</para>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Vpisnik</title>
Packit 1470ea
<para>
Packit 1470ea
For this example we will assume there is an object called GTK_TYPE_MYTYPE. The ATK implementation will be called <type>MYATKIMP_TYPE_MYTYPE</type>. A factory will be needed which will be called <type>MYATKIMP_TYPE_MYTYPE_FACTORY</type>.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
To register an ATK implementation of a GTK object, these steps must be followed in the module's <function>gtk_module_init()</function> function:
Packit 1470ea
</para>
Packit 1470ea
<orderedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Access the default registry:
Packit 1470ea
</para>
Packit 1470ea
<programlisting>
Packit 1470ea
default_registry = atk_get_default_registry();
Packit 1470ea
</programlisting>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem><para>Register the ATK object in the <function>gtk_module_init()</function> function of this module by making this function call:
Packit 1470ea
</para>
Packit 1470ea
<programlisting>
Packit 1470ea
atk_registry_set_factory_type (default_registry, GTK_TYPE_MYTYPE, 
Packit 1470ea
MYATKIMP_TYPE_MYTYPE_FACTORY); 
Packit 1470ea
</programlisting>
Packit 1470ea
</listitem>
Packit 1470ea
</orderedlist>
Packit 1470ea
<para>
Packit 1470ea
This will register the AtkObject implementation of <type>GTK_TYPE_MYTYPE</type> to <type>MYATKIMP_TYPE_MYTYPE_FACTORY</type>. This factory will be implemented so that it knows how to build objects of type <type>MYATKIMP_TYPE_MYTYPE</type>.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Factory</title>
Packit 1470ea
<para>
Packit 1470ea
The factory must be implemented as a child of class type <type>ATK_TYPE_OBJECT_FACTORY</type> and must implement the function <function>create_accessible()</function>. This function must create an appropriate <type>AtkObject</type>. A factory can be used to create more than one type of object, in which case its <function>create_accessible()</function> function will need to be smart enough to build and return the correct <type>AtkObject</type>.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>ATK Implementation for a Specific Object</title>
Packit 1470ea
<para>
Packit 1470ea
All <type>GObject</type>s implement a <function>get_type()</function> function.  Using the above example the naming convention for this function name would be <function>myatkimp_mytype_get_type()</function>.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
In this function, you specify which interfaces your object implements. If the following logic were included in this <function>get_type()</function> function, this object would implement the <type>ATK_TEXT</type> interface:
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>Sample <function>get_type()</function> function</title>
Packit 1470ea
<programlisting>
Packit 1470ea
static const GInterfaceInfo atk_text_info = 
Packit 1470ea
{ 
Packit 1470ea
   (GInterfaceInitFunc) atk_text_interface_init, 
Packit 1470ea
   (GInterfaceFinalizeFunc) NULL, 
Packit 1470ea
   NULL 
Packit 1470ea
}; 
Packit 1470ea
Packit 1470ea
g_type_add_interface_static (type, ATK_TYPE_TEXT, 
Packit 1470ea
                             &atk_text_info); 
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
<para>
Packit 1470ea
The function <function>atk_text_interface_init()</function>, which has the following prototype, would need to be implemented:
Packit 1470ea
</para>
Packit 1470ea
<programlisting>
Packit 1470ea
void atk_text_interface_init (AtkTextIface *iface); 
Packit 1470ea
</programlisting>
Packit 1470ea
<para>
Packit 1470ea
This function would connect the interface function calls to the specific implementation as follows:
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>Connecting custom interface calls to an AtkObject implementation</title>
Packit 1470ea
<programlisting>
Packit 1470ea
void 
Packit 1470ea
atk_text_interface_init (AtkTextIface *iface) 
Packit 1470ea
{ 
Packit 1470ea
   g_return_if_fail (iface != NULL); 
Packit 1470ea
   iface->get_text = myatkimp_mytype_get_text; 
Packit 1470ea
   iface->get_character_at_offset = myatkimp_mytype_get_character_at_offset; 
Packit 1470ea
   ... 
Packit 1470ea
}
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
<para>
Packit 1470ea
Then the functions <function>myatkimp_mytype_get_text()</function>, <function>myatkimp_mytype_get_character_at_offset()</function>, and the rest of the <type>ATK_TEXT</type> interface functions would need to be implemented.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title><type>AtkObject</type> Implementation</title>
Packit 1470ea
<para>
Packit 1470ea
<type>AtkObject</type>s are <type>GObjects</type>, and all <type>GObject</type>s need to specify the <function>get_type()</function> function. Here is an example that sets up a class and instance initializer. This <function>get_type()</function> function also specifies that the object implements <type>ATK_TEXT</type> and specifies the parent object to be <type>MYATKIMP_MYPARENTTYPE</type>.
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>Sample <function>get_type()</function> implementation</title>
Packit 1470ea
<programlisting>
Packit 1470ea
GType 
Packit 1470ea
myatkimp_mytype_get_type (void) 
Packit 1470ea
{ 
Packit 1470ea
   static GType type = 0; 
Packit 1470ea
Packit 1470ea
   if (!type) 
Packit 1470ea
   { 
Packit 1470ea
      static const GTypeInfo tinfo = 
Packit 1470ea
      { 
Packit 1470ea
         sizeof (GailLabelClass), 
Packit 1470ea
         (GBaseInitFunc) NULL,                              /* base init */ 
Packit 1470ea
         (GBaseFinalizeFunc) NULL,                          /* base finalize */
Packit 1470ea
         (GClassInitFunc) myatkimp_mytype_class_init,       /* class init */ 
Packit 1470ea
         (GClassFinalizeFunc) NULL,                         /* class finalize */ 
Packit 1470ea
         NULL,                                              /* class data */ 
Packit 1470ea
         sizeof (GailLabel),                                /* instance size */ 
Packit 1470ea
         0,                                                 /* nb preallocs */ 
Packit 1470ea
         (GInstanceInitFunc) myatkimp_mytype_instance_init, /* instance init */ 
Packit 1470ea
         NULL                                               /* value table */ 
Packit 1470ea
      }; 
Packit 1470ea
Packit 1470ea
      /* Set up atk_text_info structure used below */ 
Packit 1470ea
      static const GInterfaceInfo atk_text_info = 
Packit 1470ea
      { 
Packit 1470ea
         (GInterfaceInitFunc) atk_text_interface_init, 
Packit 1470ea
         (GInterfaceFinalizeFunc) NULL, 
Packit 1470ea
         NULL 
Packit 1470ea
      }; 
Packit 1470ea
Packit 1470ea
      /* Set up typename and specify parent type */ 
Packit 1470ea
      type = g_type_register_static (MYATKIMP_MYPARENTTYPE, 
Packit 1470ea
            "MyatkimpMytype", &tinfo, 0); 
Packit 1470ea
Packit 1470ea
      /* This class implements interface ATK_TYPE_TEXT */ 
Packit 1470ea
      g_type_add_interface_static (type, ATK_TYPE_TEXT, 
Packit 1470ea
                                   &atk_text_info); 
Packit 1470ea
   } 
Packit 1470ea
   return type; 
Packit 1470ea
} 
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Class/Instance Initializers</title>
Packit 1470ea
<para>
Packit 1470ea
You will have to set up a class initializer for the <type>GObject</type> if your <type>AtkObject</type> implementation either:
Packit 1470ea
</para>
Packit 1470ea
<orderedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Redefines any function calls defined by the object's parent. This is typically necessary when an object needs to implement a function like <function>atk_object_get_n_accessible_children()</function>.  This is necessary if the object has children, but they are not represented with widgets.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
For example, if your ATK implementation needs to over-ride the <type>AtkObject</type> function <function>get_name()</function>, then the class initializer would look like:
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>Class initializer that overrides parent's <function>get_name()</function> function</title>
Packit 1470ea
<programlisting>
Packit 1470ea
myatkimp_mytype_class_init (GailLabelClass *klass) 
Packit 1470ea
{ 
Packit 1470ea
  AtkObjectClass *class = ATK_OBJECT_CLASS (klass); 
Packit 1470ea
  class->get_name = myatkimp_mytype_get_name; 
Packit 1470ea
} 
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem><para>Requires a <function>parent->init</function>, <function>parent->notify_gtk</function>, or <function>parent->finalize</function> function. This example defines all three:
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>Class initializer that defines its own <function>init()</function>, <function>notify_gtk()</function> and <function>finalize()</function> functions</title>
Packit 1470ea
<programlisting>
Packit 1470ea
static ParentObjectType *parent_class = NULL; 
Packit 1470ea
Packit 1470ea
myatkimp_mytype_class_init (GailLabelClass *klass) 
Packit 1470ea
{ 
Packit 1470ea
   ParentObjectType *parent_class = (ParentObjectType*)klass; 
Packit 1470ea
Packit 1470ea
   /* 
Packit 1470ea
    * Caching the parent_class is necessary if the init, 
Packit 1470ea
    * notify_gtk, or finalize functions are set up. 
Packit 1470ea
    */ 
Packit 1470ea
    parent_class = g_type_class_ref (MYATKIMP_TYPE_PARENT); 
Packit 1470ea
Packit 1470ea
    parent_class->init = myatkimp_mytype_widget_init; 
Packit 1470ea
    parent_class->notify_gtk = myatkimp_mytype_real_notify_gtk; 
Packit 1470ea
    parent_class->finalize = myatkimp_mytype_finalize; 
Packit 1470ea
}
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
<orderedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
parent->init
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
A <function>parent->init()</function> function may be necessary if the ATK implementation needs to do either of the following:
Packit 1470ea
</para> 
Packit 1470ea
<orderedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Cache any data obtained from a backing GTK widget.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Listen to any signals from the backing GTK widget.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</orderedlist>
Packit 1470ea
<para>
Packit 1470ea
Here is an example of both:
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>A custom <function>init()</function> function</title>
Packit 1470ea
<programlisting>
Packit 1470ea
void 
Packit 1470ea
gail_tree_view_widget_init (MyatkimpMytype  *mytype, 
Packit 1470ea
                            GtkWidget       *gtk_widget) 
Packit 1470ea
{ 
Packit 1470ea
   /* Make sure to call the parent's init function */ 
Packit 1470ea
   parent_class->init (widget, gtk_widget); 
Packit 1470ea
   
Packit 1470ea
   /* Cache a value in the ATK implementation */ 
Packit 1470ea
   mytype->cached_value = gtk_widget_function_call(); 
Packit 1470ea
Packit 1470ea
   /* Listen to a signal */ 
Packit 1470ea
   gtk_signal_connect (GTK_OBJECT (gtk_widget), 
Packit 1470ea
                       "signal-type", 
Packit 1470ea
                       GTK_SIGNAL_FUNC (_myatkimp_mytype_signal_type), 
Packit 1470ea
                       NULL); 
Packit 1470ea
} 
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
<para>
Packit 1470ea
In this example, if the specified <type>signal-type</type> signal were generated on the backing <varname>gtk_widget</varname>, then the <function>_myatkimp_mytype_signal_type()</function> function would be called.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
parent->notify_gtk
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
If the ATK implementation needs to listen to any property notifications on the backing GTK object, a <function>parent->notify_gtk()</function> function may be necessary. For example:
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>A custom <function>notify_gtk()</function> function</title>
Packit 1470ea
<programlisting>
Packit 1470ea
void 
Packit 1470ea
myatkimp_mytype_real_notify_gtk (GObject    *obj, 
Packit 1470ea
                                 GParamSpec *pspec) 
Packit 1470ea
{ 
Packit 1470ea
   GtkWidget *widget = GTK_WIDGET (obj); 
Packit 1470ea
   AtkObject* atk_obj = gtk_widget_get_accessible (widget); 
Packit 1470ea
Packit 1470ea
   if (strcmp (pspec->name, "property-of-interest") == 0) 
Packit 1470ea
   { 
Packit 1470ea
      /* Handle the property change. */ 
Packit 1470ea
   } 
Packit 1470ea
   else 
Packit 1470ea
   { 
Packit 1470ea
      parent_class->notify_gtk (obj, pspec); 
Packit 1470ea
   } 
Packit 1470ea
} 
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
parent->finalize
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
If it is necessary to free any data when a <type>GObject</type> instance is destroyed, then a <function>finalize()</function> function is needed to free the memory.  For example:
Packit 1470ea
</para>
Packit 1470ea
<example>
Packit 1470ea
<title>A custom <function>finalize()</function> function</title>
Packit 1470ea
<programlisting>
Packit 1470ea
void 
Packit 1470ea
myatkimp_mytype_finalize (GObject *object) 
Packit 1470ea
{ 
Packit 1470ea
   MyAtkimpMyType *my_type = MYATKIMP_MYTYPE (object); 
Packit 1470ea
Packit 1470ea
   g_object_unref (my_type->cached_value); 
Packit 1470ea
   G_OBJECT_CLASS (parent_class)->finalize (object); 
Packit 1470ea
} 
Packit 1470ea
</programlisting>
Packit 1470ea
</example>
Packit 1470ea
</listitem>
Packit 1470ea
</orderedlist>
Packit 1470ea
</listitem>
Packit 1470ea
</orderedlist>
Packit 1470ea
</section>
Packit 1470ea
</section>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="gad-custom">
Packit 1470ea
<title>Making Custom Components Accessible</title>
Packit 1470ea
<para>
Packit 1470ea
Adding ATK support to your custom widget will assure its cooperation with the accessibility infrastructure. These are the general steps that are required:
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
assess a custom widget according to the applicable <link linkend="gad-ui-guidelines">User Interface Guidelines</link>;
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
determine which <ulink url="https://developer.gnome.org/atk/stable/interfaces.html">ATK interfaces</ulink> a custom widget should implement, according to the widget's feature set and function;
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
assess which <ulink url="https://developer.gnome.org/atk/stable/interfaces.html">ATK interfaces</ulink> can be inherited from the parent widget class;
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
implement the appropriate ATK interfaces for the widget class in one of two ways:
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
directly by the custom widget, or
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
in an <ulink url="http://library.gnome.org/devel/atk/stable/AtkObject.html"><type>AtkObject</type></ulink> subtype created by a new <ulink url="http://library.gnome.org/devel/atk/stable/AtkObjectFactory.html"><type>AtkObjectFactory</type></ulink> subclass
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
<para>
Packit 1470ea
If the second method is used, the appropriate factory type must be registered with the <type>AtkObjectFactoryRegistry</type> at runtime.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
<para>
Packit 1470ea
The <ulink url="ftp://ftp.gnome.org/pub/GNOME/sources/gail/">GAIL source code</ulink> serves as an excellent tutorial for advanced ATK usage. 
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="gad-ui-guidelines">
Packit 1470ea
<title>User Interface Guidelines for Supporting Accessibility</title>
Packit 1470ea
<para>
Packit 1470ea
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!
Packit 1470ea
</para>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>General</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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 <guibutton>Finish</guibutton> 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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Keyboard Navigation</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
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!
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Use a logical keyboard navigation order. When navigating around a window with the <keycap>Tab</keycap> key, keyboard focus should move between controls in a predictable order.  In Western locales, this is normally left to right and top to bottom.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Don't override existing system-level accessibility features. For example, <ulink url="http://www.rehab.uiuc.edu/accessx/overview.html">AccessX</ulink> 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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Don't use general navigation functions to trigger operations. For example, do not use basic <keycap>Tab</keycap> keyboard navigation in a dialog to activate any actions associated with a control.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Show keyboard-invoked menus, windows and tooltips near the object they relate to. In GNOME 2.0, users can call up popup menus with <keycombo><keycap>Shift</keycap><keycap>F10</keycap></keycombo>, and tooltips with <keycombo><keycap>Shift</keycap><keycap>F1</keycap></keycombo>. Do not completely hide or obscure the object to which the menu or tooltip refers, however.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Mouse Interaction</title>
Packit 1470ea
<para>
Packit 1470ea
Remember that not everybody can use a mouse with equal dexterity, and that some users may have difficulty seeing or following the mouse pointer.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Allow all mouse operations to be cancelled. Pressing the <keycap>Esc</keycap> 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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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 <link linkend="gad-mouse-examples">Mouse Interaction Examples</link>.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
Packit 1470ea
<section id="gad-mouse-examples">
Packit 1470ea
<title>Mouse Interaction Examples</title>
Packit 1470ea
<figure>
Packit 1470ea
<title>Example of "no-drop" pointer from CDE/Motif</title>
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/nodrop.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Example of an "invalid drop target" pointer shape</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</figure>
Packit 1470ea
</section>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Graphical Elements</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Fonts and Text</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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 <link linkend="gad-font-examples">Fonts and Text Examples</link>.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
When you use static text to label a control, end the label with a colon. For example, <guilabel>Username:</guilabel> 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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
Packit 1470ea
<section id="gad-font-examples">
Packit 1470ea
<title>Fonts and Text Examples</title>
Packit 1470ea
<figure id="label-placement-example">
Packit 1470ea
<title>Correct label placement for various GUI elements</title>
Packit 1470ea
<informaltable frame="all">
Packit 1470ea
<tgroup cols="3" align="center">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/label_above.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>List control with label above</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
List control with label above
Packit 1470ea
</entry>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/label_below.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Large file manager icon with label underneath</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
Large file manager icon with label underneath
Packit 1470ea
</entry>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/label_right.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Small toolbar icon with label to its right</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
Small toolbar icon with label to its right
Packit 1470ea
</entry>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/label_left.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Spinbox control with label to its left</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
Spinbox control with label to its left
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
</informaltable>
Packit 1470ea
</figure>
Packit 1470ea
</section>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Color and Contrast</title>      
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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 <link linkend="gad-color-examples">Color and Contrast Examples</link>.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
Packit 1470ea
<section id="gad-color-examples">
Packit 1470ea
<title>Color and Contrast Examples</title>
Packit 1470ea
<example>
Packit 1470ea
<title>Example illustrating redundant use of color</title>
Packit 1470ea
<informaltable frame="all">
Packit 1470ea
<tgroup cols="2">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/color_only.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Example showing changes in stock price using color only</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
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.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/color_and_arrows.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Example showing changes in stock price using both color and arrows</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
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 <guilabel>Preferences</guilabel> dialog.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
</informaltable>
Packit 1470ea
</example>
Packit 1470ea
</section>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Magnification</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Provide the ability for the user to magnify the work area.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Audio</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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!
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Allow users to configure frequency and volume of all warning beeps and other sounds. This includes being able to turn off sound altogether.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Animation</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Don't flash or blink large areas of the screen. Small areas are less likely to trigger seizures in those susceptible to them.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Make all animations optional. The animated information should be available in at least one non-animated format, at the user's request.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Keyboard Focus</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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 <guilabel>OK</guilabel> or <guilabel>Cancel</guilabel> buttons of a dialog even if they are the most commonly used controls, as they can always be activated immediately by pressing <keycap>Enter</keycap> or <keycap>Escape</keycap>.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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 <link linkend="gad-focus-examples">Keyboard Focus Examples</link>.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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 <link linkend="gad-focus-examples">Keyboard Focus Examples</link>.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.)
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
Packit 1470ea
<section id="gad-focus-examples">
Packit 1470ea
<title>Keyboard Focus Examples</title>
Packit 1470ea
<example><title>Example illustrating need to show focus clearly</title>
Packit 1470ea
<informaltable frame="all">
Packit 1470ea
<tgroup cols="2">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/badfocus1.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>The focused item in this window cannot be seen because it has been scrolled off-screen</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
One of the controls in this window has focus, but it's impossible to tell which...
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/badfocus2.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>The focused item in the list has been brought into view by scrolling the list</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
...until you scroll the list, which reveals that one of its items is currently selected.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/goodfocus.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>The list control in this example has a solid border indicating focus, whether its selected item is currently visible or not</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
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.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
</informaltable>
Packit 1470ea
</example>
Packit 1470ea
<example>
Packit 1470ea
<title>Example illustrating use of secondary focus</title>
Packit 1470ea
<informaltable frame="all">
Packit 1470ea
<tgroup cols="2">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/badfocus3.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Split-paned window in which both panes seem to have focus</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
In this example, it's impossible to tell just by looking which of the two panes actually has keyboard focus.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/goodfocus3.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Split-pane window in which secondary highlighting is used to show which pane has focus</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
By using a secondary selection highlight color in the inactive pane, it's immediately obvious that the tree control has focus here...
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry valign="middle">
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/goodfocus2.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>Split-pane window in which secondary highlighting is used to show which pane has focus</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</entry>
Packit 1470ea
<entry>
Packit 1470ea
...and that the list control has focus here.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
</informaltable>
Packit 1470ea
</example>
Packit 1470ea
</section>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Timing</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Documentation</title>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Provide all documentation in an accessible format. ASCII text and HTML are both excellent formats for assistive technologies.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Provide alternative text descriptions for all graphics in the documentation.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
</section>
Packit 1470ea
</chapter>
Packit 1470ea
Packit 1470ea
<chapter id="gtest" status="draft">
Packit 1470ea
<title>Testing</title>
Packit 1470ea
<para>
Packit 1470ea
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. <ulink url="http://ldtp.freedesktop.org/">LDTP</ulink>, for example, may complement your automated testing plan.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Keyboard Navigation</title>
Packit 1470ea
<para>
Packit 1470ea
The following keyboard operations should be tested. Do not use the mouse in any part of this test.
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Using only keyboard commands, move the focus through all menu bars in the application.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>Confirm that:</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Context sensitive menus display correctly.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Any functions listed on the toolbar can be performed using the keyboard.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
You can operate every control in the client area of the application and dialog boxes.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Text and objects within the client area can be selected.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Any keyboard enhancements or shortcuts are working as designed.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Graphical Elements</title>
Packit 1470ea
<para>
Packit 1470ea
Test the application using a screen reader and confirm that:
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Labels and text are being read correctly, including menus and toolbars.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Object information is read correctly.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Visual Focus Indicator</title>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Verify that when moving among objects that the visual focus indicator is easy to identify.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Keyboard navigation through the software and menus should be clearly visible when the focus moves.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Confirm that the screen reader is tracking the visual focus indicator as you navigate using a keyboard.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Fonts and Text</title>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Change the font in the application and confirm that the settings are maintained.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Test the application by changing colors and confirm that all settings are maintained.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
If magnification is available, test the font, color, and size using the magnification option.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Color and Contrast</title>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Print screenshots to a black and white printer and confirm that all information is visible.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Test applications using only black and white, high-contrast settings and confirm that all information is conveyed correctly.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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).
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Turn on high-contrast settings in the GNOME Control Center and confirm that the application respects these settings.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Test various themes to ensure that the software is working for all the available settings.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Audio</title>
Packit 1470ea
<para>
Packit 1470ea
There should be an option in the application to show audio alerts visually.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Test that the audio is working correctly by enabling sound in the GNOME Control Center and then perform the following actions:
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Perform an action that should generate an audio alert and confirm that the application is working as designed.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Verify that the application works correctly when increasing or decreasing the volume.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Confirm that warning messages and alerts can be heard correctly in a noisy work environment.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Animation</title>
Packit 1470ea
<para>
Packit 1470ea
Verify that an option is available to stop animation and that it is working as designed.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Turn the animation off. Confirm that all information is still conveyed correctly.
Packit 1470ea
</para>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Keyboard Focus</title>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Make sure an option has been included to adjust the response time and confirm that it is working as designed.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Documentation</title>
Packit 1470ea
<para>
Packit 1470ea
Test ASCII text documentation with a screen reader to confirm that it is clear and precise and can be read by assistive technologies.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Test HTML applications using a web browser and screen reader to confirm that the documentation is accessible to assistive technologies.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Note: There are web accessibility guidelines available at <ulink url="http://www.w3.org/TR/WAI-WEBCONTENT/">http://www.w3.org/TR/WAI-WEBCONTENT/</ulink>.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Confirm the following information is included in the documentation:
Packit 1470ea
</para>
Packit 1470ea
<itemizedlist>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
State if the application does not support the standard keyboard access used by the OS.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Identify if there are unique keyboard commands.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
Identify any unique accessibility features.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
<listitem>
Packit 1470ea
<para>
Packit 1470ea
If an action is documented for the mouse, make sure there is an alternative for using the keyboard.
Packit 1470ea
</para>
Packit 1470ea
</listitem>
Packit 1470ea
</itemizedlist>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section id="gad-checklist">
Packit 1470ea
<title>User Interface Checklist</title>
Packit 1470ea
<para>
Packit 1470ea
This section summarizes the guidelines given in <link linkend="gad-ui-guidelines">User Interface Guidelines for Supporting Accessibility</link>. You should refer to that section of the guide for more detailed information on any of the checklist items given here.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
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.
Packit 1470ea
</para>
Packit 1470ea
Packit 1470ea
<title>General Principles checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>GP</entry>
Packit 1470ea
<entry>General Principles</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>GP.1</entry>
Packit 1470ea
<entry>
Packit 1470ea
Every action that alters the user's data or application's settings can be undone.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry>GP.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
All application settings can be restored to their defaults without the user having to remember what those defaults were.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry>GP.3</entry>
Packit 1470ea
<entry>
Packit 1470ea
After installation, the application can be used without the user having to insert a disk or CD at any time.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>GP.4</entry>
Packit 1470ea
<entry>
Packit 1470ea
The most frequently used functions are found at the top level of the menu structure.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Keyboard navigation checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>KN</entry>
Packit 1470ea
<entry>Keyboard Navigation</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>KN.1</entry>
Packit 1470ea
<entry>Efficient keyboard access is provided to all application features.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry>KN.2</entry>
Packit 1470ea
<entry>All windows have a logical keyboard navigation order.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.3</entry>
Packit 1470ea
<entry>
Packit 1470ea
The correct tab order is used for controls whose enabled state is dependent on checkboxes, radio buttons or toggle buttons.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.4</entry>
Packit 1470ea
<entry>
Packit 1470ea
Keyboard access to application-specific functions does not override existing system accessibility features.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.5</entry>
Packit 1470ea
<entry>
Packit 1470ea
The application provides more than one method to perform keyboard tasks whenever possible.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.6</entry>
Packit 1470ea
<entry>
Packit 1470ea
There are alternative key combinations wherever possible.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.7</entry>
Packit 1470ea
<entry>
Packit 1470ea
There are no awkward reaches for frequently performed keyboard operations.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.8</entry>
Packit 1470ea
<entry>
Packit 1470ea
The application does not use repetitive, simultaneous keypresses.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.9</entry>
Packit 1470ea
<entry>
Packit 1470ea
The application provides keyboard equivalents for all mouse functions.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.10</entry>
Packit 1470ea
<entry>
Packit 1470ea
Any text or object that can be selected with the mouse can also be selected with the keyboard alone.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.11</entry>
Packit 1470ea
<entry>
Packit 1470ea
Any object that can be resized or moved with the mouse can also be resized or moved with the keyboard alone.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.12</entry>
Packit 1470ea
<entry>
Packit 1470ea
The application does not use any general navigation functions to trigger operations.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KN.13</entry>
Packit 1470ea
<entry>
Packit 1470ea
All keyboard-invoked menus, windows and tooltips appear near the object they relate to.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Mouse Interaction checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>MI</entry>
Packit 1470ea
<entry>Mouse Interaction</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>MI.1</entry>
Packit 1470ea
<entry>No operations depend on input from the <mousebutton>right</mousebutton> or <mousebutton>middle</mousebutton> mouse buttons.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>MI.2</entry>
Packit 1470ea
<entry>All mouse operations can be cancelled before they are complete.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>MI.3</entry>
Packit 1470ea
<entry>
Packit 1470ea
Visual feedback is provided throughout drag and drop operations
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>MI.4</entry>
Packit 1470ea
<entry>
Packit 1470ea
The mouse pointer is never warped under application control, or its movement restricted to part of the screen by the application.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Graphical Elements checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>GE</entry>
Packit 1470ea
<entry>Graphical Elements</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>GE.1</entry>
Packit 1470ea
<entry>
Packit 1470ea
There are no hard-coded graphical attributes such as line, border or shadow thickness.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>GE.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
All multi-color graphical elements can be shown in monochrome only, where possible.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>GE.3</entry>
Packit 1470ea
<entry>
Packit 1470ea
All interactive GUI elements are easily distinguishable from static GUI elements.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>GE.4</entry>
Packit 1470ea
<entry>
Packit 1470ea
An option to hide non-essential graphics is provided.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Fonts and Text checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>FT</entry>
Packit 1470ea
<entry>Fonts and Text</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>FT.1</entry>
Packit 1470ea
<entry>No font styles or sizes are hard-coded.</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>FT.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
An option to turn off graphical backdrops behind text is provided.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>FT.3</entry>
Packit 1470ea
<entry>
Packit 1470ea
All labels have names that make sense when taken out of context.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>FT.4</entry>
Packit 1470ea
<entry>
Packit 1470ea
No label names are used more than once in the same window.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>FT.5</entry>
Packit 1470ea
<entry>
Packit 1470ea
Label positioning is consistent throughout the application.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>FT.6</entry>
Packit 1470ea
<entry>
Packit 1470ea
All static text labels that identify other controls end in a colon (:).
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>FT.7</entry>
Packit 1470ea
<entry>
Packit 1470ea
Static text labels that identify other controls immediately precede those controls in the tab order.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>FT.8</entry>
Packit 1470ea
<entry>
Packit 1470ea
An alternative to WYSIWYG is provided. For example, the ability to specify different screen and printer fonts in a text editor.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Color and Contrast checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>CC</entry>
Packit 1470ea
<entry>Color and Contrast</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>CC.1</entry>
Packit 1470ea
<entry>
Packit 1470ea
Application colors are not hard-coded, but are drawn either from the current desktop theme or an application setting.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>CC.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
Color is only used as an enhancement, and not as the only means to convey information or actions.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row>
Packit 1470ea
<entry>CC.3</entry>
Packit 1470ea
<entry>
Packit 1470ea
The application supports all available high- contrast themes and settings.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>CC.4</entry>
Packit 1470ea
<entry>
Packit 1470ea
The software is not dependent on any particular high-contrast themes or settings.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Magnification checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>MG</entry>
Packit 1470ea
<entry>Magnification</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>MG.1</entry>
Packit 1470ea
<entry>
Packit 1470ea
The application provides the ability to magnify the work area.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>MG.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
The application provides the option to scale the work area.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>MG.3</entry>
Packit 1470ea
<entry>
Packit 1470ea
The application's functionality is not affected by changing the magnification or scale settings.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Audio checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>AU</entry>
Packit 1470ea
<entry>Audio</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>AU.1</entry>
Packit 1470ea
<entry>
Packit 1470ea
Sound is not used as the only means of conveying any items of information.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>AU.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
The user can configure the frequency and volume of all sounds and warning beeps.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Animation checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>AN</entry>
Packit 1470ea
<entry>Animation</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>AN.1</entry>
Packit 1470ea
<entry>
Packit 1470ea
There are no flashing or blinking elements with a frequency greater than 2Hz or lower than 55Hz.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>AN.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
Any flashing or blinking is confined to small areas of the screen.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>AN.3</entry>
Packit 1470ea
<entry>
Packit 1470ea
If animation is used, an option is available to turn it off before it is first shown.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Keyboard Focus checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>KF</entry>
Packit 1470ea
<entry>Keyboard Focus</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>KF.1</entry>
Packit 1470ea
<entry>
Packit 1470ea
When a window is opened, focus starts at the most commonly-used control.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KF.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
Current input focus position is clearly displayed at all times.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KF.3</entry>
Packit 1470ea
<entry>
Packit 1470ea
Input focus is shown in exactly one window at all times.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KF.4</entry>
Packit 1470ea
<entry>
Packit 1470ea
Appropriate audio or visual feedback is provided when the user attempts to navigate past either end of a group of related objects.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KF.5</entry>
Packit 1470ea
<entry>
Packit 1470ea
The default audio or visual warning signal is played when the user presses an inappropriate key.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KF.6</entry>
Packit 1470ea
<entry>
Packit 1470ea
There is sufficient audio information for the visual focus that the user can figure out what to do next.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>KF.7</entry>
Packit 1470ea
<entry>
Packit 1470ea
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.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Timing checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>TM</entry>
Packit 1470ea
<entry>Timing</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>TM.1</entry>
Packit 1470ea
<entry>
Packit 1470ea
There are no hard-coded time-outs or time-based features in the application.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>TM.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
The display or hiding of important information is not triggered solely by movement of the mouse pointer.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<title>Documentation checklist</title>
Packit 1470ea
<tgroup cols="3" align="left">
Packit 1470ea
Packit 1470ea
<row>
Packit 1470ea
<entry>DC</entry>
Packit 1470ea
<entry>Documentation</entry>
Packit 1470ea
<entry>Pass/Fail/NA</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
Packit 1470ea
<row><entry>DC.1</entry>
Packit 1470ea
<entry>
Packit 1470ea
All documentation is in an accessible format, with textual alternate descriptions provided for all figures and diagrams.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
<row><entry>DC.2</entry>
Packit 1470ea
<entry>
Packit 1470ea
The documentation includes a section that covers all the application's accessibility features.
Packit 1470ea
</entry>
Packit 1470ea
</row>
Packit 1470ea
Packit 1470ea
</tgroup>
Packit 1470ea
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>GOK (GNOME Onscreen Keyboard)</title>
Packit 1470ea
<note>
Packit 1470ea
<para>
Packit 1470ea
The information on this page is partially outdated: GNOME 3's <application><ulink url="http://wiki.gnome.org/Caribou">Caribou</ulink></application> has effectively replaced GNOME 2's <application>gok</application>.
Packit 1470ea
</para>
Packit 1470ea
</note>
Packit 1470ea
Packit 1470ea
<para>
Packit 1470ea
Your application should be usable via <application>gok</application>; key input should be generated entirely by <application>gok</application>, 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.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
The <application>gok</application> application ships with the GNOME Desktop so should already be present. For full documentation, refer to <ulink url="http://www.gok.ca">the official gok site</ulink>.
Packit 1470ea
</para>
Packit 1470ea
<para>
Packit 1470ea
Follow these steps to verify the correct operation of <application>gok</application> with your application:
Packit 1470ea
</para>
Packit 1470ea
<procedure>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Login into the GNOME desktop
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Run <application>gok</application>
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Start your application
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Provide input to your application with a pointing device (e.g., mouse or head-tracker) and <application>gok</application>.
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Work using the auto-completion and word prediction features of <application>gok</application>.
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Verify that <application>gok</application> enables and disables the <guibutton>Menus</guibutton> and <guibutton>Toolbars</guibutton> buttons based on the kind of application invoked; for example, the <guibutton>Menus</guibutton> and <guibutton>Toolbars</guibutton> buttons are disabled for the 'Font properties' capplet, but the same buttons are enabled for the <application>Gedit</application> application.
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Verify that the <application>gok</application> on-screen keyboard provided by the <guibutton>Compose</guibutton> button can be used to type in any text for the selected application; run <application>Gedit</application>, click on the text area, and then click on the <guibutton>Compose</guibutton> button in <application>gok</application>. Select the required keys from the on-screen keyboard. The characters should appear in the <application>Gedit</application> text area.
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Verify that the <guibutton>Launcher</guibutton> button allows the user to launch any of the <application>Terminal</application>, <application>Web Browser</application> or <application>Text Editor</application> applications.
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Verify that the <guibutton>Activate</guibutton> 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.
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Verify that the <guibutton>Menus</guibutton> 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 <application>Help Browser</application> application and click on the <guibutton>Menus</guibutton> button. The <application>GOK</application> window now displays the <guibutton>File</guibutton>, <guibutton>Go</guibutton> and <guibutton>Help</guibutton> buttons (the <application>Help Browser</application> menus). Click on the <guibutton>File</guibutton> button and it displays the <guibutton>New Window</guibutton> and <guibutton>Close Window</guibutton> buttons (menu items).
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Verify that the <guibutton>Toolbars</guibutton> button lists all the available buttons in the application toolbar. For example, click on the <application>Help Browser</application> application and then click on the <guibutton>Toolbars</guibutton> button. The <application>GOK</application> window now displays the <guibutton>Back</guibutton>, <guibutton>Forward</guibutton> and <guibutton>Home</guibutton> buttons.
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
<step>
Packit 1470ea
<para>
Packit 1470ea
Verify that the <guibutton>UI Grab</guibutton> button displays all the button objects for the selected application window. For example, open the 'Font Properties' capplet and click on the <guibutton>UI Grab</guibutton> button in the <application>GOK</application> window. The <application>GOK</application> window should now display the names of the buttons in the capplet - <guibutton>Sans</guibutton>, <guibutton>Sans-serif</guibutton>, <guibutton>Close</guibutton> and <guibutton>Help</guibutton>.
Packit 1470ea
</para>
Packit 1470ea
</step>
Packit 1470ea
</procedure>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
<section>
Packit 1470ea
<title>Accerciser</title>
Packit 1470ea
<screenshot>
Packit 1470ea
<mediaobject>
Packit 1470ea
<imageobject>
Packit 1470ea
<imagedata fileref="figures/at-arch.png" format="PNG"/>
Packit 1470ea
</imageobject>
Packit 1470ea
<textobject>
Packit 1470ea
<phrase>
Packit 1470ea
Accerciser and the GNOME Accessibility Architecture
Packit 1470ea
</phrase>
Packit 1470ea
</textobject>
Packit 1470ea
</mediaobject>
Packit 1470ea
</screenshot>
Packit 1470ea
Packit 1470ea
<para>
Packit 1470ea
<application>Accerciser</application> 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. <application>Accerciser</application> has a simple plugin framework which you can use     to create custom views of accessibility information. Full documentation can be found <ulink url="http://library.gnome.org/devel/accerciser/stable">in the Official Accerciser Manual</ulink>. For a demonstration of <application>Accerciser</application> and <application>PyATSPI</application> (Python-wrappered access and usage of AT-SPI), see <ulink url="http://live.gnome.org/Accessibility/PythonPoweredAccessibility">this article</ulink>. For an excellent walkthrough from the author, see the article titled <ulink url="http://www.linuxjournal.com/article/9991">Make Your Application Accessible with Accerciser</ulink>.
Packit 1470ea
</para>
Packit 1470ea
<note>
Packit 1470ea
<para>
Packit 1470ea
<application>Accerciser</application> has effectively replaced the older <application>at-poke</application> tool.
Packit 1470ea
</para>
Packit 1470ea
</note>
Packit 1470ea
</section>
Packit 1470ea
Packit 1470ea
</chapter>
Packit 1470ea
Packit 1470ea
</book>