Re: [g-a-devel]Accessibility support in Glade

[Bill Haneman <bill haneman sun com>]

Damon Chaplin wrote:
> 
> Hi,
> 
> I'm about to add a11y support to Glade, based on the libglade DTD.
> 
> A few questions:
> 
> ATK Properties
> --------------
> 
>  o The libglade DTD has:
> 
>     <!ELEMENT atkproperty (#PCDATA | accessibility)* >
> 
>    so it looks like ATK properties can contain other ATK properties,
>    actions, and relations. What is this used for? What would the
>    atkproperty name be?

The following properties are available in ATK (pasting from
AtkObject.c) :

static const gchar* atk_object_name_property_name = "accessible-name";
static const gchar* atk_object_name_property_description =
"accessible-description";

These are of course UTF-8 strings which you can set.

static const gchar* atk_object_name_property_parent =
"accessible-parent";

This one will not be explicitly set as often, but may sometimes be
needed if one wishes to explicitly set an AtkObject hierarchy that
differs from the one that would be constructed by default from the
widget
hierarchy.  It is an AtkObject itself, so it's a case where the
<atkproperty> element would contain an <accessibility> child
element, since each <accessibility/> node constructs an AtkObject.

static const gchar* atk_object_name_property_value = "accessible-value";

You won't need this one often, the AtkValue (which is what uses this)
generally is obtained from the backing widget.

"accessible-role" : only needed for custom widgets; 
I think you can ignore this one for now.

static const gchar* atk_object_name_property_component_layer =
"accessible-component-layer";
static const gchar* atk_object_name_property_component_mdi_zorder =
"accessible-component-mdi-zorder";

These are usually scavenged correctly from the UI/backing widget.

static const gchar* atk_object_name_property_table_caption =
"accessible-table-caption";

You will want to support this property, as a character string, for
widgets whose AtkObjects support AtkTable (currently only
GtkTreeView and GtkHTML2).

static const gchar* atk_object_name_property_table_column_description =
"accessible-table-column-description";
static const gchar* atk_object_name_property_table_row_description =
"accessible-table-row-description";

These will require impementing the API suggested below, in which we 
specify not only a "name" for the atkproperty but also an "index" 
which would allow us to specify which row or column we were operating
on.
Of course if the data is user-specified and not application-specified
(e.g. if the app is generic and Glade doesn't know what the
table will hold) then this API doesn't make sense at UI creation time,
so this needs to be optional. 

static const gchar* atk_object_name_property_table_column_header =
"accessible-table-column-header";
static const gchar* atk_object_name_property_table_row_header =
"accessible-table-row-header";
static const gchar* atk_object_name_property_table_summary =
"accessible-table-summary";

The summary table is itself a table.  We don't have a particularly good
API
that glade could use to attach a summary table, to I suggest leaving
this one for 
now.
 
>    The libglade parser seems to accept these, but it doesn't seem to
>    keep the hierarchy. All the child properties/actions/relations seem
>    to get folded into one list.

If I understand you correctly this is OK; the actions/relations are 
attached to the hierarchy via API calls which the parser should make
when processing <atkrelation> or <atkproperty
name="AtkObject:accessible-parent">
elements.  Maybe I am missing something in your question...

If the libglade parser sees an <atkaction> child of an <accessibility>
child,
it should associate the action with the AtkObject which the
<accessibility>
element refers to (i.e., to the widget's AtkObject).  I think the
current libglade
parsing code does this correctly at the moment, but I could be mistaken.
 
>    Does it matter if Glade doesn't preserve the hierarchy?
>    (Glade uses the libglade parsing code as well.)
> 
>  o The libglade parser seems to look for a translatable attribute on ATK
>    properties. Should we add this to the DTD? The atkaction description
>    should probably also have a translatable attribute.

name, description, and other string properties should be translatable, 
except for "role".  Action descriptions should be translatable.
 
>    We could say that all ATK properties and action descriptions are
>    translatable, so the attribute is not necessary, but intltool would
>    need updating to handle that.
> 
>  o I think the only ATK properties we need to handle are:
> 
>     AtkObject::accessible-name
>     AtkObject::accessible-description
> 
>    Are there any others?
> 
>    Do we have to add the above to properties to every widget?

They are provided by default; glade should only set them if they
are explicitly set by the user.

One question is whether the glade UI should show the user
the default (i.e., "scavenged") values for name and value, 
or not.  If the glade UI shows the default, then it might be
expected that all widgets have explicit atk_object_set_name, etc.
calls; but there are reasons not to make such a call. (see below)

My suggestion is to show the user the default values
(obtainable via atk_object_get_name, atk_object_get_description
if the widgets have been instantiated. If Glade doesn't instantiate
the widgets then you can't do this...).  Then if the user
overrides or edits the default values, you should explicitly store
them, otherwise don't store the property values in the .glade
file.  The reason for not always storing the values is this: if 
an app explicitly sets these values, it triggers instantiation 
of the AtkObject first, which, if the user didn't need accessibility,
would only otherwise happen on-demand.
 
> ATK Relations
> -------------
> 
>  o Is there a way of programmatically determining which relation types
>    are relevant to which widgets?
> 
>    If not, is there a list of which types are relevant to which widgets?

No; but I don't think there is any harm in allowing them for all
widgets; for instance I think most widget types could
conceivably be used (or abused) as "labels".  Likewise
it's only silly, but not dangerous, to refer to a GtkLabel as a 
"controller" for another object.

>    It looks like some relations are automatically created by GAIL
>    itself, e.g. "member-of" is automatically handled for radiobutton
>    groups. So Glade doesn't need to support those.

Well, I think that Glade still needs to provide member-of for other
cases; 
perhaps the best solution is to use ATK API to get the relation set and 
expose it to the user.  Again, this requires that the UI have been
instantiated as part of running Glade.
 
> Glade GUI
> ---------
> 
> I think I'll add a new page to the property editor for a11y.
> (I think I'll use an icon in the notebook tab as we don't have much room
> for text, especially 'Accessibility'!.)

Then of course you will need to provide alt-text for the icon...
and set atk_object_set_name () for the notebook tab.

If you really only expose two properties, is there a danger of
this page just being ignored all the time?  We want this to
be as visible as possible without seriously compromising 
glade's usability.

> At the top we'll have the 2 ATK properties, a string property for
> 'Name:' and a text property for 'Description:', i.e.
> 
>   Name:          _____________________________
>   Description:   _____________________________
>                  _____________________________
> 
> Below that will be text properties for descriptions for each of the
> actions that the widget supports. e.g. for a button it will show:
> 
>   click:         _____________________________
>                  _____________________________
>   press:         _____________________________
>                  _____________________________
>   release:       _____________________________
>                  _____________________________
> 
> (Note that the action names are not translated, so they aren't
> i18n-friendly. But I could hard-code translation support for them.)

Yes, I think that would be the right thing to do here.
 
> Finally, if we can determine which relations are relevant to each type
> of widget (maybe hard-coding them), we'll show properties for each
> relation here, e.g.
> 
>   controlled-by: widget1,widget2_________[...]
>   label-for:     button1_________________[...]
> 
> The text fields won't be editable.
> The buttons on the right will pop up a dialog containing a list of all
> widgets in the window/dialog with checkboxes next to them, so the user
> can select one or more widgets easily. (I hope relations can only be
> between widgets within one window.)

That's a good approximation; relations between widgets
in different windows would probably be a usability bug 
anyhow.
 
> The only thing left to add is support for <atkproperty> elements with
> child <accessibility> elements. But I don't know what that is used for
> yet.

This is used for setting the parent explicitly (somewhat unusual)
and for setting table summaries and headings.

At the moment we have not defined the DTD for setting
table column headers, column descriptions, etc.  Eventually we
will definitely need to do this, but perhaps not for 2.0.0.

For instance, perhaps we want to set an object for a table header,
specifically we want to provide an AtkObject for the third
(zero-indexed)
column:

(the actual header content is relatively unhelpful in this example, 
but it illustrates the technique)

[... XML for the GtkTreeView widget goes here]
<accessibility>
	<atkproperty name="AtkObject:accessible-table-column-header" index=2>
		<accessibility>
			<atkproperty name="AtkObject:accessible-name">
			"February"
			</atkproperty>
			<atkproperty>
			"Accounts receivable entries for Feb, 2002"
			</atkproperty>
		</accessibility>
	</atkproperty>
</accessibility>
 
I think that the atkrelation and atkaction features are more
important for the time being than supporting the non-string
AtkObject properties, though I believe we will need to support
the non-string properties in the future.

So I think that in addition to the properties you mention
(accessible-name and accessible-description), atkrelation,
and atkaction, for 2.0.0 we need only 

accessible-parent, 
accessible-table-caption,
and perhaps the row/column descriptions for tables (but not
the row/column captions or table summary).

I am wondering about "role", but that should be a non-translated
string that's fixed for GTK+ widgets and only modified for 
custom widgets... so exposing it might lead to errors.

- Bill

> Damon
> 
> _______________________________________________
> Gnome-accessibility-devel mailing list
> Gnome-accessibility-devel gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-accessibility-devel