atk.c.types

This is a singly-linked list (a #GSList) of #AtkAttribute. It is used by [atk.text.Text.getRunAttributes], [atk.text.Text.getDefaultAttributes], [atk.editable_text.EditableText.setRunAttributes], [atk.document.Document.getAttributes] and [atk.object.ObjectWrap.getAttributes]

An AtkState describes a single state of an object.

An AtkState describes a single state of an object. The full set of states that apply to an object at a given time are contained in its #AtkStateSet.

See id@atk_object_ref_state_set and id@atk_object_notify_state_change

Specifies how xy coordinates are to be interpreted. Used by functions such as [atk.component.Component.getPosition] and [atk.text.Text.getCharacterExtents]

Describes the type of link

Specifies the type of a keyboard evemt.

Describes the layer of a component

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.

Enumeration used to indicate a type of live region and how assertive it should be in terms of speaking notifications. Currently, this is only used for "notification" events, but it may be used for additional purposes in the future.

Describes the type of the relation

Describes the role of an object

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.types.Role.LastDefined] is not necessarily an error.

Specifies where an object should be placed on the screen when using scroll_to.

The possible types of states of an object

Describes the text attributes supported

Text boundary types used for specifying boundaries for regions of text. This enumeration is deprecated since 2.9.4 and should not be used. Use AtkTextGranularity with #atk_text_get_string_at_offset instead.

Describes the type of clipping required.

Text granularity types used for specifying the granularity of the region of text we are interested in.

Default types for a given value. Those are defined in order to easily get localized strings to describe a given value or a given subrange, using [atk.global.valueTypeGetLocalizedName].

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

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.ObjectWrap.getAttributes]) or an document (see [atk.document.Document.getAttributes]). In the case of text attributes (see [atk.text.Text.getDefaultAttributes]), #AtkTextAttribute enum defines all the possible text attribute names. You can use [atk.global.textAttributeGetName] to get the string name from the enum value. See also [atk.global.textAttributeForName] and [atk.global.textAttributeGetValue] for more information.

A string name/value pair representing a generic attribute.

The ATK interface provided by UI components which occupy a physical area on the screen. which the user can activate/interact with.

#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 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 ATK interface which represents the toplevel container for document content.

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

See iface@AtkText

This object class is derived from AtkObject and can be used as a basis implementing accessible objects.

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.

An ATK object which encapsulates a link or set of links in a hypertext document.

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.

A queryable interface which allows AtkHyperlink instances associated with an AtkObject to be obtained. AtkHyperlinkImpl corresponds to AT-SPI's Hyperlink interface, and differs from AtkHyperlink in that AtkHyperlink is an object type, rather than an interface, and thus cannot be directly queried. FTW

The ATK interface which provides standard mechanism for manipulating hyperlinks.

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

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

Encapsulates information about a key event.

A set of ATK utility functions for thread locking

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

Usage of AtkMisc is deprecated since 2.12 and heavily discouraged.

An AtkObject which purports to implement all ATK interfaces.

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 AtkObjectFactory which creates an AtkNoOpObject.

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 base object class for a factory used to create accessible objects for objects of a specific GType.

This class is the base object class for a factory used to create an accessible object for a specific GType. The function [atk.registry.Registry.setFactoryType] is normally called to store in the registry the factory type to be used to create an accessible of a particular GType.

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 class@AtkObjectFactory, class@AtkRegistry. (GTK+ users see also #GtkAccessible).

Toplevel for embedding into other processes

See class@AtkSocket

A given range or subrange, to be used with #AtkValue

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

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

An object used to store the GType of the factories used to create an accessible object for an object of a particular GType.

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.

An object used to describe a relation between a object and one or more other objects.

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.

A set of AtkRelations, normally the set of AtkRelations which an AtkObject has.

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

Container for AtkPlug objects from other processes

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.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.Plug.getId] and [atk.socket.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.Socket.embed] in order to embed it.

For the same reasons, an implementor doesn't need to implement [atk.object.ObjectWrap.getNAccessibleChildren] and [atk.object.ObjectWrap.refAccessibleChild]. All the logic related to those functions will be implemented by the IPC layer.

See class@AtkPlug

An AtkStateSet contains the states of an object.

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.ObjectWrap.refStateSet] is called.

The ATK interface which provides access to streamable content.

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 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". 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 ATK interface implemented for a cell inside a two-dimentional #AtkTable

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 iface@AtkTable

AtkTableCell is an interface for cells inside an #AtkTable.

The ATK interface implemented 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.

A structure used to describe a text range.

A structure used to store a rectangle used by AtkText.

This structure represents a single text selection within a document. This selection is defined by two points in the content, where each one is defined by an AtkObject supporting the AtkText interface and a character offset relative to it.

The end object must appear after the start object in the accessibility tree, i.e. the end object must be reachable from the start object by navigating forward (next, first child etc).

This struct also contains a @start_is_active boolean, to communicate if the start of the selection is the active point or not.

The active point corresponds to the user's focus or point of interest. The user moves the active point to expand or collapse the range. The anchor point is the other point of the range and typically remains constant. In most cases, anchor is the start of the range and active is the end. However, when selecting backwards (e.g. pressing shift+left arrow in a text field), the start of the range is the active point, as the user moves this to manipulate the selection.

A set of ATK utility functions for event and toolkit support.

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

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.

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.

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.

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.

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

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:

"acceptable", and "strong" indicated by color, bar tick marks, and/or on-screen text.</listitem>

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>

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.

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.

values</title>

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.global.valueTypeGetLocalizedName] with the following already-localized constants for commonly-needed values can be used:

Proposals for additional constants, along with their use cases, should be submitted to the GNOME Accessibility Team.

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.

The ATK Interface provided by UI components that represent a top-level window.

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

See class@AtkObject