Structures

The AtkAction interface should be supported by any object that can perform one or more actions. The interface provides the standard mechanism for an assistive technology to determine what those actions are as well as tell the object to perform them. Any object that can be manipulated should support this interface.

The ActionIfaceRef type acts as a lightweight Swift reference to an underlying AtkActionIface instance. It exposes methods that can operate on this data type through ActionIfaceProtocol conformance. Use ActionIfaceRef only as an unowned reference to an existing AtkActionIface instance.

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 AttributeRef type acts as a lightweight Swift reference to an underlying AtkAttribute instance. It exposes methods that can operate on this data type through AttributeProtocol conformance. Use AttributeRef only as an unowned reference to an existing 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 ActionRef type acts as a lightweight Swift reference to an underlying AtkAction instance. It exposes methods that can operate on this data type through ActionProtocol conformance. Use ActionRef only as an unowned reference to an existing AtkAction instance.

The AtkComponent interface should be supported by any object that is rendered on the screen. The interface provides the standard mechanism for an assistive technology to determine and set the graphical representation of an object.

The ComponentIfaceRef type acts as a lightweight Swift reference to an underlying AtkComponentIface instance. It exposes methods that can operate on this data type through ComponentIfaceProtocol conformance. Use ComponentIfaceRef only as an unowned reference to an existing AtkComponentIface 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 ComponentRef type acts as a lightweight Swift reference to an underlying AtkComponent instance. It exposes methods that can operate on this data type through ComponentProtocol conformance. Use ComponentRef only as an unowned reference to an existing AtkComponent instance.

The DocumentIfaceRef type acts as a lightweight Swift reference to an underlying AtkDocumentIface instance. It exposes methods that can operate on this data type through DocumentIfaceProtocol conformance. Use DocumentIfaceRef only as an unowned reference to an existing AtkDocumentIface 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 DocumentRef type acts as a lightweight Swift reference to an underlying AtkDocument instance. It exposes methods that can operate on this data type through DocumentProtocol conformance. Use DocumentRef only as an unowned reference to an existing AtkDocument instance.

The EditableTextIfaceRef type acts as a lightweight Swift reference to an underlying AtkEditableTextIface instance. It exposes methods that can operate on this data type through EditableTextIfaceProtocol conformance. Use EditableTextIfaceRef only as an unowned reference to an existing AtkEditableTextIface 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 EditableTextRef type acts as a lightweight Swift reference to an underlying AtkEditableText instance. It exposes methods that can operate on this data type through EditableTextProtocol conformance. Use EditableTextRef only as an unowned reference to an existing AtkEditableText instance.

The GObjectAccessibleClassRef type acts as a lightweight Swift reference to an underlying AtkGObjectAccessibleClass instance. It exposes methods that can operate on this data type through GObjectAccessibleClassProtocol conformance. Use GObjectAccessibleClassRef only as an unowned reference to an existing AtkGObjectAccessibleClass 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 GObjectAccessibleRef type acts as a lightweight Swift reference to an underlying AtkGObjectAccessible instance. It exposes methods that can operate on this data type through GObjectAccessibleProtocol conformance. Use GObjectAccessibleRef only as an unowned reference to an existing AtkGObjectAccessible instance.

The HyperlinkClassRef type acts as a lightweight Swift reference to an underlying AtkHyperlinkClass instance. It exposes methods that can operate on this data type through HyperlinkClassProtocol conformance. Use HyperlinkClassRef only as an unowned reference to an existing AtkHyperlinkClass instance.

The HyperlinkImplIfaceRef type acts as a lightweight Swift reference to an underlying AtkHyperlinkImplIface instance. It exposes methods that can operate on this data type through HyperlinkImplIfaceProtocol conformance. Use HyperlinkImplIfaceRef only as an unowned reference to an existing AtkHyperlinkImplIface instance.

The HypertextIfaceRef type acts as a lightweight Swift reference to an underlying AtkHypertextIface instance. It exposes methods that can operate on this data type through HypertextIfaceProtocol conformance. Use HypertextIfaceRef only as an unowned reference to an existing AtkHypertextIface 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 HyperlinkRef type acts as a lightweight Swift reference to an underlying AtkHyperlink instance. It exposes methods that can operate on this data type through HyperlinkProtocol conformance. Use HyperlinkRef only as an unowned reference to an existing 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 HyperlinkImplRef type acts as a lightweight Swift reference to an underlying AtkHyperlinkImpl instance. It exposes methods that can operate on this data type through HyperlinkImplProtocol conformance. Use HyperlinkImplRef only as an unowned reference to an existing 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 HypertextRef type acts as a lightweight Swift reference to an underlying AtkHypertext instance. It exposes methods that can operate on this data type through HypertextProtocol conformance. Use HypertextRef only as an unowned reference to an existing AtkHypertext instance.

The ImageIfaceRef type acts as a lightweight Swift reference to an underlying AtkImageIface instance. It exposes methods that can operate on this data type through ImageIfaceProtocol conformance. Use ImageIfaceRef only as an unowned reference to an existing AtkImageIface instance.

The ImplementorRef type acts as a lightweight Swift reference to an underlying AtkImplementor instance. It exposes methods that can operate on this data type through ImplementorProtocol conformance. Use ImplementorRef only as an unowned reference to an existing 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 ImageRef type acts as a lightweight Swift reference to an underlying AtkImage instance. It exposes methods that can operate on this data type through ImageProtocol conformance. Use ImageRef only as an unowned reference to an existing AtkImage instance.

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

The ImplementorIfaceRef type acts as a lightweight Swift reference to an underlying AtkImplementorIface instance. It exposes methods that can operate on this data type through ImplementorIfaceProtocol conformance. Use ImplementorIfaceRef only as an unowned reference to an existing AtkImplementorIface instance.

Encapsulates information about a key event.

The KeyEventStructRef type acts as a lightweight Swift reference to an underlying AtkKeyEventStruct instance. It exposes methods that can operate on this data type through KeyEventStructProtocol conformance. Use KeyEventStructRef only as an unowned reference to an existing AtkKeyEventStruct instance.

Usage of AtkMisc is deprecated since 2.12 and heavily discouraged.

The MiscClassRef type acts as a lightweight Swift reference to an underlying AtkMiscClass instance. It exposes methods that can operate on this data type through MiscClassProtocol conformance. Use MiscClassRef only as an unowned reference to an existing AtkMiscClass instance.

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

The MiscRef type acts as a lightweight Swift reference to an underlying AtkMisc instance. It exposes methods that can operate on this data type through MiscProtocol conformance. Use MiscRef only as an unowned reference to an existing AtkMisc instance.

The NoOpObjectClassRef type acts as a lightweight Swift reference to an underlying AtkNoOpObjectClass instance. It exposes methods that can operate on this data type through NoOpObjectClassProtocol conformance. Use NoOpObjectClassRef only as an unowned reference to an existing AtkNoOpObjectClass instance.

The NoOpObjectFactoryClassRef type acts as a lightweight Swift reference to an underlying AtkNoOpObjectFactoryClass instance. It exposes methods that can operate on this data type through NoOpObjectFactoryClassProtocol conformance. Use NoOpObjectFactoryClassRef only as an unowned reference to an existing AtkNoOpObjectFactoryClass 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 NoOpObjectRef type acts as a lightweight Swift reference to an underlying AtkNoOpObject instance. It exposes methods that can operate on this data type through NoOpObjectProtocol conformance. Use NoOpObjectRef only as an unowned reference to an existing 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 NoOpObjectFactoryRef type acts as a lightweight Swift reference to an underlying AtkNoOpObjectFactory instance. It exposes methods that can operate on this data type through NoOpObjectFactoryProtocol conformance. Use NoOpObjectFactoryRef only as an unowned reference to an existing AtkNoOpObjectFactory instance.

The ObjectClassRef type acts as a lightweight Swift reference to an underlying AtkObjectClass instance. It exposes methods that can operate on this data type through ObjectClassProtocol conformance. Use ObjectClassRef only as an unowned reference to an existing AtkObjectClass instance.

The ObjectFactoryClassRef type acts as a lightweight Swift reference to an underlying AtkObjectFactoryClass instance. It exposes methods that can operate on this data type through ObjectFactoryClassProtocol conformance. Use ObjectFactoryClassRef only as an unowned reference to an existing AtkObjectFactoryClass 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 ObjectRef type acts as a lightweight Swift reference to an underlying AtkObject instance. It exposes methods that can operate on this data type through ObjectProtocol conformance. Use ObjectRef only as an unowned reference to an existing 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 ObjectFactoryRef type acts as a lightweight Swift reference to an underlying AtkObjectFactory instance. It exposes methods that can operate on this data type through ObjectFactoryProtocol conformance. Use ObjectFactoryRef only as an unowned reference to an existing AtkObjectFactory instance.

The PlugClassRef type acts as a lightweight Swift reference to an underlying AtkPlugClass instance. It exposes methods that can operate on this data type through PlugClassProtocol conformance. Use PlugClassRef only as an unowned reference to an existing AtkPlugClass 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 PropertyValuesRef type acts as a lightweight Swift reference to an underlying AtkPropertyValues instance. It exposes methods that can operate on this data type through PropertyValuesProtocol conformance. Use PropertyValuesRef only as an unowned reference to an existing AtkPropertyValues instance.

See AtkSocket

The PlugRef type acts as a lightweight Swift reference to an underlying AtkPlug instance. It exposes methods that can operate on this data type through PlugProtocol conformance. Use PlugRef only as an unowned reference to an existing 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 RangeRef type acts as a lightweight Swift reference to an underlying AtkRange instance. It exposes methods that can operate on this data type through RangeProtocol conformance. Use RangeRef only as an unowned reference to an existing AtkRange instance.

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

The RectangleRef type acts as a lightweight Swift reference to an underlying AtkRectangle instance. It exposes methods that can operate on this data type through RectangleProtocol conformance. Use RectangleRef only as an unowned reference to an existing AtkRectangle instance.

The RegistryClassRef type acts as a lightweight Swift reference to an underlying AtkRegistryClass instance. It exposes methods that can operate on this data type through RegistryClassProtocol conformance. Use RegistryClassRef only as an unowned reference to an existing AtkRegistryClass instance.

The RelationClassRef type acts as a lightweight Swift reference to an underlying AtkRelationClass instance. It exposes methods that can operate on this data type through RelationClassProtocol conformance. Use RelationClassRef only as an unowned reference to an existing AtkRelationClass instance.

The RelationSetClassRef type acts as a lightweight Swift reference to an underlying AtkRelationSetClass instance. It exposes methods that can operate on this data type through RelationSetClassProtocol conformance. Use RelationSetClassRef only as an unowned reference to an existing AtkRelationSetClass 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 RegistryRef type acts as a lightweight Swift reference to an underlying AtkRegistry instance. It exposes methods that can operate on this data type through RegistryProtocol conformance. Use RegistryRef only as an unowned reference to an existing 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 RelationRef type acts as a lightweight Swift reference to an underlying AtkRelation instance. It exposes methods that can operate on this data type through RelationProtocol conformance. Use RelationRef only as an unowned reference to an existing 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 RelationSetRef type acts as a lightweight Swift reference to an underlying AtkRelationSet instance. It exposes methods that can operate on this data type through RelationSetProtocol conformance. Use RelationSetRef only as an unowned reference to an existing AtkRelationSet instance.

The SelectionIfaceRef type acts as a lightweight Swift reference to an underlying AtkSelectionIface instance. It exposes methods that can operate on this data type through SelectionIfaceProtocol conformance. Use SelectionIfaceRef only as an unowned reference to an existing AtkSelectionIface instance.

The SocketClassRef type acts as a lightweight Swift reference to an underlying AtkSocketClass instance. It exposes methods that can operate on this data type through SocketClassProtocol conformance. Use SocketClassRef only as an unowned reference to an existing AtkSocketClass instance.

The StateSetClassRef type acts as a lightweight Swift reference to an underlying AtkStateSetClass instance. It exposes methods that can operate on this data type through StateSetClassProtocol conformance. Use StateSetClassRef only as an unowned reference to an existing AtkStateSetClass instance.

The StreamableContentIfaceRef type acts as a lightweight Swift reference to an underlying AtkStreamableContentIface instance. It exposes methods that can operate on this data type through StreamableContentIfaceProtocol conformance. Use StreamableContentIfaceRef only as an unowned reference to an existing AtkStreamableContentIface 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 SelectionRef type acts as a lightweight Swift reference to an underlying AtkSelection instance. It exposes methods that can operate on this data type through SelectionProtocol conformance. Use SelectionRef only as an unowned reference to an existing 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 StreamableContentRef type acts as a lightweight Swift reference to an underlying AtkStreamableContent instance. It exposes methods that can operate on this data type through StreamableContentProtocol conformance. Use StreamableContentRef only as an unowned reference to an existing 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 SocketRef type acts as a lightweight Swift reference to an underlying AtkSocket instance. It exposes methods that can operate on this data type through SocketProtocol conformance. Use SocketRef only as an unowned reference to an existing 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 StateSetRef type acts as a lightweight Swift reference to an underlying AtkStateSet instance. It exposes methods that can operate on this data type through StateSetProtocol conformance. Use StateSetRef only as an unowned reference to an existing AtkStateSet instance.

AtkTableCell is an interface for cells inside an AtkTable.

The TableCellIfaceRef type acts as a lightweight Swift reference to an underlying AtkTableCellIface instance. It exposes methods that can operate on this data type through TableCellIfaceProtocol conformance. Use TableCellIfaceRef only as an unowned reference to an existing AtkTableCellIface instance.

The TableIfaceRef type acts as a lightweight Swift reference to an underlying AtkTableIface instance. It exposes methods that can operate on this data type through TableIfaceProtocol conformance. Use TableIfaceRef only as an unowned reference to an existing AtkTableIface instance.

The TextIfaceRef type acts as a lightweight Swift reference to an underlying AtkTextIface instance. It exposes methods that can operate on this data type through TextIfaceProtocol conformance. Use TextIfaceRef only as an unowned reference to an existing AtkTextIface instance.

A structure used to describe a text range.

The TextRangeRef type acts as a lightweight Swift reference to an underlying AtkTextRange instance. It exposes methods that can operate on this data type through TextRangeProtocol conformance. Use TextRangeRef only as an unowned reference to an existing AtkTextRange instance.

A structure used to store a rectangle used by AtkText.

The TextRectangleRef type acts as a lightweight Swift reference to an underlying AtkTextRectangle instance. It exposes methods that can operate on this data type through TextRectangleProtocol conformance. Use TextRectangleRef only as an unowned reference to an existing 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 TableRef type acts as a lightweight Swift reference to an underlying AtkTable instance. It exposes methods that can operate on this data type through TableProtocol conformance. Use TableRef only as an unowned reference to an existing 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 TableCellRef type acts as a lightweight Swift reference to an underlying AtkTableCell instance. It exposes methods that can operate on this data type through TableCellProtocol conformance. Use TableCellRef only as an unowned reference to an existing 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 TextRef type acts as a lightweight Swift reference to an underlying AtkText instance. It exposes methods that can operate on this data type through TextProtocol conformance. Use TextRef only as an unowned reference to an existing AtkText instance.

The UtilClassRef type acts as a lightweight Swift reference to an underlying AtkUtilClass instance. It exposes methods that can operate on this data type through UtilClassProtocol conformance. Use UtilClassRef only as an unowned reference to an existing AtkUtilClass 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 UtilRef type acts as a lightweight Swift reference to an underlying AtkUtil instance. It exposes methods that can operate on this data type through UtilProtocol conformance. Use UtilRef only as an unowned reference to an existing AtkUtil instance.

The ValueIfaceRef type acts as a lightweight Swift reference to an underlying AtkValueIface instance. It exposes methods that can operate on this data type through ValueIfaceProtocol conformance. Use ValueIfaceRef only as an unowned reference to an existing AtkValueIface 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 ValueRef type acts as a lightweight Swift reference to an underlying AtkValue instance. It exposes methods that can operate on this data type through ValueProtocol conformance. Use ValueRef only as an unowned reference to an existing AtkValue instance.

The WindowIfaceRef type acts as a lightweight Swift reference to an underlying AtkWindowIface instance. It exposes methods that can operate on this data type through WindowIfaceProtocol conformance. Use WindowIfaceRef only as an unowned reference to an existing AtkWindowIface 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 WindowRef type acts as a lightweight Swift reference to an underlying AtkWindow instance. It exposes methods that can operate on this data type through WindowProtocol conformance. Use WindowRef only as an unowned reference to an existing AtkWindow instance.

Describes the type of link