Classes

AtkAttribute is a string name/value pair representing a generic attribute. This can be used to expose additional information from an accessible object as a whole (see atk_object_get_attributes()) or an document (see atk_document_get_attributes()). In the case of text attributes (see atk_text_get_default_attributes()), AtkTextAttribute enum defines all the possible text attribute names. You can use atk_text_attribute_get_name() to get the string name from the enum value. See also atk_text_attribute_for_name() and atk_text_attribute_get_value() for more information.

A string name/value pair representing a generic attribute.

The Attribute type acts as an owner of an underlying AtkAttribute instance. It provides the methods that can operate on this data type through AttributeProtocol conformance. Use Attribute as a strong reference or owner of a AtkAttribute instance.

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 text, etc.) or AtkValue (set value) then these actions should not be exposed by AtkAction as well.

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.

The Action type acts as an owner of an underlying AtkAction instance. It provides the methods that can operate on this data type through ActionProtocol conformance. Use Action as a strong reference or owner of a AtkAction instance.

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.

The Component type acts as an owner of an underlying AtkComponent instance. It provides the methods that can operate on this data type through ComponentProtocol conformance. Use Component as a strong reference or owner of a AtkComponent instance.

The AtkDocument interface should be supported by any object whose content is a representation or view of a document. The AtkDocument interface should appear on the toplevel container for the document content; however AtkDocument instances may be nested (i.e. an AtkDocument may be a descendant of another AtkDocument) in those cases where one document contains “embedded content” which can reasonably be considered a document in its own right.

The Document type acts as an owner of an underlying AtkDocument instance. It provides the methods that can operate on this data type through DocumentProtocol conformance. Use Document as a strong reference or owner of a AtkDocument instance.

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.

See also: AtkText

The EditableText type acts as an owner of an underlying AtkEditableText instance. It provides the methods that can operate on this data type through EditableTextProtocol conformance. Use EditableText as a strong reference or owner of a AtkEditableText instance.

This object class is derived from AtkObject. It can be used as a basis for implementing accessible objects for GObjects which are not derived from GtkWidget. One example of its use is in providing an accessible object for GnomeCanvasItem in the GAIL library.

The GObjectAccessible type acts as a reference-counted owner of an underlying AtkGObjectAccessible instance. It provides the methods that can operate on this data type through GObjectAccessibleProtocol conformance. Use GObjectAccessible as a strong reference or owner of a AtkGObjectAccessible instance.

An ATK object which encapsulates a link or set of links (for instance in the case of client-side image maps) in a hypertext document. It may implement the AtkAction interface. AtkHyperlink may also be used to refer to inline embedded content, since it allows specification of a start and end offset within the host AtkHypertext object.

The Hyperlink type acts as a reference-counted owner of an underlying AtkHyperlink instance. It provides the methods that can operate on this data type through HyperlinkProtocol conformance. Use Hyperlink as a strong reference or owner of a AtkHyperlink instance.

AtkHyperlinkImpl allows AtkObjects to refer to their associated AtkHyperlink instance, if one exists. AtkHyperlinkImpl differs from AtkHyperlink in that AtkHyperlinkImpl is an interface, whereas AtkHyperlink is a object type. The AtkHyperlinkImpl interface allows a client to query an AtkObject for the availability of an associated AtkHyperlink instance, and obtain that instance. It is thus particularly useful in cases where embedded content or inline content within a text object is present, since the embedding text object implements AtkHypertext and the inline/embedded objects are exposed as children which implement AtkHyperlinkImpl, in addition to their being obtainable via AtkHypertext:getLink followed by AtkHyperlink:getObject.

The AtkHyperlinkImpl interface should be supported by objects exposed within the hierarchy as children of an AtkHypertext container which correspond to “links” or embedded content within the text. HTML anchors are not, for instance, normally exposed this way, but embedded images and components which appear inline in the content of a text object are. The AtkHyperlinkIface interface allows a means of determining which children are hyperlinks in this sense of the word, and for obtaining their corresponding AtkHyperlink object, from which the embedding range, URI, etc. can be obtained.

To some extent this interface exists because, for historical reasons, AtkHyperlink was defined as an object type, not an interface. Thus, in order to interact with AtkObjects via AtkHyperlink semantics, a new interface was required.

The HyperlinkImpl type acts as an owner of an underlying AtkHyperlinkImpl instance. It provides the methods that can operate on this data type through HyperlinkImplProtocol conformance. Use HyperlinkImpl as a strong reference or owner of a AtkHyperlinkImpl instance.

An interface used for objects which implement linking between multiple resource or content locations, or multiple ‘markers’ within a single document. A Hypertext instance is associated with one or more Hyperlinks, which are associated with particular offsets within the Hypertext’s included content. While this interface is derived from Text, there is no requirement that Hypertext instances have textual content; they may implement Image as well, and Hyperlinks need not have non-zero text offsets.

The Hypertext type acts as an owner of an underlying AtkHypertext instance. It provides the methods that can operate on this data type through HypertextProtocol conformance. Use Hypertext as a strong reference or owner of a AtkHypertext instance.

The Implementor type acts as an owner of an underlying AtkImplementor instance. It provides the methods that can operate on this data type through ImplementorProtocol conformance. Use Implementor as a strong reference or owner of a AtkImplementor instance.

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.

The Image type acts as an owner of an underlying AtkImage instance. It provides the methods that can operate on this data type through ImageProtocol conformance. Use Image as a strong reference or owner of a AtkImage instance.

The AtkImplementor interface is implemented by objects for which AtkObject peers may be obtained via calls to iface->(ref_accessible)(implementor);

The ImplementorIface type acts as an owner of an underlying AtkImplementorIface instance. It provides the methods that can operate on this data type through ImplementorIfaceProtocol conformance. Use ImplementorIface as a strong reference or owner of a AtkImplementorIface instance.

Encapsulates information about a key event.

The KeyEventStruct type acts as an owner of an underlying AtkKeyEventStruct instance. It provides the methods that can operate on this data type through KeyEventStructProtocol conformance. Use KeyEventStruct as a strong reference or owner of a AtkKeyEventStruct instance.

A set of utility functions for thread locking. This interface and all his related methods are deprecated since 2.12.

The Misc type acts as a reference-counted owner of an underlying AtkMisc instance. It provides the methods that can operate on this data type through MiscProtocol conformance. Use Misc as a strong reference or owner of a AtkMisc instance.

An AtkNoOpObject is an AtkObject which purports to implement all ATK interfaces. It is the type of AtkObject which is created if an accessible object is requested for an object type for which no factory type is specified.

The NoOpObject type acts as a reference-counted owner of an underlying AtkNoOpObject instance. It provides the methods that can operate on this data type through NoOpObjectProtocol conformance. Use NoOpObject as a strong reference or owner of a AtkNoOpObject instance.

The AtkObjectFactory which creates an AtkNoOpObject. An instance of this is created by an AtkRegistry if no factory type has not been specified to create an accessible object of a particular type.

The NoOpObjectFactory type acts as a reference-counted owner of an underlying AtkNoOpObjectFactory instance. It provides the methods that can operate on this data type through NoOpObjectFactoryProtocol conformance. Use NoOpObjectFactory as a strong reference or owner of a AtkNoOpObjectFactory instance.

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).

The Object type acts as a reference-counted owner of an underlying AtkObject instance. It provides the methods that can operate on this data type through ObjectProtocol conformance. Use Object as a strong reference or owner of a AtkObject instance.

This class is the base object class for a factory used to create an accessible object for a specific GType. The function atk_registry_set_factory_type() is normally called to store in the registry the factory type to be used to create an accessible of a particular GType.

The ObjectFactory type acts as a reference-counted owner of an underlying AtkObjectFactory instance. It provides the methods that can operate on this data type through ObjectFactoryProtocol conformance. Use ObjectFactory as a strong reference or owner of a AtkObjectFactory instance.

Note: old_value field of AtkPropertyValues will not contain a valid value. This is a field defined with the purpose of contain the previous value of the property, but is not used anymore.

The PropertyValues type acts as an owner of an underlying AtkPropertyValues instance. It provides the methods that can operate on this data type through PropertyValuesProtocol conformance. Use PropertyValues as a strong reference or owner of a AtkPropertyValues instance.

See AtkSocket

The Plug type acts as a reference-counted owner of an underlying AtkPlug instance. It provides the methods that can operate on this data type through PlugProtocol conformance. Use Plug as a strong reference or owner of a AtkPlug instance.

AtkRange are used on AtkValue, in order to represent the full range of a given component (for example an slider or a range control), or to define each individual subrange this full range is splitted if available. See AtkValue documentation for further details.

The Range type acts as an owner of an underlying AtkRange instance. It provides the methods that can operate on this data type through RangeProtocol conformance. Use Range as a strong reference or owner of a AtkRange instance.

A data structure for holding a rectangle. Those coordinates are relative to the component top-level parent.

The Rectangle type acts as an owner of an underlying AtkRectangle instance. It provides the methods that can operate on this data type through RectangleProtocol conformance. Use Rectangle as a strong reference or owner of a AtkRectangle instance.

The AtkRegistry is normally used to create appropriate ATK “peers” for user interface components. Application developers usually need only interact with the AtkRegistry by associating appropriate ATK implementation classes with GObject classes via the atk_registry_set_factory_type call, passing the appropriate GType for application custom widget classes.

The Registry type acts as a reference-counted owner of an underlying AtkRegistry instance. It provides the methods that can operate on this data type through RegistryProtocol conformance. Use Registry as a strong reference or owner of a AtkRegistry instance.

An AtkRelation describes a relation between an object and one or more other objects. The actual relations that an object has with other objects are defined as an AtkRelationSet, which is a set of AtkRelations.

The Relation type acts as a reference-counted owner of an underlying AtkRelation instance. It provides the methods that can operate on this data type through RelationProtocol conformance. Use Relation as a strong reference or owner of a AtkRelation instance.

The AtkRelationSet held by an object establishes its relationships with objects beyond the normal “parent/child” hierarchical relationships that all user interface objects have. AtkRelationSets establish whether objects are labelled or controlled by other components, share group membership with other components (for instance within a radio-button group), or share content which “flows” between them, among other types of possible relationships.

The RelationSet type acts as a reference-counted owner of an underlying AtkRelationSet instance. It provides the methods that can operate on this data type through RelationSetProtocol conformance. Use RelationSet as a strong reference or owner of a AtkRelationSet instance.

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.

The Selection type acts as an owner of an underlying AtkSelection instance. It provides the methods that can operate on this data type through SelectionProtocol conformance. Use Selection as a strong reference or owner of a AtkSelection instance.

An interface whereby an object allows its backing content to be streamed to clients. Typical implementors would be images or icons, HTML content, or multimedia display/rendering widgets.

Negotiation of content type is allowed. Clients may examine the backing data and transform, convert, or parse the content in order to present it in an alternate form to end-users.

The AtkStreamableContent interface is particularly useful for saving, printing, or post-processing entire documents, or for persisting alternate views of a document. If document content itself is being serialized, stored, or converted, then use of the AtkStreamableContent interface can help address performance issues. Unlike most ATK interfaces, this interface is not strongly tied to the current user-agent view of the a particular document, but may in some cases give access to the underlying model data.

The StreamableContent type acts as an owner of an underlying AtkStreamableContent instance. It provides the methods that can operate on this data type through StreamableContentProtocol conformance. Use StreamableContent as a strong reference or owner of a AtkStreamableContent instance.

Together with AtkPlug, AtkSocket provides the ability to embed accessibles from one process into another in a fashion that is transparent to assistive technologies. AtkSocket works as the container of AtkPlug, embedding it using the method atk_socket_embed(). Any accessible contained in the AtkPlug will appear to the assistive technologies as being inside the application that created the AtkSocket.

The communication between a AtkSocket and a AtkPlug is done by the IPC layer of the accessibility framework, normally implemented by the D-Bus based implementation of AT-SPI (at-spi2). If that is the case, at-spi-atk2 is the responsible to implement the abstract methods atk_plug_get_id() and atk_socket_embed(), so an ATK implementor shouldn’t reimplement them. The process that contains the AtkPlug is responsible to send the ID returned by atk_plug_id() to the process that contains the AtkSocket, so it could call the method atk_socket_embed() in order to embed it.

For the same reasons, an implementor doesn’t need to implement atk_object_get_n_accessible_children() and atk_object_ref_accessible_child(). All the logic related to those functions will be implemented by the IPC layer.

The Socket type acts as a reference-counted owner of an underlying AtkSocket instance. It provides the methods that can operate on this data type through SocketProtocol conformance. Use Socket as a strong reference or owner of a AtkSocket instance.

An AtkStateSet is a read-only representation of the full set of AtkStates that apply to an object at a given time. This set is not meant to be modified, but rather created when atk_object_ref_state_set() is called.

The StateSet type acts as a reference-counted owner of an underlying AtkStateSet instance. It provides the methods that can operate on this data type through StateSetProtocol conformance. Use StateSet as a strong reference or owner of a AtkStateSet instance.

A structure used to describe a text range.

The TextRange type acts as an owner of an underlying AtkTextRange instance. It provides the methods that can operate on this data type through TextRangeProtocol conformance. Use TextRange as a strong reference or owner of a AtkTextRange instance.

A structure used to store a rectangle used by AtkText.

The TextRectangle type acts as an owner of an underlying AtkTextRectangle instance. It provides the methods that can operate on this data type through TextRectangleProtocol conformance. Use TextRectangle as a strong reference or owner of a AtkTextRectangle instance.

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”. Those cells should implement the interface AtkTableCell, but Atk doesn’t require them to be direct children of the current AtkTable. They can be grand-children, grand-grand-children etc. AtkTable provides the API needed to get a individual cell based on the row and column numbers.

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.

Note for implementors: in the past, AtkTable required that all the cells should be direct children of AtkTable, and provided some index based methods to request the cells. The practice showed that that forcing made AtkTable implementation complex, and hard to expose other kind of children, like rows or captions. Right now, index-based methods are deprecated.

The Table type acts as an owner of an underlying AtkTable instance. It provides the methods that can operate on this data type through TableProtocol conformance. Use Table as a strong reference or owner of a AtkTable instance.

Being AtkTable a component which present elements ordered via rows and columns, an AtkTableCell is the interface which each of those elements, so “cells” should implement.

See also AtkTable.

The TableCell type acts as a reference-counted owner of an underlying AtkTableCell instance. It provides the methods that can operate on this data type through TableCellProtocol conformance. Use TableCell as a strong reference or owner of a AtkTableCell instance.

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.

The Text type acts as an owner of an underlying AtkText instance. It provides the methods that can operate on this data type through TextProtocol conformance. Use Text as a strong reference or owner of a AtkText instance.

A set of ATK utility functions which are used to support event registration of various types, and obtaining the ‘root’ accessible of a process and information about the current ATK implementation and toolkit version.

The Util type acts as a reference-counted owner of an underlying AtkUtil instance. It provides the methods that can operate on this data type through UtilProtocol conformance. Use Util as a strong reference or owner of a AtkUtil instance.

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 would fail.

<refsect1 id=“current-value-text”> <title>On the subject of current value text</title> <para> In addition to providing the current value, implementors can optionally provide an end-user-consumable textual description associated with this value. This description should be included when the numeric value fails to convey the full, on-screen representation seen by users. </para>

<example> <title>Password strength</title> A password strength meter whose value changes as the user types their new password. Red is used for values less than 4.0, yellow for values between 4.0 and 7.0, and green for values greater than 7.0. In this instance, value text should be provided by the implementor. Appropriate value text would be “weak”, “acceptable,” and “strong” respectively. </example>

A level bar whose value changes to reflect the battery charge. The color remains the same regardless of the charge and there is no on-screen text reflecting the fullness of the battery. In this case, because the position within the bar is the only indication the user has of the current charge, value text should not be provided by the implementor.

<refsect2 id=“implementor-notes”> <title>Implementor Notes</title> <para> Implementors should bear in mind that assistive technologies will likely prefer the value text provided over the numeric value when presenting a widget’s value. As a result, strings not intended for end users should not be exposed in the value text, and strings which are exposed should be localized. In the case of widgets which display value text on screen, for instance through a separate label in close proximity to the value-displaying widget, it is still expected that implementors will expose the value text using the above API. </para>

<para> AtkValue should NOT be implemented for widgets whose displayed value is not reflective of a meaningful amount. For instance, a progress pulse indicator whose value alternates between 0.0 and 1.0 to indicate that some process is still taking place should not implement AtkValue because the current value does not reflect progress towards completion. </para> </refsect2> </refsect1>

<refsect1 id=“ranges”> <title>On the subject of ranges</title> <para> In addition to providing the minimum and maximum values, implementors can optionally provide details about subranges associated with the widget. These details should be provided by the implementor when both of the following are communicated visually to the end user: </para> <itemizedlist> <listitem>The existence of distinct ranges such as “weak”, “acceptable”, and “strong” indicated by color, bar tick marks, and/or on-screen text.</listitem> <listitem>Where the current value stands within a given subrange, for instance illustrating progression from very “weak” towards nearly “acceptable” through changes in shade and/or position on the bar within the “weak” subrange.</listitem> </itemizedlist> <para> If both of the above do not apply to the widget, it should be sufficient to expose the numeric value, along with the value text if appropriate, to make the widget accessible. </para>

<refsect2 id=“ranges-implementor-notes”> <title>Implementor Notes</title> <para> If providing subrange details is deemed necessary, all possible values of the widget are expected to fall within one of the subranges defined by the implementor. </para> </refsect2> </refsect1>

<refsect1 id=“localization”> <title>On the subject of localization of end-user-consumable text values</title> <para> Because value text and subrange descriptors are human-consumable, implementors are expected to provide localized strings which can be directly presented to end users via their assistive technology. In order to simplify this for implementors, implementors can use atk_value_type_get_localized_name() with the following already-localized constants for commonly-needed values can be used: </para>

<itemizedlist> <listitem>ATK_VALUE_VERY_WEAK</listitem> <listitem>ATK_VALUE_WEAK</listitem> <listitem>ATK_VALUE_ACCEPTABLE</listitem> <listitem>ATK_VALUE_STRONG</listitem> <listitem>ATK_VALUE_VERY_STRONG</listitem> <listitem>ATK_VALUE_VERY_LOW</listitem> <listitem>ATK_VALUE_LOW</listitem> <listitem>ATK_VALUE_MEDIUM</listitem> <listitem>ATK_VALUE_HIGH</listitem> <listitem>ATK_VALUE_VERY_HIGH</listitem> <listitem>ATK_VALUE_VERY_BAD</listitem> <listitem>ATK_VALUE_BAD</listitem> <listitem>ATK_VALUE_GOOD</listitem> <listitem>ATK_VALUE_VERY_GOOD</listitem> <listitem>ATK_VALUE_BEST</listitem> <listitem>ATK_VALUE_SUBSUBOPTIMAL</listitem> <listitem>ATK_VALUE_SUBOPTIMAL</listitem> <listitem>ATK_VALUE_OPTIMAL</listitem> </itemizedlist> <para> Proposals for additional constants, along with their use cases, should be submitted to the GNOME Accessibility Team. </para> </refsect1>

<refsect1 id=“changes”> <title>On the subject of changes</title> <para> Note that if there is a textual description associated with the new numeric value, that description should be included regardless of whether or not it has also changed. </para> </refsect1>

The Value type acts as an owner of an underlying AtkValue instance. It provides the methods that can operate on this data type through ValueProtocol conformance. Use Value as a strong reference or owner of a AtkValue instance.

AtkWindow should be implemented by the UI elements that represent a top-level window, such as the main window of an application or dialog.

The Window type acts as a reference-counted owner of an underlying AtkWindow instance. It provides the methods that can operate on this data type through WindowProtocol conformance. Use Window as a strong reference or owner of a AtkWindow instance.