From 8ccad4587d46ce100e104a3e312e3a2b74e95775 Mon Sep 17 00:00:00 2001 From: Bill Haneman Date: Wed, 30 Jan 2002 15:42:42 +0000 Subject: Added descriptive documentation of the ATK interfaces, primarily 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"). --- ChangeLog | 17 +++++++++++++++++ docs/tmpl/atkaction.sgml | 32 +++++++++++++++++++++++++++++--- docs/tmpl/atkcomponent.sgml | 16 +++++++++++++--- docs/tmpl/atkeditabletext.sgml | 13 +++++++++---- docs/tmpl/atkimage.sgml | 17 ++++++++++++++--- docs/tmpl/atkobject.sgml | 34 ++++++++++++++++++++++++++++------ docs/tmpl/atkselection.sgml | 17 +++++++++++++---- docs/tmpl/atktable.sgml | 26 ++++++++++++++++++++++---- docs/tmpl/atktext.sgml | 21 +++++++++++++++++++-- docs/tmpl/atkvalue.sgml | 12 +++++++++--- 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 + + * 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 * 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 - +The ATK interface provided by UI components which the user can +activate/interact with, - +#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. + + +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. + + +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. + + +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. - 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 - - +ATK Interface provided by UI components which occupy a physical area on +the screen. - +#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. + + +A possible exception might be textual information with a transparent +background, in which case text glyph bounding box information is +provided by #AtkText. 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 - - +ATK Interface implemented by components containing user-editable text content. - +#AtkEditableText should be implemented by UI components which contain +text which the user can edit, via the #AtkObject corresponding to that +component (see #AtkObject). + + +#AtkEditableText is a subclass of #AtkText, and as such, an object which +implements #AtkEditableText is by definition an #AtkText implementor as well. - +#AtkText 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 - - +ATK Interface implemented by components which expose image or pixmap +content on-screen. - +#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. + + +#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. 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 +The base object class for the Accessibility Toolkit API. - +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. + +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. - - +See also: #AtkObjectFactory, #AtkRegistry. +( GTK+ users see also #GtkAccessible). @@ -29,7 +45,9 @@ AtkObject - +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. @ATK_ROLE_INVALID: @@ -114,7 +132,9 @@ AtkObject - +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. @ATK_LAYER_INVALID: @@ -133,7 +153,9 @@ AtkObject - +This interface provides an alternative means of obtaining AtkObjects +from a GOBject instance, and for querying whether a GObject instance +provides ATK functionality. @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 - +ATK Interface implemented by container objects whose #AtkObject children +can be selected. - +#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. + + +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. - - +#AtkText 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 - +ATK Interface implemented for UI components which contain tabular or +row/column information. - +#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. + + +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. + + +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. - - +#AtkObject, #ATK_STATE_TRANSIENT 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 - +ATK Interface provided by components with text content. - +#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. + + +#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. 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 - - +ATK Interface implemented by valuators and components which display or +select a value from a bounded range of values. - +#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. -- cgit v1.2.1