+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.
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>
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 ##### -->
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 ##### -->
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 ##### -->
<!-- ##### 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 ##### -->
<!-- ##### 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:
<!-- ##### 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:
<!-- ##### 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:
<!-- ##### 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 ##### -->
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 ##### -->
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 ##### -->
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 ##### -->
projects / platform / upstream / atk.git / commitdiff