Module: Gtk::Accessible

Defined in:

(unknown)

Overview

GtkAccessible is an interface for describing UI elements for Assistive Technologies.

Every accessible implementation has:

• a “role”, represented by a value of the [enumGtk.AccessibleRole] enumeration
• an “attribute”, represented by a set of [enumGtk.AccessibleState], [enumGtk.AccessibleProperty] and [enumGtk.AccessibleRelation] values

The role cannot be changed after instantiating a GtkAccessible implementation.

The attributes are updated every time a UI element's state changes in a way that should be reflected by assistive technologies. For instance, if a GtkWidget visibility changes, the %GTK_ACCESSIBLE_STATE_HIDDEN state will also change to reflect the [propertyGtk.Widget:visible] property.

Every accessible implementation is part of a tree of accessible objects. Normally, this tree corresponds to the widget tree, but can be customized by reimplementing the [vfuncGtk.Accessible.get_accessible_parent], [vfuncGtk.Accessible.get_first_accessible_child] and [vfuncGtk.Accessible.get_next_accessible_sibling] virtual functions. Note that you can not create a top-level accessible object as of now, which means that you must always have a parent accessible object. Also note that when an accessible object does not correspond to a widget, and it has children, whose implementation you don't control, it is necessary to ensure the correct shape of the a11y tree by calling [methodGtk.Accessible.set_accessible_parent] and updating the sibling by [methodGtk.Accessible.update_next_accessible_sibling].

Instance Method Summary

• #accessible_parent ⇒ Gtk::Accessible

  Retrieves the accessible parent for an accessible object.

• #accessible_role ⇒ Gtk::AccessibleRole

  Retrieves the accessible role of an accessible object.

• #announce(message, priority) ⇒ nil

  Requests the user's screen reader to announce the given message.

• #at_context ⇒ Gtk::ATContext

  Retrieves the accessible implementation for the given GtkAccessible.

• #first_accessible_child ⇒ Gtk::Accessible

  Retrieves the first accessible child of an accessible object.

• #get_bounds(x, y, width, height) ⇒ Boolean

  Queries the coordinates and dimensions of this accessible.

• #get_platform_state(state) ⇒ Boolean

  Query a platform state, such as focus.

• #next_accessible_sibling ⇒ Gtk::Accessible

  Retrieves the next accessible sibling of an accessible object.

• #reset_property(property) ⇒ nil

  Resets the accessible property to its default value.

• #reset_relation(relation) ⇒ nil

  Resets the accessible relation to its default value.

• #reset_state(state) ⇒ nil

  Resets the accessible state to its default value.

• #set_accessible_parent(parent, next_sibling) ⇒ nil

  Sets the parent and sibling of an accessible object.

• #update_next_accessible_sibling(new_sibling) ⇒ nil

  Updates the next accessible sibling of self.

• #update_property(first_property, array) ⇒ nil

  Updates a list of accessible properties.

• #update_property_value(n_properties, properties, values) ⇒ nil

  Updates an array of accessible properties.

• #update_relation(first_relation, array) ⇒ nil

  Updates a list of accessible relations.

• #update_relation_value(n_relations, relations, values) ⇒ nil

  Updates an array of accessible relations.

• #update_state(first_state, array) ⇒ nil

  Updates a list of accessible states.

• #update_state_value(n_states, states, values) ⇒ nil

  Updates an array of accessible states.

Instance Method Details

#accessible_parent ⇒ Gtk::Accessible

Retrieves the accessible parent for an accessible object.

This function returns NULL for top level widgets.

Returns:

• (Gtk::Accessible) —

  the accessible parent

#accessible_role ⇒ Gtk::AccessibleRole

Retrieves the accessible role of an accessible object.

Returns:

• (Gtk::AccessibleRole) —

  the accessible role

#announce(message, priority) ⇒ nil

Requests the user's screen reader to announce the given message.

This kind of notification is useful for messages that either have only a visual representation or that are not exposed visually at all, e.g. a notification about a successful operation.

Also, by using this API, you can ensure that the message does not interrupts the user's current screen reader output.

Parameters:

• message (String) —

  the string to announce

• priority (Gtk::AccessibleAnnouncementPriority) —

  the priority of the announcement

Returns:

• (nil)

#at_context ⇒ Gtk::ATContext

Retrieves the accessible implementation for the given GtkAccessible.

Returns:

• (Gtk::ATContext) —

  the accessible implementation object

#first_accessible_child ⇒ Gtk::Accessible

Retrieves the first accessible child of an accessible object.

Returns:

• (Gtk::Accessible) —

  the first accessible child

#get_bounds(x, y, width, height) ⇒ Boolean

Queries the coordinates and dimensions of this accessible

This functionality can be overridden by GtkAccessible implementations, e.g. to get the bounds from an ignored child widget.

Parameters:

• x (Integer) —

  the x coordinate of the top left corner of the accessible

• y (Integer) —

  the y coordinate of the top left corner of the widget

• width (Integer) —

  the width of the accessible object

• height (Integer) —

  the height of the accessible object

Returns:

• (Boolean) —

  true if the bounds are valid, and false otherwise

#get_platform_state(state) ⇒ Boolean

Query a platform state, such as focus.

See gtk_accessible_platform_changed().

This functionality can be overridden by GtkAccessible implementations, e.g. to get platform state from an ignored child widget, as is the case for GtkText wrappers.

Parameters:

• state (Gtk::AccessiblePlatformState) —

  platform state to query

Returns:

• (Boolean) —

  the value of state for the accessible

#next_accessible_sibling ⇒ Gtk::Accessible

Retrieves the next accessible sibling of an accessible object

Returns:

• (Gtk::Accessible) —

  the next accessible sibling

#reset_property(property) ⇒ nil

Resets the accessible property to its default value.

Parameters:

• property (Gtk::AccessibleProperty) —

  a GtkAccessibleProperty

Returns:

• (nil)

#reset_relation(relation) ⇒ nil

Resets the accessible relation to its default value.

Parameters:

• relation (Gtk::AccessibleRelation) —

  a GtkAccessibleRelation

Returns:

• (nil)

#reset_state(state) ⇒ nil

Resets the accessible state to its default value.

Parameters:

• state (Gtk::AccessibleState) —

  a GtkAccessibleState

Returns:

• (nil)

#set_accessible_parent(parent, next_sibling) ⇒ nil

Sets the parent and sibling of an accessible object.

This function is meant to be used by accessible implementations that are not part of the widget hierarchy, and but act as a logical bridge between widgets. For instance, if a widget creates an object that holds metadata for each child, and you want that object to implement the GtkAccessible interface, you will use this function to ensure that the parent of each child widget is the metadata object, and the parent of each metadata object is the container widget.

Parameters:

• parent (Gtk::Accessible) —

  the parent accessible object

• next_sibling (Gtk::Accessible) —

  the sibling accessible object

Returns:

• (nil)

#update_next_accessible_sibling(new_sibling) ⇒ nil

Updates the next accessible sibling of self.

That might be useful when a new child of a custom GtkAccessible is created, and it needs to be linked to a previous child.

Parameters:

• new_sibling (Gtk::Accessible) —

  the new next accessible sibling to set

Returns:

• (nil)

#update_property(first_property, array) ⇒ nil

Updates a list of accessible properties.

See the [enumGtk.AccessibleProperty] documentation for the value types of accessible properties.

This function should be called by GtkWidget types whenever an accessible property change must be communicated to assistive technologies.

Example:

value = gtk_adjustment_get_value (adjustment);
gtk_accessible_update_property (GTK_ACCESSIBLE (spin_button),
                                   GTK_ACCESSIBLE_PROPERTY_VALUE_NOW, value,
                                   -1);

Parameters:

• first_property (Gtk::AccessibleProperty) —

  the first GtkAccessibleProperty

• array (Array) —

  a list of property and value pairs, terminated by -1

Returns:

• (nil)

#update_property_value(n_properties, properties, values) ⇒ nil

Updates an array of accessible properties.

This function should be called by GtkWidget types whenever an accessible property change must be communicated to assistive technologies.

This function is meant to be used by language bindings.

Parameters:

• n_properties (Integer) —

  the number of accessible properties to set

• properties (Array<Gtk::AccessibleProperty>) —

  an array of GtkAccessibleProperty

• values (Array<GObject::Value>) —

  an array of GValues, one for each property

Returns:

• (nil)

#update_relation(first_relation, array) ⇒ nil

Updates a list of accessible relations.

This function should be called by GtkWidget types whenever an accessible relation change must be communicated to assistive technologies.

If the [enumGtk.AccessibleRelation] requires a list of references, you should pass each reference individually, followed by nil, e.g.

gtk_accessible_update_relation (accessible,
                                GTK_ACCESSIBLE_RELATION_CONTROLS,
                                  ref1, NULL,
                                GTK_ACCESSIBLE_RELATION_LABELLED_BY,
                                  ref1, ref2, ref3, NULL,
                                -1);

Parameters:

• first_relation (Gtk::AccessibleRelation) —

  the first GtkAccessibleRelation

• array (Array) —

  a list of relation and value pairs, terminated by -1

Returns:

• (nil)

#update_relation_value(n_relations, relations, values) ⇒ nil

Updates an array of accessible relations.

This function should be called by GtkWidget types whenever an accessible relation change must be communicated to assistive technologies.

This function is meant to be used by language bindings.

Parameters:

• n_relations (Integer) —

  the number of accessible relations to set

• relations (Array<Gtk::AccessibleRelation>) —

  an array of GtkAccessibleRelation

• values (Array<GObject::Value>) —

  an array of GValues, one for each relation

Returns:

• (nil)

#update_state(first_state, array) ⇒ nil

Updates a list of accessible states. See the [enumGtk.AccessibleState] documentation for the value types of accessible states.

This function should be called by GtkWidget types whenever an accessible state change must be communicated to assistive technologies.

Example:

value = GTK_ACCESSIBLE_TRISTATE_MIXED;
gtk_accessible_update_state (GTK_ACCESSIBLE (check_button),
                             GTK_ACCESSIBLE_STATE_CHECKED, value,
                             -1);

Parameters:

• first_state (Gtk::AccessibleState) —

  the first GtkAccessibleState

• array (Array) —

  a list of state and value pairs, terminated by -1

Returns:

• (nil)

#update_state_value(n_states, states, values) ⇒ nil

Updates an array of accessible states.

This function should be called by GtkWidget types whenever an accessible state change must be communicated to assistive technologies.

This function is meant to be used by language bindings.

Parameters:

• n_states (Integer) —

  the number of accessible states to set

• states (Array<Gtk::AccessibleState>) —

  an array of GtkAccessibleState

• values (Array<GObject::Value>) —

  an array of GValues, one for each state

Returns:

• (nil)