diff --git a/gtk/a11y/gtkatspicontext.c b/gtk/a11y/gtkatspicontext.c index 0643ed6089..5501721d12 100644 --- a/gtk/a11y/gtkatspicontext.c +++ b/gtk/a11y/gtkatspicontext.c @@ -82,7 +82,7 @@ * hold the TAB_PANEL role and be the target of the CONTROLS * relation with their corresponding tabs (in the stack * switcher or notebook). - * + * * These are the exceptions implemented by GTK itself, but note that application * developers can customize the accessibility tree by implementing the * [iface@Gtk.Accessible] interface in any way they choose. @@ -343,7 +343,7 @@ get_index_in (GtkAccessible *parent, return -1; res = 0; -for (candidate = gtk_accessible_get_first_accessible_child (parent); + for (candidate = gtk_accessible_get_first_accessible_child (parent); candidate != NULL; candidate = gtk_accessible_get_next_accessible_sibling (candidate)) { @@ -363,7 +363,11 @@ static int get_index_in_parent (GtkAccessible *accessible) { GtkAccessible *parent = gtk_accessible_get_accessible_parent (accessible); - return get_index_in(parent, accessible); + + if (parent != NULL) + return get_index_in (parent, accessible); + + return -1; } static int @@ -1108,19 +1112,16 @@ gtk_at_spi_context_child_change (GtkATContext *ctx, GtkAccessible *accessible = gtk_at_context_get_accessible (ctx); GtkATContext *child_context = gtk_accessible_get_at_context (child); - int idx = 0; - if (child_context == NULL) return; - if (gtk_accessible_get_accessible_parent (child) != accessible) - { - idx = 0; - } - else - { - idx = get_index_in(accessible, child); - } + GtkAccessible *parent = gtk_accessible_get_accessible_parent (child); + int idx = 0; + + if (parent == NULL) + idx = -1; + else if (parent == accessible) + idx = get_index_in (accessible, child); if (change & GTK_ACCESSIBLE_CHILD_CHANGE_ADDED) emit_children_changed (self, diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c index a029d09f81..7143c14006 100644 --- a/gtk/gtkaccessible.c +++ b/gtk/gtkaccessible.c @@ -41,7 +41,8 @@ * 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 [vfunc@Gtk.Accessible.get_accessible_parent], - * [vfunc@Gtk.Accessible.get_first_accessible_child] and [vfunc@Gtk.Accessible.get_next_accessible_sibling] virtual functions. + * [vfunc@Gtk.Accessible.get_first_accessible_child] and + * [vfunc@Gtk.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. */ @@ -97,13 +98,17 @@ gtk_accessible_get_at_context (GtkAccessible *self) return GTK_ACCESSIBLE_GET_IFACE (self)->get_at_context (self); } -/* +/** * gtk_accessible_get_accessible_parent: * @self: a `GtkAccessible` * - * Retrieves the parent `GtkAccessible` for the given `GtkAccessible`. + * Retrieves the accessible accessible for an accessible object * - * Returns: (transfer none): the parent `GtkAccessible`, which can not be %NULL + * This function returns `NULL` for top level widgets + * + * Returns: (transfer none) (nullable): the accessible parent + * + * Since: 4.10 */ GtkAccessible * gtk_accessible_get_accessible_parent (GtkAccessible *self) @@ -113,14 +118,13 @@ gtk_accessible_get_accessible_parent (GtkAccessible *self) return GTK_ACCESSIBLE_GET_IFACE (self)->get_accessible_parent (self); } - /** * gtk_accessible_get_first_accessible_child: - * @self: a `GtkAccessible` + * @self: an accessible object * - * Retrieves the first child `GtkAccessible` for this `GtkAccessible`. + * Retrieves the first accessible child of an accessible object. * - * Returns: (transfer none) (nullable): the first `GtkAccessible` child of @self, if @self has accessible children, %NULL otherwise + * Returns: (transfer none) (nullable): the first accessible child * * since: 4.10 */ @@ -134,11 +138,11 @@ gtk_accessible_get_first_accessible_child (GtkAccessible *self) /** * gtk_accessible_get_next_accessible_sibling: - * @self: a `GtkAccessible` + * @self: an accessible object * - * Retrieves the next `GtkAccessible` sibling of this `GtkAccessible`. + * Retrieves the next accessible sibling of an accessible object * - * Returns: (transfer none) (nullable): the next `GtkAccessible` sibling of @self, if @self has a next sibling, %NULL otherwise + * Returns: (transfer none) (nullable): the next accessible sibling * * since: 4.10 */ @@ -151,12 +155,12 @@ gtk_accessible_get_next_accessible_sibling (GtkAccessible *self) } /** - * gtk_accessible_get_accessible_role: (attributes org.gtk.Method.get_property=accessible-role) - * @self: a `GtkAccessible` + * gtk_accessible_get_accessible_role: + * @self: an accessible object * - * Retrieves the `GtkAccessibleRole` for the given `GtkAccessible`. + * Retrieves the accessible role of an accessible object. * - * Returns: a `GtkAccessibleRole` + * Returns: the accessible role */ GtkAccessibleRole gtk_accessible_get_accessible_role (GtkAccessible *self) @@ -187,6 +191,7 @@ gtk_accessible_get_accessible_role (GtkAccessible *self) * state change must be communicated to assistive technologies. * * Example: + * * ```c * value = GTK_ACCESSIBLE_TRISTATE_MIXED; * gtk_accessible_update_state (GTK_ACCESSIBLE (check_button), @@ -743,7 +748,7 @@ gtk_accessible_role_is_range_subclass (GtkAccessibleRole role) return FALSE; } -/* +/*< private > * gtk_accessible_platform_changed: * @self: a `GtkAccessible` * @change: the platform state change to report @@ -795,15 +800,19 @@ gtk_accessible_platform_changed (GtkAccessible *self, * child widget, as is the case for `GtkText` wrappers. * * Returns: the value of @state for the accessible + * + * Since: 4.10 */ gboolean gtk_accessible_get_platform_state (GtkAccessible *self, GtkAccessiblePlatformState state) { + g_return_val_if_fail (GTK_IS_ACCESSIBLE (self), FALSE); + return GTK_ACCESSIBLE_GET_IFACE (self)->get_platform_state (self, state); } -/**< private > +/*< private > * gtk_accessible_bounds_changed: * @self: a `GtkAccessible` * @@ -830,7 +839,7 @@ gtk_accessible_bounds_changed (GtkAccessible *self) gtk_at_context_bounds_changed (context); } -/* +/** * gtk_accessible_get_bounds: * @self: a `GtkAccessible` * @x: (out): the x coordinate of the top left corner of the accessible @@ -855,10 +864,14 @@ gtk_accessible_get_bounds (GtkAccessible *self, int *width, int *height) { + g_return_val_if_fail (GTK_IS_ACCESSIBLE (self), FALSE); + g_return_val_if_fail (x != NULL && y != NULL, FALSE); + g_return_val_if_fail (width != NULL && height != NULL, FALSE); + return GTK_ACCESSIBLE_GET_IFACE (self)->get_bounds (self, x, y, width, height); } -/* +/*< private > * gtk_accessible_should_present: * @self: a `GtkAccessible` * diff --git a/gtk/gtkaccessible.h b/gtk/gtkaccessible.h index 4146a8d57e..713a9b5ccf 100644 --- a/gtk/gtkaccessible.h +++ b/gtk/gtkaccessible.h @@ -40,7 +40,7 @@ G_DECLARE_INTERFACE (GtkAccessible, gtk_accessible, GTK, ACCESSIBLE, GObject) * @GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSABLE: whether the accessible can be focused * @GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSED: whether the accessible has focus * @GTK_ACCESSIBLE_PLATFORM_STATE_ACTIVE: whether the accessible is active - * + * * The various platform states which can be queried * using [method@Gtk.Accessible.get_platform_state]. * @@ -52,161 +52,179 @@ typedef enum { GTK_ACCESSIBLE_PLATFORM_STATE_ACTIVE } GtkAccessiblePlatformState; -/** < private > - * GtkAccessiblePlatformChange: - * @GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSABLE: whether the accessible has changed - * its focusable state - * @GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSED: whether the accessible has changed its - * focused state - * @GTK_ACCESSIBLE_PLATFORM_CHANGE_ACTIVE: whether the accessible has changed its - * active state +/** + * GtkAccessibleInterface: + * @get_at_context: retrieve the platform-specific accessibility context + * for the accessible implementation + * @get_platform_state: retrieve the accessible state * - * Represents the various platform changes which can occur and are communicated - * using [method@Gtk.Accessible.platform_changed]. + * The common interface for accessible objects. + * + * Since: 4.10 */ -typedef enum { - GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSABLE = 1 << GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSABLE, - GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSED = 1 << GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSED, - GTK_ACCESSIBLE_PLATFORM_CHANGE_ACTIVE = 1 << GTK_ACCESSIBLE_PLATFORM_STATE_ACTIVE, -} GtkAccessiblePlatformChange; - struct _GtkAccessibleInterface { GTypeInterface g_iface; /** * GtkAccessibleInterface::get_at_context: - * @self: a `GtkAccessible` - * - * Retrieves the `GtkATContext` for this accessible implementation. + * @self: an accessible object + * + * Retrieves the platform-specific accessibility context for the + * accessible implementation. + * + * Returns: (transfer none) (nullable): the accessibility context + * + * Since: 4.10 */ - GtkATContext * (* get_at_context) (GtkAccessible *self); + GtkATContext * (* get_at_context) (GtkAccessible *self); /** * GtkAccessibleInterface::get_platform_state: - * - * @self: A `GtkAccessible` - * @state: The state to retrieve - * - * Returns whether @self has the given platform state. - * @returns: %true if @state is active for @self. - * @returns: + * @self: an accessible object + * @state: the state to query + * + * Checks if the given @state applies to the accessible object. + * + * Returns: true if the @state is set, and false otherwise + * + * Since: 4.10 */ - gboolean (* get_platform_state) (GtkAccessible *self, - GtkAccessiblePlatformState state); + gboolean (* get_platform_state) (GtkAccessible *self, + GtkAccessiblePlatformState state); /** * GtkAccessibleInterface::get_accessible_parent: - * @self: a `GtkAccessible` - * - * Returns the parent `GtkAccessible` of @self. - * A return value of %NULL implies that the accessible represents a top-level - * accessible object, which currently also implies that the accessible - * represents something which is in the list of top-level widgets. + * @self: an accessible object + * + * Retrieves the accessible parent of an accessible object. + * + * This virtual function should return `NULL` for top level objects. + * + * Returns: (nullable) (transfer none): the accessible parent + * + * Since: 4.10 */ - GtkAccessible * (* get_accessible_parent) (GtkAccessible *self); - + GtkAccessible * (* get_accessible_parent) (GtkAccessible *self); + /** * GtkaccessibleInterface::get_first_accessible_child: - * @self: a `GtkAccessible` - * - * Returns the first accessible child of @self, or %NULL if @self has none + * @self: an accessible object + * + * Retrieves the first accessible child of an accessible object. + * + * Returns: (transfer none) (nullable): an accessible object + * + * Since: 4.10 */ - GtkAccessible * (* get_first_accessible_child) (GtkAccessible *self); - + GtkAccessible * (* get_first_accessible_child) (GtkAccessible *self); /** * GtkaccessibleInterface::get_next_accessible_sibling: - * @self: a `GtkAccessible` - * - * Returns the next accessible sibling of @self, or %NULL if @self has none + * @self: an accessible object + * + * Retrieves the next accessible sibling of an accessible object. + * + * Returns: (transfer none) (nullable): an accessible object + * + * Since: 4.10 */ - GtkAccessible * (* get_next_accessible_sibling) (GtkAccessible *self); + GtkAccessible * (* get_next_accessible_sibling) (GtkAccessible *self); /** * GtkAccessibleInterface::get_bounds: - * @self: a `GtkAccessible` - * @x: an addres of the x coordinate - * @y: an address of the y coordinate - * @width: address of the width - * @height: address of the height - * - * Returns the dimensions and position of @self, if this information - * can be determined. - * @returns: %true if the values are valid, %false otherwise + * @self: an accessible object + * @x: (out): the horizontal coordinate of a rectangle + * @y: (out): the vertical coordinate of a rectangle + * @width: (out): the width of a rectangle + * @height: (out): the height of a rectangle + * + * Retrieves the dimensions and position of an accessible object in its + * parent's coordinate space, if those values can be determined. + * + * For top level accessible objects, the X and Y coordinates are always + * going to be set to zero. + * + * Returns: true if the values are value, and false otherwise */ - gboolean (* get_bounds) (GtkAccessible *self, int *x, int *y, - int *width, int *height); + gboolean (* get_bounds) (GtkAccessible *self, + int *x, + int *y, + int *width, + int *height); }; GDK_AVAILABLE_IN_ALL GtkATContext * gtk_accessible_get_at_context (GtkAccessible *self); GDK_AVAILABLE_IN_4_10 -gboolean gtk_accessible_get_platform_state (GtkAccessible *self, - GtkAccessiblePlatformState state); +gboolean gtk_accessible_get_platform_state (GtkAccessible *self, + GtkAccessiblePlatformState state); GDK_AVAILABLE_IN_4_10 -GtkAccessible * gtk_accessible_get_accessible_parent(GtkAccessible *self); +GtkAccessible * gtk_accessible_get_accessible_parent (GtkAccessible *self); GDK_AVAILABLE_IN_4_10 -GtkAccessible * gtk_accessible_get_first_accessible_child(GtkAccessible *self); +GtkAccessible * gtk_accessible_get_first_accessible_child (GtkAccessible *self); GDK_AVAILABLE_IN_4_10 -GtkAccessible * gtk_accessible_get_next_accessible_sibling(GtkAccessible *self); +GtkAccessible * gtk_accessible_get_next_accessible_sibling (GtkAccessible *self); GDK_AVAILABLE_IN_4_10 -gboolean gtk_accessible_get_bounds (GtkAccessible *self, int *x, int *y, int *width, int *height); +gboolean gtk_accessible_get_bounds (GtkAccessible *self, + int *x, + int *y, + int *width, + int *height); GDK_AVAILABLE_IN_ALL -GtkAccessibleRole gtk_accessible_get_accessible_role (GtkAccessible *self); +GtkAccessibleRole gtk_accessible_get_accessible_role (GtkAccessible *self); GDK_AVAILABLE_IN_ALL -void gtk_accessible_update_state (GtkAccessible *self, - GtkAccessibleState first_state, - ...); +void gtk_accessible_update_state (GtkAccessible *self, + GtkAccessibleState first_state, + ...); GDK_AVAILABLE_IN_ALL -void gtk_accessible_update_property (GtkAccessible *self, - GtkAccessibleProperty first_property, - ...); +void gtk_accessible_update_property (GtkAccessible *self, + GtkAccessibleProperty first_property, + ...); GDK_AVAILABLE_IN_ALL -void gtk_accessible_update_relation (GtkAccessible *self, - GtkAccessibleRelation first_relation, - ...); +void gtk_accessible_update_relation (GtkAccessible *self, + GtkAccessibleRelation first_relation, + ...); GDK_AVAILABLE_IN_ALL -void gtk_accessible_update_state_value (GtkAccessible *self, - int n_states, - GtkAccessibleState states[], - const GValue values[]); +void gtk_accessible_update_state_value (GtkAccessible *self, + int n_states, + GtkAccessibleState states[], + const GValue values[]); GDK_AVAILABLE_IN_ALL -void gtk_accessible_update_property_value (GtkAccessible *self, - int n_properties, - GtkAccessibleProperty properties[], - const GValue values[]); +void gtk_accessible_update_property_value (GtkAccessible *self, + int n_properties, + GtkAccessibleProperty properties[], + const GValue values[]); GDK_AVAILABLE_IN_ALL -void gtk_accessible_update_relation_value (GtkAccessible *self, - int n_relations, - GtkAccessibleRelation relations[], - const GValue values[]); +void gtk_accessible_update_relation_value (GtkAccessible *self, + int n_relations, + GtkAccessibleRelation relations[], + const GValue values[]); +GDK_AVAILABLE_IN_ALL +void gtk_accessible_reset_state (GtkAccessible *self, + GtkAccessibleState state); +GDK_AVAILABLE_IN_ALL +void gtk_accessible_reset_property (GtkAccessible *self, + GtkAccessibleProperty property); +GDK_AVAILABLE_IN_ALL +void gtk_accessible_reset_relation (GtkAccessible *self, + GtkAccessibleRelation relation); GDK_AVAILABLE_IN_ALL -void gtk_accessible_reset_state (GtkAccessible *self, - GtkAccessibleState state); +void gtk_accessible_state_init_value (GtkAccessibleState state, + GValue *value); GDK_AVAILABLE_IN_ALL -void gtk_accessible_reset_property (GtkAccessible *self, - GtkAccessibleProperty property); +void gtk_accessible_property_init_value (GtkAccessibleProperty property, + GValue *value); GDK_AVAILABLE_IN_ALL -void gtk_accessible_reset_relation (GtkAccessible *self, - GtkAccessibleRelation relation); - -GDK_AVAILABLE_IN_ALL -void gtk_accessible_state_init_value (GtkAccessibleState state, - GValue *value); -GDK_AVAILABLE_IN_ALL -void gtk_accessible_property_init_value (GtkAccessibleProperty property, - GValue *value); -GDK_AVAILABLE_IN_ALL -void gtk_accessible_relation_init_value (GtkAccessibleRelation relation, - GValue *value); +void gtk_accessible_relation_init_value (GtkAccessibleRelation relation, + GValue *value); G_END_DECLS diff --git a/gtk/gtkaccessibleprivate.h b/gtk/gtkaccessibleprivate.h index 2ae1064724..6d2f2f2125 100644 --- a/gtk/gtkaccessibleprivate.h +++ b/gtk/gtkaccessibleprivate.h @@ -21,10 +21,37 @@ #pragma once #include "gtkaccessible.h" -#include "gtkatcontextprivate.h" G_BEGIN_DECLS +/* < private > + * GtkAccessiblePlatformChange: + * @GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSABLE: whether the accessible has changed + * its focusable state + * @GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSED: whether the accessible has changed its + * focused state + * @GTK_ACCESSIBLE_PLATFORM_CHANGE_ACTIVE: whether the accessible has changed its + * active state + * + * Represents the various platform changes which can occur and are communicated + * using [method@Gtk.Accessible.platform_changed]. + */ +typedef enum { + GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSABLE = 1 << GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSABLE, + GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSED = 1 << GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSED, + GTK_ACCESSIBLE_PLATFORM_CHANGE_ACTIVE = 1 << GTK_ACCESSIBLE_PLATFORM_STATE_ACTIVE, +} GtkAccessiblePlatformChange; + +typedef enum { + GTK_ACCESSIBLE_CHILD_STATE_ADDED, + GTK_ACCESSIBLE_CHILD_STATE_REMOVED +} GtkAccessibleChildState; + +typedef enum { + GTK_ACCESSIBLE_CHILD_CHANGE_ADDED = 1 << GTK_ACCESSIBLE_CHILD_STATE_ADDED, + GTK_ACCESSIBLE_CHILD_CHANGE_REMOVED = 1 << GTK_ACCESSIBLE_CHILD_STATE_REMOVED +} GtkAccessibleChildChange; + const char * gtk_accessible_role_to_name (GtkAccessibleRole role, const char *domain); diff --git a/gtk/gtkatcontextprivate.h b/gtk/gtkatcontextprivate.h index 7808d133d3..c0acfc7793 100644 --- a/gtk/gtkatcontextprivate.h +++ b/gtk/gtkatcontextprivate.h @@ -22,6 +22,7 @@ #include "gtkatcontext.h" +#include "gtkaccessibleprivate.h" #include "gtkaccessibleattributesetprivate.h" G_BEGIN_DECLS @@ -80,16 +81,6 @@ typedef enum { GTK_ACCESSIBLE_STATE_CHANGE_SELECTED = 1 << GTK_ACCESSIBLE_STATE_SELECTED } GtkAccessibleStateChange; -typedef enum { - GTK_ACCESSIBLE_CHILD_STATE_ADDED, - GTK_ACCESSIBLE_CHILD_STATE_REMOVED -} GtkAccessibleChildState; - -typedef enum { - GTK_ACCESSIBLE_CHILD_CHANGE_ADDED = 1 << GTK_ACCESSIBLE_CHILD_STATE_ADDED, - GTK_ACCESSIBLE_CHILD_CHANGE_REMOVED = 1 << GTK_ACCESSIBLE_CHILD_STATE_REMOVED -} GtkAccessibleChildChange; - struct _GtkATContext { GObject parent_instance;