IMPORTANT: This article is being preserved for historical purposes. Current information and documentation about GNOME Accessibility can be found at: the GNOME Accessibility Project
Coding Guidelines for Supporting Accessibility
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 User Interface Guidelines for Supporting Accessibility section later in this document):
- For components that don't display a short string (such as a graphical button), specify a name for it with atk_object_set_name(). You might want to do this for image-only buttons, panels that provide logical groupings, text areas, and so on.
- If you can't provide a tooltip for a component, use atk_object_set_description() instead to provide a description that assistive technologies can give the user. For example, to provide an accessible description for a Close button:
Example 1. Providing an accessible description for a GtkButton
{
AtkObject *obj;
obj = gtk_widget_get_accessible (button);
atk_object_set_description (obj, _("Closes the window"));
}- Use atk_image_set_description() to provide a text description for all images and icons in your program.
If a bunch of components form a logical group, try to put them into one container. (This is a JFC guideline, does it make a difference with GTK? Does it belong here or in the GUI section?)
- Whenever you have a label that describes another component, use atk_relation_set_add_relation() so that assistive technologies can find the component with which the label is associated. (N.B. If you associate the label with the component using gtk_label_set_mnemonic_widget(), the ATK_RELATION_LABEL_FOR relation is generated automatically, so the following code would not be necessary):
{
GtkWidget *widget;
GtkLabel *label;
AtkObject *atk_widget, *atk_label;
AtkRelationSet *relation_set;
AtkRelation *relation;
AtkObject *targets[1];
atk_widget = gtk_widget_get_accessible (widget);
atk_label = gtk_widget_get_accessible (GTK_WIDGET (label));
relation_set = atk_object_ref_relation_set (atk_label);
targets[0] = atk_widget;
relation = atk_relation_new (targets, 1, ATK_RELATION_LABEL_FOR);
atk_relation_set_add (relation_set, relation);
g_object_unref (G_OBJECT (relation));
}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 Making Custom Components Accessible.
Don't break what you get for free! If your GUI has an inaccessible container, any components inside that container may become inaccessible. (Give an example here. Should it go here or in the GUI section?)