summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEmmanuele Bassi <ebassi@gnome.org>2023-02-02 15:44:15 +0100
committerEmmanuele Bassi <ebassi@gnome.org>2023-02-03 11:49:17 +0100
commita0dff87c867a1ba3a42fdddede4e8f760167ceff (patch)
tree9bd26b80e17683345882c2b8015dc31d8431daeb
parent3015b9f12071879dd9b071287c21b25bc030cb60 (diff)
downloadgtk+-a0dff87c867a1ba3a42fdddede4e8f760167ceff.tar.gz
a11y: Documentation and code style fixes
-rw-r--r--gtk/a11y/gtkatspicontext.c27
-rw-r--r--gtk/gtkaccessible.c51
-rw-r--r--gtk/gtkaccessible.h216
-rw-r--r--gtk/gtkaccessibleprivate.h29
-rw-r--r--gtk/gtkatcontextprivate.h11
5 files changed, 192 insertions, 142 deletions
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
+ *
+ * This function returns `NULL` for top level widgets
+ *
+ * Returns: (transfer none) (nullable): the accessible parent
*
- * Returns: (transfer none): the parent `GtkAccessible`, which can not be %NULL
+ * 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>
+/*< 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>
+/*< 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
+ *
+ * The common interface for accessible objects.
*
- * Represents the various platform changes which can occur and are communicated
- * using [method@Gtk.Accessible.platform_changed].
+ * 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);
+void gtk_accessible_reset_state (GtkAccessible *self,
+ GtkAccessibleState state);
GDK_AVAILABLE_IN_ALL
-void gtk_accessible_reset_property (GtkAccessible *self,
- GtkAccessibleProperty property);
+void gtk_accessible_reset_property (GtkAccessible *self,
+ GtkAccessibleProperty property);
GDK_AVAILABLE_IN_ALL
-void gtk_accessible_reset_relation (GtkAccessible *self,
- GtkAccessibleRelation relation);
+void gtk_accessible_reset_relation (GtkAccessible *self,
+ GtkAccessibleRelation relation);
GDK_AVAILABLE_IN_ALL
-void gtk_accessible_state_init_value (GtkAccessibleState state,
- GValue *value);
+void gtk_accessible_state_init_value (GtkAccessibleState state,
+ GValue *value);
GDK_AVAILABLE_IN_ALL
-void gtk_accessible_property_init_value (GtkAccessibleProperty property,
- GValue *value);
+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;