Added descriptive documentation of the ATK interfaces, primarilyATK_0_11

to assist custom widget maintainers and others who need to provide ATK
implementations for widgets outside GTK+ (for which implementations are
already provided by package "gail").

10 files changed, 173 insertions, 32 deletions

diff --git a/ChangeLog b/ChangeLog
index 9cb419b..6e356a4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2002-01-30  Bill Haneman  <bill.haneman@sun.com>
+
+	* docs/tmpl/atkaction.sgml:
+	* docs/tmpl/atkcomponent.sgml:
+	* docs/tmpl/atkeditabletext.sgml:
+	* docs/tmpl/atkimage.sgml:
+	* docs/tmpl/atkobject.sgml:
+	* docs/tmpl/atkselection.sgml:
+	* docs/tmpl/atktable.sgml:
+	* docs/tmpl/atktext.sgml:
+	* docs/tmpl/atkvalue.sgml:
+	Initial entries into the SHORT_DESCRIPTION and LONG_DESCRIPTION
+	fields to improve docs; the documentation now gives some
+	information on the purpose and function of the various ATK
+	interfaces, and which types of UI components typically implement
+	which interfaces.
+	
 Tue Jan 29 23:29:46 2002  Owen Taylor  <otaylor@redhat.com>
 
 	* NEWS: Retroactively write a NEWS entry for 0.9 and 0.10.
diff --git a/docs/tmpl/atkaction.sgml b/docs/tmpl/atkaction.sgml
index 668cdb9..37a4ab2 100644
--- a/docs/tmpl/atkaction.sgml
+++ b/docs/tmpl/atkaction.sgml
@@ -2,13 +2,39 @@
 AtkAction
 
 <!-- ##### SECTION Short_Description ##### -->
-
+The ATK interface provided by UI components which the user can
+activate/interact with,
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#AtkAction should be implemented by instances of #AtkObject classes with
+which the user can interact directly, i.e. buttons, checkboxes,
+scrollbars,  e.g. components which are not "passive"
+providers of UI information.
+</para>
+<para>
+Exceptions: when the user interaction is already covered by
+another appropriate interface such as #AtkEditableText (insert/delete
+test, etc.) or #AtkValue (set value) then these actions should not be
+exposed by #AtkAction as well.  
+</para>
+<para>
+Also note that the #AtkAction API is limited in that parameters may not
+be passed to the object being activated; thus the action must be
+self-contained and specifiable via only a single "verb".  Concrete
+examples include "press", "release", "click" for buttons, "drag"
+(meaning initiate drag) and "drop" for drag sources and drop targets,
+etc.  
+</para>
+<para>
+Though most UI interactions on components should be invocable via
+keyboard as well as mouse, there will generally be a close mapping
+between "mouse actions" that are possible on a component and the
+AtkActions.  Where mouse and keyboard actions are redundant in effect,
+#AtkAction should expose only one action rather than exposing redundant
+actions if possible.  By convention we have been using "mouse centric"
+terminology for #AtkAction names.
 </para>
-
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
diff --git a/docs/tmpl/atkcomponent.sgml b/docs/tmpl/atkcomponent.sgml
index 046d8d4..fdef339 100644
--- a/docs/tmpl/atkcomponent.sgml
+++ b/docs/tmpl/atkcomponent.sgml
@@ -2,11 +2,21 @@
 AtkComponent
 
 <!-- ##### SECTION Short_Description ##### -->
-
-
+ATK Interface provided by UI components which occupy a physical area on
+the screen.
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#AtkComponent should be implemented by most if not all UI elements with
+an actual on-screen presence, i.e. components which can be said to have
+a screen-coordinate bounding box.  Virtually all widgets will need to
+have #AtkComponent implementations provided for their corresponding
+#AtkObject class.  In short, only UI elements which are *not* GUI
+elements will omit this ATK interface.
+</para>
+<para>
+A possible exception might be textual information with a transparent
+background, in which case text glyph bounding box information is
+provided by #AtkText.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/tmpl/atkeditabletext.sgml b/docs/tmpl/atkeditabletext.sgml
index c577880..7fb992e 100644
--- a/docs/tmpl/atkeditabletext.sgml
+++ b/docs/tmpl/atkeditabletext.sgml
@@ -2,16 +2,21 @@
 AtkEditableText
 
 <!-- ##### SECTION Short_Description ##### -->
-
-
+ATK Interface implemented by components containing user-editable text content.
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#AtkEditableText should be implemented by UI components which contain
+text which the user can edit, via the #AtkObject corresponding to that
+component (see #AtkObject).
+</para>
+<para>
+#AtkEditableText is a subclass of #AtkText, and as such, an object which
+implements #AtkEditableText is by definition an #AtkText implementor as well.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#AtkText
 </para>
 
 <!-- ##### STRUCT AtkEditableText ##### -->
diff --git a/docs/tmpl/atkimage.sgml b/docs/tmpl/atkimage.sgml
index e6558cc..ae05133 100644
--- a/docs/tmpl/atkimage.sgml
+++ b/docs/tmpl/atkimage.sgml
@@ -2,11 +2,22 @@
 AtkImage
 
 <!-- ##### SECTION Short_Description ##### -->
-
-
+ATK Interface implemented by components which expose image or pixmap
+content on-screen.
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#AtkImage should be implemented by #AtkObject subtypes on behalf of
+components which display image/pixmap information onscreen, and which
+provide information (other than just widget borders, etc.) via that
+image content.  For instance, icons, buttons with icons, toolbar
+elements, and image viewing panes typically should implement #AtkImage.
+</para>
+<para>
+#AtkImage primarily provides two types of information: coordinate
+information (useful for screen review mode of screenreaders, and for use
+by onscreen magnifiers), and descriptive information.  The descriptive
+information is provided for alternative, text-only presentation of the
+most significant information present in the image.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/tmpl/atkobject.sgml b/docs/tmpl/atkobject.sgml
index c314931..10f6385 100644
--- a/docs/tmpl/atkobject.sgml
+++ b/docs/tmpl/atkobject.sgml
@@ -3,15 +3,31 @@ AtkObject
 
 <!-- ##### SECTION Short_Description ##### -->
 
+The base object class for the Accessibility Toolkit API.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+This class is the primary class for accessibility support via
+the Accessibility ToolKit (ATK).  Objects which are instances
+of #AtkObject (or instances of AtkObject-derived types) are
+queried for properties which relate basic (and generic) properties of a
+UI component such as name and description.  Instances of #AtkObject
+may also be queried as to whether they implement other ATK interfaces
+(e.g. #AtkAction, #AtkComponent, etc.), as appropriate to the role
+which a given UI component plays in a user interface.
+</para>
+<para>All UI components in an application which provide useful
+information or services to the user must provide corresponding
+#AtkObject instances on request (in GTK+, for instance, usually
+on a call to #gtk_widget_get_accessible ()), either via ATK support
+built into the toolkit for the widget class or ancestor class, or in
+the case of custom widgets, if the inherited #AtkObject implementation
+is insufficient, via instances of a new #AtkObject subclass. 
 </para>
-
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+See also: #AtkObjectFactory, #AtkRegistry.
+( GTK+ users see also #GtkAccessible).
 </para>
 
 <!-- ##### STRUCT AtkObject ##### -->
@@ -29,7 +45,9 @@ AtkObject
 
 <!-- ##### ENUM AtkRole ##### -->
 <para>
-
+These are the built-in enumerated roles that UI components can have in
+ATK.  Other roles may be added at runtime, so an AtkRole >=
+ATK_ROLE_LAST_DEFINED is not necessarily an error.
 </para>
 
 @ATK_ROLE_INVALID: 
@@ -114,7 +132,9 @@ AtkObject
 
 <!-- ##### ENUM AtkLayer ##### -->
 <para>
-
+These enumerated "layer values" are used when determining which UI
+rendering layer a component is drawn into, which can help in making
+determinations of when components occlude one another.
 </para>
 
 @ATK_LAYER_INVALID: 
@@ -133,7 +153,9 @@ AtkObject
 
 <!-- ##### STRUCT AtkImplementorIface ##### -->
 <para>
-
+This interface provides an alternative means of obtaining AtkObjects
+from a GOBject instance, and for querying whether a GObject instance
+provides ATK functionality.
 </para>
 
 @parent: 
diff --git a/docs/tmpl/atkselection.sgml b/docs/tmpl/atkselection.sgml
index fdeb7b7..2ace0a4 100644
--- a/docs/tmpl/atkselection.sgml
+++ b/docs/tmpl/atkselection.sgml
@@ -3,15 +3,24 @@ AtkSelection
 
 <!-- ##### SECTION Short_Description ##### -->
 
-
+ATK Interface implemented by container objects whose #AtkObject children
+can be selected.
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#AtkSelection should be implemented by UI components with children which
+are exposed by #atk_object_ref_child and #atk_object_get_n_children, if
+the use of the parent UI component ordinarily involves selection of one
+or more of the objects corresponding to those #AtkObject children - for
+example, selectable lists.
+</para>
+<para>
+Note that other types of "selection" (for instance text selection) are
+accomplished a other ATK interfaces - #AtkSelection is limited to the
+selection/deselection of children.
 </para>
-
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#AtkText
 </para>
 
 <!-- ##### STRUCT AtkSelection ##### -->
diff --git a/docs/tmpl/atktable.sgml b/docs/tmpl/atktable.sgml
index 25dc585..986c1c0 100644
--- a/docs/tmpl/atktable.sgml
+++ b/docs/tmpl/atktable.sgml
@@ -2,16 +2,34 @@
 AtkTable
 
 <!-- ##### SECTION Short_Description ##### -->
-
+ATK Interface implemented for UI components which contain tabular or
+row/column information.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#AtkTable should be implemented by components which present elements
+ordered via rows and columns.  It may also be used to present
+tree-structured information if the nodes of the trees can be said to
+contain multiple "columns".  Individual elements of an #AtkTable are
+typically referred to as "cells", and these cells are exposed by
+#AtkTable as child #AtkObjects of the #AtkTable.  Both row/column and
+child-index-based access to these children is provided.
+</para>
+<para>
+Children of #AtkTable are frequently "lightweight" objects, that is,
+they may not have backing widgets in the host UI toolkit.  They are
+therefore often transient.
+</para>
+<para>
+Since tables are often very complex, #AtkTable includes provision for
+offering simplified summary information, as well as row and column
+headers and captions.  Headers and captions are #AtkObjects which may
+implement other interfaces (#AtkText, #AtkImage, etc.) as appropriate.
+#AtkTable summaries may themselves be (simplified) #AtkTables, etc.
 </para>
-
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#AtkObject, #ATK_STATE_TRANSIENT
 </para>
 
 <!-- ##### STRUCT AtkTable ##### -->
diff --git a/docs/tmpl/atktext.sgml b/docs/tmpl/atktext.sgml
index 2d14994..981cc01 100644
--- a/docs/tmpl/atktext.sgml
+++ b/docs/tmpl/atktext.sgml
@@ -2,11 +2,28 @@
 AtkText
 
 <!-- ##### SECTION Short_Description ##### -->
-
+ATK Interface provided by components with text content.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#AtkText should be implemented by #AtkObjects on behalf of widgets that
+have text content which is either attributed or otherwise non-trivial.
+#AtkObjects whose text content is simple, unattributed, and very brief
+may expose that content via #atk_object_get_name instead; however if the
+text is editable, multi-line, typically longer than three or four words,
+attributed, selectable, or if the object already uses the 'name' ATK
+property for other information, the #AtkText interface should be used
+to expose the text content.  In the case of editable text content,
+#AtkEditableText (a subtype of the #AtkText interface) should be
+implemented instead.
+</para>
+<para>
+#AtkText provides not only traversal facilities and change notification
+for text content, but also caret tracking and glyph bounding box
+calculations.  Note that the text strings are exposed as UTF-8, and are
+therefore potentially multi-byte, and caret-to-byte offset mapping makes
+no assumptions about the character length; also bounding box
+glyph-to-offset mapping may be complex for languages which use ligatures.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/tmpl/atkvalue.sgml b/docs/tmpl/atkvalue.sgml
index 0dc4e18..8f244b2 100644
--- a/docs/tmpl/atkvalue.sgml
+++ b/docs/tmpl/atkvalue.sgml
@@ -2,11 +2,17 @@
 AtkValue
 
 <!-- ##### SECTION Short_Description ##### -->
-
-
+ATK Interface implemented by valuators and components which display or
+select a value from a bounded range of values.
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#AtkValue should be implemented for components which either display a
+value from a bounded range, or which allow the user to specify a value
+from a bounded range, or both.  For instance, most sliders and range
+controls, as well as dials, should have #AtkObject representations which
+implement #AtkValue on the component's behalf.  #AtKValues may be
+read-only, in which case attempts to alter the value return FALSE to
+indicate failure.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->