AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

a11y: Documentation and code style fixes

Browse Source
This commit is contained in:
Emmanuele Bassi 2023-02-02 15:44:15 +01:00
parent 3015b9f120
commit a0dff87c86
5 changed files with 195 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
gtk/a11y/gtkatspicontext.c
View File

@ -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,

51
gtk/gtkaccessible.c
View File

@ -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>
/*< 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`
*

222
gtk/gtkaccessible.h
View File

@ -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

29
gtk/gtkaccessibleprivate.h
View File

@ -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);

11
gtk/gtkatcontextprivate.h
View File

@ -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;