Namespace

Atk – 1.0

The Accessibility toolkit

Version2.37
AuthorsGTK Development Team
LicenseLGPL-2.1-or-later
Websitehttps://www.gtk.org
Sourcehttps://gitlab.gnome.org/GNOME/atk/

Build

C headersatk/atk.h
pkg-config filesatk

Dependencies

GObject—2.0 The base type system library
Browse documentation
AT-SPI The Assistive Technology Service Provider Interface
Browse documentation

Additional documentation

Classes

GObjectAccessible

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.

Hyperlink

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.

Misc

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

NoOpObject

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.

NoOpObjectFactory

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.

Object

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.

ObjectFactory

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.

Plug

See AtkSocket.

Registry

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.

Relation

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.

RelationSet

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.

Socket

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.

StateSet

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.

Util

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.

Interfaces

Action

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.

Component

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.

Document

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.

EditableText

AtkEditableText should be implemented by UI components which contain text which the user can edit, via the AtkObject corresponding to that component (see AtkObject).

HyperlinkImpl

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.

Hypertext

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.

Image

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.

ImplementorIface

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

Selection

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.

StreamableContent

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.

Table

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.

TableCell

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.

Text

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.

Value

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.

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.

Structs

Attribute

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.

Implementor

KeyEventStruct

Encapsulates information about a key event.

PropertyValues

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

Range

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.

Rectangle

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

TextRange

A structure used to describe a text range.

TextRectangle

A structure used to store a rectangle used by AtkText.

Aliases

AttributeSet

This is a singly-linked list (a GSList) of AtkAttribute. It is used by atk_text_get_run_attributes(), atk_text_get_default_attributes(), atk_editable_text_set_run_attributes(), atk_document_get_attributes() and atk_object_get_attributes()

State

Enumerations

CoordType

Specifies how xy coordinates are to be interpreted. Used by functions such as atk_component_get_position() and atk_text_get_character_extents()

KeyEventType

Specifies the type of a keyboard evemt.

Layer

Describes the layer of a component.

RelationType

Describes the type of the relation.

Role

Describes the role of an object.

ScrollType

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

since: 2.30

StateType

The possible types of states of an object.

TextAttribute

Describes the text attributes supported.

TextBoundary

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.

TextClipType

Describes the type of clipping required.

TextGranularity

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

ValueType

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

Bitfields

HyperlinkStateFlags

Describes the type of link.

Callbacks

EventListener

A function which is called when an object emits a matching event, as used in #atk_add_focus_tracker. Currently the only events for which object-specific handlers are supported are events of type “focus:”. Most clients of ATK will prefer to attach signal handlers for the various ATK signals instead.

EventListenerInit

An AtkEventListenerInit function is a special function that is called in order to initialize the per-object event registration system used by AtkEventListener, if any preparation is required.

FocusHandler

The type of callback function used for atk_component_add_focus_handler() and atk_component_remove_focus_handler()

deprecated: 2.9.4 

Function

An AtkFunction is a function definition used for padding which has been added to class and interface structures to allow for expansion in the future.

KeySnoopFunc

An AtkKeySnoopFunc is a type of callback which is called whenever a key event occurs, if registered via atk_add_key_event_listener. It allows for pre-emptive interception of key events via the return code as described below.

PropertyChangeHandler

An AtkPropertyChangeHandler is a function which is executed when an AtkObject’s property changes value. It is specified in a call to atk_object_connect_property_change_handler().

deprecated: Unknown 

Functions

add_focus_tracker

Adds the specified function to the list of functions to be called when an object receives focus.

deprecated: 2.9.4 

add_global_event_listener

Adds the specified function to the list of functions to be called when an ATK event of type event_type occurs.

add_key_event_listener

Adds the specified function to the list of functions to be called when a key event occurs. The data element will be passed to the AtkKeySnoopFunc (listener) as the func_data param, on notification.

focus_tracker_init

Specifies the function to be called for focus tracker initialization. This function should be called by an implementation of the ATK interface if any specific work needs to be done to enable focus tracking.

deprecated: 2.9.4 

focus_tracker_notify

Cause the focus tracker functions which have been specified to be executed for the object.

deprecated: 2.9.4 

get_binary_age

Returns the binary age as passed to libtool when building the ATK library the process is running against.

since: 2.8

get_default_registry

Gets a default implementation of the AtkObjectFactory/type registry. Note: For most toolkit maintainers, this will be the correct registry for registering new AtkObject factories. Following a call to this function, maintainers may call atk_registry_set_factory_type() to associate an AtkObjectFactory subclass with the GType of objects for whom accessibility information will be provided.

get_focus_object

Gets the currently focused object.

since: 1.6

get_interface_age

Returns the interface age as passed to libtool when building the ATK library the process is running against.

since: 2.8

get_major_version

Returns the major version number of the ATK library. (e.g. in ATK version 2.7.4 this is 2.)

since: 2.8

get_micro_version

Returns the micro version number of the ATK library. (e.g. in ATK version 2.7.4 this is 4.)

since: 2.8

get_minor_version

Returns the minor version number of the ATK library. (e.g. in ATK version 2.7.4 this is 7.)

since: 2.8

get_root

Gets the root accessible container for the current application.

get_toolkit_name

Gets name string for the GUI toolkit implementing ATK for this application.

get_toolkit_version

Gets version string for the GUI toolkit implementing ATK for this application.

get_version

Gets the current version for ATK.

since: 1.20

remove_focus_tracker

Removes the specified focus tracker from the list of functions to be called when any object receives focus.

deprecated: 2.9.4 

remove_global_event_listener

listener_id is the value returned by #atk_add_global_event_listener when you registered that event listener.

remove_key_event_listener

listener_id is the value returned by #atk_add_key_event_listener when you registered that event listener.

Function Macros

CHECK_VERSION

Returns TRUE if the version of the ATK header files is the same as or newer than the passed-in version.

since: 2.7.4

DEFINE_ABSTRACT_TYPE

A convenience macro for ATK type implementations. Similar to ATK_DEFINE_TYPE(), but defines an abstract type.

since: 1.22

DEFINE_ABSTRACT_TYPE_WITH_CODE

A convenience macro for ATK type implementations. Similar to ATK_DEFINE_TYPE_WITH_CODE(), but defines an abstract type.

since: 1.22

DEFINE_TYPE

A convenience macro for type ATK implementations, which declares a class initialization function, an instance initialization function (see GTypeInfo for information about these) and a static variable named t_n _parent_class pointing to the parent class. Furthermore, it defines a _get_type() function.

since: 1.22

DEFINE_TYPE_EXTENDED

The most general convenience macro for ATK type implementations, on which ATK_DEFINE_TYPE(), etc are based.

since: 1.22

DEFINE_TYPE_WITH_CODE

A convenience macro for ATK type implementations. Similar to ATK_DEFINE_TYPE(), but allows you to insert custom code into the _get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().

since: 1.22

DEPRECATED_FOR

GOBJECT_ACCESSIBLE

GOBJECT_ACCESSIBLE_CLASS

NO_OP_OBJECT

NO_OP_OBJECT_CLASS

NO_OP_OBJECT_FACTORY

NO_OP_OBJECT_FACTORY_CLASS

UNAVAILABLE

Constants

BINARY_AGE

Like atk_get_binary_age(), but from the headers used at application compile time, rather than from the library linked against at application run time.

INTERFACE_AGE

Like atk_get_interface_age(), but from the headers used at application compile time, rather than from the library linked against at application run time.

MAJOR_VERSION

Like atk_get_major_version(), but from the headers used at application compile time, rather than from the library linked against at application run time.

MICRO_VERSION

Like atk_get_micro_version(), but from the headers used at application compile time, rather than from the library linked against at application run time.

MINOR_VERSION

Like atk_get_minor_version(), but from the headers used at application compile time, rather than from the library linked against at application run time.

VERSION_MIN_REQUIRED

A macro that should be defined by the user prior to including the atk/atk.h header. The definition should be one of the predefined ATK version macros: ATK_VERSION_2_12, ATK_VERSION_2_14,…