gi-gtk4-4.0.12: Gtk 4.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Interfaces.Accessible

Contents

- Exported types
- Methods
  - announce
  - getAccessibleId
  - getAccessibleParent
  - getAccessibleRole
  - getAtContext
  - getBounds
  - getFirstAccessibleChild
  - getNextAccessibleSibling
  - getPlatformState
  - resetProperty
  - resetRelation
  - resetState
  - setAccessibleParent
  - updateNextAccessibleSibling
  - updatePlatformState
  - updateProperty
  - updateRelation
  - updateState
- Properties
  - accessibleRole

Description

An interface for describing UI elements for Assistive Technologies.

Every accessible implementation has:

- a “role”, represented by a value of the `AccessibleRole` enumeration
- “attributes”, represented by a set of `AccessibleState`, `AccessibleProperty` and `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 `AccessibleStateHidden` state will also change to reflect the 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 `Accessible`.`get_accessible_parent`(), `Accessible`.`get_first_accessible_child`() and `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 `accessibleSetAccessibleParent` and updating the sibling by `accessibleUpdateNextAccessibleSibling`.

Synopsis

- newtype Accessible = Accessible (ManagedPtr Accessible)
- class (GObject o, IsDescendantOf Accessible o) => IsAccessible o
- toAccessible :: (MonadIO m, IsAccessible o) => o -> m Accessible
- accessibleAnnounce :: (HasCallStack, MonadIO m, IsAccessible a) => a -> Text -> AccessibleAnnouncementPriority -> m ()
- accessibleGetAccessibleId :: (HasCallStack, MonadIO m, IsAccessible a) => a -> m (Maybe Text)
- accessibleGetAccessibleParent :: (HasCallStack, MonadIO m, IsAccessible a) => a -> m (Maybe Accessible)
- accessibleGetAccessibleRole :: (HasCallStack, MonadIO m, IsAccessible a) => a -> m AccessibleRole
- accessibleGetAtContext :: (HasCallStack, MonadIO m, IsAccessible a) => a -> m ATContext
- accessibleGetBounds :: (HasCallStack, MonadIO m, IsAccessible a) => a -> m (Bool, Int32, Int32, Int32, Int32)
- accessibleGetFirstAccessibleChild :: (HasCallStack, MonadIO m, IsAccessible a) => a -> m (Maybe Accessible)
- accessibleGetNextAccessibleSibling :: (HasCallStack, MonadIO m, IsAccessible a) => a -> m (Maybe Accessible)
- accessibleGetPlatformState :: (HasCallStack, MonadIO m, IsAccessible a) => a -> AccessiblePlatformState -> m Bool
- accessibleResetProperty :: (HasCallStack, MonadIO m, IsAccessible a) => a -> AccessibleProperty -> m ()
- accessibleResetRelation :: (HasCallStack, MonadIO m, IsAccessible a) => a -> AccessibleRelation -> m ()
- accessibleResetState :: (HasCallStack, MonadIO m, IsAccessible a) => a -> AccessibleState -> m ()
- accessibleSetAccessibleParent :: (HasCallStack, MonadIO m, IsAccessible a, IsAccessible b, IsAccessible c) => a -> Maybe b -> Maybe c -> m ()
- accessibleUpdateNextAccessibleSibling :: (HasCallStack, MonadIO m, IsAccessible a, IsAccessible b) => a -> Maybe b -> m ()
- accessibleUpdatePlatformState :: (HasCallStack, MonadIO m, IsAccessible a) => a -> AccessiblePlatformState -> m ()
- accessibleUpdateProperty :: (HasCallStack, MonadIO m, IsAccessible a) => a -> [AccessibleProperty] -> [GValue] -> m ()
- accessibleUpdateRelation :: (HasCallStack, MonadIO m, IsAccessible a) => a -> [AccessibleRelation] -> [GValue] -> m ()
- accessibleUpdateState :: (HasCallStack, MonadIO m, IsAccessible a) => a -> [AccessibleState] -> [GValue] -> m ()
- constructAccessibleAccessibleRole :: (IsAccessible o, MonadIO m) => AccessibleRole -> m (GValueConstruct o)
- getAccessibleAccessibleRole :: (MonadIO m, IsAccessible o) => o -> m AccessibleRole
- setAccessibleAccessibleRole :: (MonadIO m, IsAccessible o) => o -> AccessibleRole -> m ()

# Exported types

newtype Accessible Source #

Memory-managed wrapper type.

Constructors

Accessible (ManagedPtr Accessible) |

#### Instances

Instances details

Eq Accessible Source # |
Instance details Defined in GI.Gtk.Interfaces.Accessible Methods (==) :: Accessible -> Accessible -> Bool Source # (/=) :: Accessible -> Accessible -> Bool Source #
GObject Accessible Source # |
Instance details Defined in GI.Gtk.Interfaces.Accessible
ManagedPtrNewtype Accessible Source # |
Instance details Defined in GI.Gtk.Interfaces.Accessible Methods toManagedPtr :: Accessible -> ManagedPtr Accessible Source #
TypedObject Accessible Source # |
Instance details Defined in GI.Gtk.Interfaces.Accessible Methods glibType :: IO GType Source #
HasParentTypes Accessible Source # |
Instance details Defined in GI.Gtk.Interfaces.Accessible
IsGValue (Maybe Accessible) Source # | Convert `Accessible` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Interfaces.Accessible Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Accessible -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Accessible) Source #
type ParentTypes Accessible Source # |
Instance details Defined in GI.Gtk.Interfaces.Accessible type ParentTypes Accessible = '[Object]

class (GObject o, IsDescendantOf Accessible o) => IsAccessible o Source #

Type class for types which can be safely cast to `Accessible`, for instance with `toAccessible`.

#### Instances

Instances details

(GObject o, IsDescendantOf Accessible o) => IsAccessible o Source # |
Instance details Defined in GI.Gtk.Interfaces.Accessible

toAccessible :: (MonadIO m, IsAccessible o) => o -> m Accessible Source #

Cast to `Accessible`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

announce, bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, resetProperty, resetRelation, resetState, runDispose, stealData, stealQdata, thawNotify, unref, updateNextAccessibleSibling, updatePlatformState, updateProperty, updateRelation, updateState, watchClosure.

#### Getters

getAccessibleId, getAccessibleParent, getAccessibleRole, getAtContext, getBounds, getData, getFirstAccessibleChild, getNextAccessibleSibling, getPlatformState, getProperty, getQdata.

#### Setters

setAccessibleParent, setData, setDataFull, setProperty.

## announce

accessibleAnnounce Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> Text | `message`: the string to announce
-> AccessibleAnnouncementPriority | `priority`: the priority of the announcement
-> m () |

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.

Since: 4.14

## getAccessibleId

accessibleGetAccessibleId Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> m (Maybe Text) | Returns: the accessible identifier

Retrieves the accessible identifier for the accessible object.

This functionality can be overridden by `GtkAccessible` implementations.

It is left to the accessible implementation to define the scope and uniqueness of the identifier.

Since: 4.22

## getAccessibleParent

accessibleGetAccessibleParent Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> m (Maybe Accessible) | Returns: the accessible parent

Retrieves the accessible parent for an accessible object.

This function returns `NULL` for top level widgets.

Since: 4.10

## getAccessibleRole

accessibleGetAccessibleRole Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> m AccessibleRole | Returns: the accessible role

Retrieves the accessible role of an accessible object.

## getAtContext

accessibleGetAtContext Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> m ATContext | Returns: the accessible implementation object

Retrieves the implementation for the given accessible object.

Since: 4.10

## getBounds

accessibleGetBounds Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> m (Bool, Int32, Int32, Int32, Int32) | Returns: true if the bounds are valid, and false otherwise

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.

Since: 4.10

## getFirstAccessibleChild

accessibleGetFirstAccessibleChild Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> m (Maybe Accessible) | Returns: the first accessible child

Retrieves the first accessible child of an accessible object.

Since: 4.10

## getNextAccessibleSibling

accessibleGetNextAccessibleSibling Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> m (Maybe Accessible) | Returns: the next accessible sibling

Retrieves the next accessible sibling of an accessible object

Since: 4.10

## getPlatformState

accessibleGetPlatformState Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> AccessiblePlatformState | `state`: platform state to query
-> m Bool | Returns: the value of state for the accessible

Queries a platform state, such as focus.

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.

Since: 4.10

## resetProperty

accessibleResetProperty Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> AccessibleProperty | `property`: the accessible property
-> m () |

Resets the accessible property to its default value.

## resetRelation

accessibleResetRelation Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> AccessibleRelation | `relation`: the accessible relation
-> m () |

Resets the accessible relation to its default value.

## resetState

accessibleResetState Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> AccessibleState | `state`: the accessible state
-> m () |

Resets the accessible state to its default value.

## setAccessibleParent

accessibleSetAccessibleParent Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a, IsAccessible b, IsAccessible c) |
=> a | `self`: an accessible object
-> Maybe b | `parent`: the parent accessible object
-> Maybe c | `nextSibling`: the sibling accessible object
-> m () |

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.

Since: 4.10

## updateNextAccessibleSibling

accessibleUpdateNextAccessibleSibling Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a, IsAccessible b) |
=> a | `self`: an accessible object
-> Maybe b | `newSibling`: the new next accessible sibling to set
-> m () |

Updates the next accessible sibling.

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

Since: 4.10

## updatePlatformState

accessibleUpdatePlatformState Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> AccessiblePlatformState | `state`: the platform state to update
-> m () |

Informs ATs that the platform state has changed.

This function should be used by `GtkAccessible` implementations that have a platform state but are not widgets. Widgets handle platform states automatically.

Since: 4.18

## updateProperty

accessibleUpdateProperty Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> [AccessibleProperty] | `properties`: an array of accessible properties
-> [GValue] | `values`: an array of `GValues`, one for each property
-> m () |

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.

## updateRelation

accessibleUpdateRelation Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible object
-> [AccessibleRelation] | `relations`: an array of accessible relations
-> [GValue] | `values`: an array of `GValues`, one for each relation
-> m () |

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.

## updateState

accessibleUpdateState Source #

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a) |
=> a | `self`: an accessible objedct
-> [AccessibleState] | `states`: an array of accessible states
-> [GValue] | `values`: an array of `GValues`, one for each state
-> m () |

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.

# Properties

## accessibleRole

The accessible role of the given `GtkAccessible` implementation.

The accessible role cannot be changed once set.

constructAccessibleAccessibleRole :: (IsAccessible o, MonadIO m) => AccessibleRole -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`accessible-role`” property. This is rarely needed directly, but it is used by `new`.

getAccessibleAccessibleRole :: (MonadIO m, IsAccessible o) => o -> m AccessibleRole Source #

Get the value of the “`accessible-role`” property. When overloading is enabled, this is equivalent to

    get accessible #accessibleRole

setAccessibleAccessibleRole :: (MonadIO m, IsAccessible o) => o -> AccessibleRole -> m () Source #

Set the value of the “`accessible-role`” property. When overloading is enabled, this is equivalent to

    set accessible [ #accessibleRole := value ]