diff options
author | Bill Haneman <billh@src.gnome.org> | 2002-01-30 15:42:42 +0000 |
---|---|---|
committer | Bill Haneman <billh@src.gnome.org> | 2002-01-30 15:42:42 +0000 |
commit | 8ccad4587d46ce100e104a3e312e3a2b74e95775 (patch) | |
tree | d89e98e254b9a0dfaf29316618d32e58e8e4b51c | |
parent | f1bd024727fceb061d45c5eb6dc079a107c9356a (diff) | |
download | atk-ATK_0_11.tar.gz |
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").
-rw-r--r-- | ChangeLog | 17 | ||||
-rw-r--r-- | docs/tmpl/atkaction.sgml | 32 | ||||
-rw-r--r-- | docs/tmpl/atkcomponent.sgml | 16 | ||||
-rw-r--r-- | docs/tmpl/atkeditabletext.sgml | 13 | ||||
-rw-r--r-- | docs/tmpl/atkimage.sgml | 17 | ||||
-rw-r--r-- | docs/tmpl/atkobject.sgml | 34 | ||||
-rw-r--r-- | docs/tmpl/atkselection.sgml | 17 | ||||
-rw-r--r-- | docs/tmpl/atktable.sgml | 26 | ||||
-rw-r--r-- | docs/tmpl/atktext.sgml | 21 | ||||
-rw-r--r-- | docs/tmpl/atkvalue.sgml | 12 |
10 files changed, 173 insertions, 32 deletions
@@ -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 ##### --> |