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

1200 lines
36 KiB
C
Raw Normal View History

Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
/* gtkatcontext.c: Assistive technology context
*
* Copyright 2020 GNOME Foundation
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/**
* SECTION:gtkatcontext
* @Title: GtkATContext
* @Short_description: An object communicating to Assistive Technologies
*
* GtkATContext is an abstract class provided by GTK to communicate to
* platform-specific assistive technologies API.
*
* Each platform supported by GTK implements a #GtkATContext subclass, and
* is responsible for updating the accessible state in response to state
* changes in #GtkAccessible.
*/
#include "config.h"
#include "gtkatcontextprivate.h"
#include "gtkaccessiblevalueprivate.h"
a11y: Pass on platform changes Add an enum for 'platform changes' to the at context change notification mechanism. This will let us pass along things that ARIA considers 'platform state' such as focus or editability. The difference between the platform state and other ARIA states is that we don't keep the platform state separately in the at context - backends are expected to just query the widgets. This is just about avoiding notify listeners for change notification.
2020-10-12 17:05:43 +00:00
#include "gtkaccessibleprivate.h"
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
#include "gtkdebug.h"
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
#include "gtktestatcontextprivate.h"
#include "gtktypebuiltins.h"
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
#if defined(GDK_WINDOWING_X11) || defined(GDK_WINDOWING_WAYLAND)
#include "a11y/gtkatspicontextprivate.h"
#endif
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
G_DEFINE_ABSTRACT_TYPE (GtkATContext, gtk_at_context, G_TYPE_OBJECT)
enum
{
PROP_ACCESSIBLE_ROLE = 1,
PROP_ACCESSIBLE,
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
PROP_DISPLAY,
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
N_PROPS
};
a11y: Add change notification to GtkATContext Emit a ::state-change signal when state changes; this was already a vfunc, but we want to listen to state changes from the inspector too.
2020-07-28 02:51:34 +00:00
enum
{
STATE_CHANGE,
LAST_SIGNAL
};
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
static GParamSpec *obj_props[N_PROPS];
a11y: Add change notification to GtkATContext Emit a ::state-change signal when state changes; this was already a vfunc, but we want to listen to state changes from the inspector too.
2020-07-28 02:51:34 +00:00
static guint obj_signals[LAST_SIGNAL];
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
static void
gtk_at_context_finalize (GObject *gobject)
{
GtkATContext *self = GTK_AT_CONTEXT (gobject);
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
gtk_accessible_attribute_set_unref (self->properties);
gtk_accessible_attribute_set_unref (self->relations);
gtk_accessible_attribute_set_unref (self->states);
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
G_OBJECT_CLASS (gtk_at_context_parent_class)->finalize (gobject);
}
a11y: Unrealize ATContext on dispose
2020-11-04 16:40:59 +00:00
static void
gtk_at_context_dispose (GObject *gobject)
{
GtkATContext *self = GTK_AT_CONTEXT (gobject);
gtk_at_context_unrealize (self);
G_OBJECT_CLASS (gtk_at_context_parent_class)->dispose (gobject);
}
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
static void
gtk_at_context_set_property (GObject *gobject,
guint prop_id,
const GValue *value,
GParamSpec *pspec)
{
GtkATContext *self = GTK_AT_CONTEXT (gobject);
switch (prop_id)
{
case PROP_ACCESSIBLE_ROLE:
a11y: Allow updating role on unrealized contexts We can still change the accessible role if an ATContext instance is unrealized.
2020-11-04 14:35:16 +00:00
if (!self->realized)
self->accessible_role = g_value_get_enum (value);
else
g_critical ("The accessible role cannot be set on a realized AT context");
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
break;
case PROP_ACCESSIBLE:
self->accessible = g_value_get_object (value);
break;
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
case PROP_DISPLAY:
a11y: Rework ownership and lifetime of GtkATContext Now that GtkATContext is explicitly realized and unrealized, we should always create an instance at widget initialization time, and drop it during the widget finalization. This should make it easier to set up the initial accessible state of a widget during the instance initialization, as well as reduce the chances of accidental creation of GtkATContext instances during the destruction sequence.
2020-11-11 18:17:41 +00:00
gtk_at_context_set_display (self, g_value_get_object (value));
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
break;
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
}
}
static void
gtk_at_context_get_property (GObject *gobject,
guint prop_id,
GValue *value,
GParamSpec *pspec)
{
GtkATContext *self = GTK_AT_CONTEXT (gobject);
switch (prop_id)
{
case PROP_ACCESSIBLE_ROLE:
g_value_set_enum (value, self->accessible_role);
break;
case PROP_ACCESSIBLE:
g_value_set_object (value, self->accessible);
break;
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
case PROP_DISPLAY:
g_value_set_object (value, self->display);
break;
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
}
}
static void
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
gtk_at_context_real_state_change (GtkATContext *self,
GtkAccessibleStateChange changed_states,
a11y: Add relations API Since we split relation attributes from the generic properties, we need to add API for setting and retrieving their values.
2020-07-17 11:00:31 +00:00
GtkAccessiblePropertyChange changed_properties,
GtkAccessibleRelationChange changed_relations,
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
GtkAccessibleAttributeSet *states,
GtkAccessibleAttributeSet *properties,
GtkAccessibleAttributeSet *relations)
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
{
}
a11y: Add a separate vfunc for platform changes The state_change vfunc is becoming unwieldy. Lets move the platform changes to their own vfunc, as a start.
2020-10-19 15:19:57 +00:00
static void
gtk_at_context_real_platform_change (GtkATContext *self,
GtkAccessiblePlatformChange change)
{
}
a11y: Add bounds change api Add a way for GTK to pass bounds change information to the AT context.
2020-10-19 15:33:38 +00:00
static void
gtk_at_context_real_bounds_change (GtkATContext *self)
{
}
a11y: Add child state change to GtkATContext And the required private API in GtkAccessible to notify AT contexts of changes in the children list.
2020-10-15 13:49:14 +00:00
static void
gtk_at_context_real_child_change (GtkATContext *self,
GtkAccessibleChildChange change,
GtkAccessible *child)
{
}
a11y: Move ATContext to an explicit realization model We are doing too much work during the construction phase of the AT-SPI backend for GtkATContext. Instead of having the AtSpiContext register itself at construction time, let's add explicit realize and unrealize operations, and connect the ATContext realization to the rooting operation of a GtkWidget.
2020-10-19 16:44:50 +00:00
static void
gtk_at_context_real_realize (GtkATContext *self)
{
}
static void
gtk_at_context_real_unrealize (GtkATContext *self)
{
}
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
static void
gtk_at_context_class_init (GtkATContextClass *klass)
{
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
gobject_class->set_property = gtk_at_context_set_property;
gobject_class->get_property = gtk_at_context_get_property;
a11y: Unrealize ATContext on dispose
2020-11-04 16:40:59 +00:00
gobject_class->dispose = gtk_at_context_dispose;
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
gobject_class->finalize = gtk_at_context_finalize;
a11y: Move ATContext to an explicit realization model We are doing too much work during the construction phase of the AT-SPI backend for GtkATContext. Instead of having the AtSpiContext register itself at construction time, let's add explicit realize and unrealize operations, and connect the ATContext realization to the rooting operation of a GtkWidget.
2020-10-19 16:44:50 +00:00
klass->realize = gtk_at_context_real_realize;
klass->unrealize = gtk_at_context_real_unrealize;
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
klass->state_change = gtk_at_context_real_state_change;
a11y: Add a separate vfunc for platform changes The state_change vfunc is becoming unwieldy. Lets move the platform changes to their own vfunc, as a start.
2020-10-19 15:19:57 +00:00
klass->platform_change = gtk_at_context_real_platform_change;
a11y: Add bounds change api Add a way for GTK to pass bounds change information to the AT context.
2020-10-19 15:33:38 +00:00
klass->bounds_change = gtk_at_context_real_bounds_change;
a11y: Add child state change to GtkATContext And the required private API in GtkAccessible to notify AT contexts of changes in the children list.
2020-10-15 13:49:14 +00:00
klass->child_change = gtk_at_context_real_child_change;
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
/**
* GtkATContext:accessible-role:
*
* The accessible role used by the AT context.
*
* Depending on the given role, different states and properties can be
* set or retrieved.
*/
obj_props[PROP_ACCESSIBLE_ROLE] =
g_param_spec_enum ("accessible-role",
"Accessible Role",
"The accessible role of the AT context",
GTK_TYPE_ACCESSIBLE_ROLE,
a11y: Change default accessible role Only GtkWidget should use GTK_ACCESSIBLE_ROLE_WIDGET as its default accessible role; the default for GtkAccessible and GtkATContext should be GTK_ACCESSIBLE_ROLE_NONE, meaning "an element whose implicit native role semantics will not be mapped to the accessibility API", according to the WAI-ARIA specification.
2020-07-17 16:43:01 +00:00
GTK_ACCESSIBLE_ROLE_NONE,
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
G_PARAM_READWRITE |
a11y: Allow updating role on unrealized contexts We can still change the accessible role if an ATContext instance is unrealized.
2020-11-04 14:35:16 +00:00
G_PARAM_CONSTRUCT |
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
G_PARAM_STATIC_STRINGS);
/**
* GtkATContext:accessible:
*
* The #GtkAccessible that created the #GtkATContext instance.
*/
obj_props[PROP_ACCESSIBLE] =
g_param_spec_object ("accessible",
"Accessible",
"The accessible implementation",
GTK_TYPE_ACCESSIBLE,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS);
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
/**
* GtkATContext:display:
*
* The #GdkDisplay for the #GtkATContext.
*/
obj_props[PROP_DISPLAY] =
g_param_spec_object ("display",
"Display",
"The display connection",
GDK_TYPE_DISPLAY,
G_PARAM_READWRITE |
a11y: Rework ownership and lifetime of GtkATContext Now that GtkATContext is explicitly realized and unrealized, we should always create an instance at widget initialization time, and drop it during the widget finalization. This should make it easier to set up the initial accessible state of a widget during the instance initialization, as well as reduce the chances of accidental creation of GtkATContext instances during the destruction sequence.
2020-11-11 18:17:41 +00:00
G_PARAM_STATIC_STRINGS |
G_PARAM_EXPLICIT_NOTIFY);
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
a11y: Document GtkATContext::state-changed
2020-07-29 02:19:35 +00:00
/**
* GtkATContext::state-change:
* @self: the #GtkATContext
*
* Emitted when the attributes of the accessible for the
* #GtkATContext instance change.
*/
a11y: Add change notification to GtkATContext Emit a ::state-change signal when state changes; this was already a vfunc, but we want to listen to state changes from the inspector too.
2020-07-28 02:51:34 +00:00
obj_signals[STATE_CHANGE] =
g_signal_new ("state-change",
G_TYPE_FROM_CLASS (gobject_class),
G_SIGNAL_RUN_FIRST,
a11y: Simplify the ATContext::state-change signal We cannot pass all the data we pass to the virtual function, because the types are private, but the class and the signal are public API. The signal is just a notification, so we can decouple the virtual function (which stays the same, for internal types that implement the ATContext API contract) from the signal.
2020-08-25 15:34:04 +00:00
0,
a11y: Add change notification to GtkATContext Emit a ::state-change signal when state changes; this was already a vfunc, but we want to listen to state changes from the inspector too.
2020-07-28 02:51:34 +00:00
NULL, NULL,
NULL,
a11y: Simplify the ATContext::state-change signal We cannot pass all the data we pass to the virtual function, because the types are private, but the class and the signal are public API. The signal is just a notification, so we can decouple the virtual function (which stays the same, for internal types that implement the ATContext API contract) from the signal.
2020-08-25 15:34:04 +00:00
G_TYPE_NONE, 0);
a11y: Add change notification to GtkATContext Emit a ::state-change signal when state changes; this was already a vfunc, but we want to listen to state changes from the inspector too.
2020-07-28 02:51:34 +00:00
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
g_object_class_install_properties (gobject_class, N_PROPS, obj_props);
}
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
#define N_PROPERTIES (GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT + 1)
#define N_RELATIONS (GTK_ACCESSIBLE_RELATION_SET_SIZE + 1)
#define N_STATES (GTK_ACCESSIBLE_STATE_SELECTED + 1)
static const char *property_attrs[] = {
[GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE] = "autocomplete",
[GTK_ACCESSIBLE_PROPERTY_DESCRIPTION] = "description",
[GTK_ACCESSIBLE_PROPERTY_HAS_POPUP] = "haspopup",
[GTK_ACCESSIBLE_PROPERTY_KEY_SHORTCUTS] = "keyshortcuts",
[GTK_ACCESSIBLE_PROPERTY_LABEL] = "label",
[GTK_ACCESSIBLE_PROPERTY_LEVEL] = "level",
[GTK_ACCESSIBLE_PROPERTY_MODAL] = "modal",
[GTK_ACCESSIBLE_PROPERTY_MULTI_LINE] = "multiline",
[GTK_ACCESSIBLE_PROPERTY_MULTI_SELECTABLE] = "multiselectable",
[GTK_ACCESSIBLE_PROPERTY_ORIENTATION] = "orientation",
[GTK_ACCESSIBLE_PROPERTY_PLACEHOLDER] = "placeholder",
[GTK_ACCESSIBLE_PROPERTY_READ_ONLY] = "readonly",
[GTK_ACCESSIBLE_PROPERTY_REQUIRED] = "required",
[GTK_ACCESSIBLE_PROPERTY_ROLE_DESCRIPTION] = "roledescription",
[GTK_ACCESSIBLE_PROPERTY_SORT] = "sort",
[GTK_ACCESSIBLE_PROPERTY_VALUE_MAX] = "valuemax",
[GTK_ACCESSIBLE_PROPERTY_VALUE_MIN] = "valuemin",
[GTK_ACCESSIBLE_PROPERTY_VALUE_NOW] = "valuenow",
[GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT] = "valuetext",
};
a11y: Add testing API We want to test the accessibility API, as well as the implementation inside each widget. For that, we should expose an API that lets us verify that a GtkAccessible has a given role, as well as a given property. The API follows the pattern of other GTest API: - a macro to assert that a condition is respected - a function that prints out the error message in case of failure
2020-07-17 13:39:56 +00:00
/*< private >
* gtk_accessible_property_get_attribute_name:
* @property: a #GtkAccessibleProperty
*
* Retrieves the name of a #GtkAccessibleProperty.
*
* Returns: (transfer none): the name of the accessible property
*/
const char *
gtk_accessible_property_get_attribute_name (GtkAccessibleProperty property)
{
g_return_val_if_fail (property >= GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE &&
property <= GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT,
"<none>");
return property_attrs[property];
}
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
static const char *relation_attrs[] = {
[GTK_ACCESSIBLE_RELATION_ACTIVE_DESCENDANT] = "activedescendant",
[GTK_ACCESSIBLE_RELATION_COL_COUNT] = "colcount",
[GTK_ACCESSIBLE_RELATION_COL_INDEX] = "colindex",
[GTK_ACCESSIBLE_RELATION_COL_INDEX_TEXT] = "colindextext",
[GTK_ACCESSIBLE_RELATION_COL_SPAN] = "colspan",
[GTK_ACCESSIBLE_RELATION_CONTROLS] = "controls",
[GTK_ACCESSIBLE_RELATION_DESCRIBED_BY] = "describedby",
[GTK_ACCESSIBLE_RELATION_DETAILS] = "details",
[GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE] = "errormessage",
[GTK_ACCESSIBLE_RELATION_FLOW_TO] = "flowto",
[GTK_ACCESSIBLE_RELATION_LABELLED_BY] = "labelledby",
[GTK_ACCESSIBLE_RELATION_OWNS] = "owns",
[GTK_ACCESSIBLE_RELATION_POS_IN_SET] = "posinset",
[GTK_ACCESSIBLE_RELATION_ROW_COUNT] = "rowcount",
[GTK_ACCESSIBLE_RELATION_ROW_INDEX] = "rowindex",
[GTK_ACCESSIBLE_RELATION_ROW_INDEX_TEXT] = "rowindextext",
[GTK_ACCESSIBLE_RELATION_ROW_SPAN] = "rowspan",
[GTK_ACCESSIBLE_RELATION_SET_SIZE] = "setsize",
};
a11y: Add testing API We want to test the accessibility API, as well as the implementation inside each widget. For that, we should expose an API that lets us verify that a GtkAccessible has a given role, as well as a given property. The API follows the pattern of other GTest API: - a macro to assert that a condition is respected - a function that prints out the error message in case of failure
2020-07-17 13:39:56 +00:00
/*< private >
* gtk_accessible_relation_get_attribute_name:
* @relation: a #GtkAccessibleRelation
*
* Retrieves the name of a #GtkAccessibleRelation.
*
* Returns: (transfer none): the name of the accessible relation
*/
const char *
gtk_accessible_relation_get_attribute_name (GtkAccessibleRelation relation)
{
g_return_val_if_fail (relation >= GTK_ACCESSIBLE_RELATION_ACTIVE_DESCENDANT &&
relation <= GTK_ACCESSIBLE_RELATION_SET_SIZE,
"<none>");
return relation_attrs[relation];
}
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
static const char *state_attrs[] = {
[GTK_ACCESSIBLE_STATE_BUSY] = "busy",
[GTK_ACCESSIBLE_STATE_CHECKED] = "checked",
[GTK_ACCESSIBLE_STATE_DISABLED] = "disabled",
[GTK_ACCESSIBLE_STATE_EXPANDED] = "expanded",
[GTK_ACCESSIBLE_STATE_HIDDEN] = "hidden",
[GTK_ACCESSIBLE_STATE_INVALID] = "invalid",
[GTK_ACCESSIBLE_STATE_PRESSED] = "pressed",
[GTK_ACCESSIBLE_STATE_SELECTED] = "selected",
};
a11y: Add testing API We want to test the accessibility API, as well as the implementation inside each widget. For that, we should expose an API that lets us verify that a GtkAccessible has a given role, as well as a given property. The API follows the pattern of other GTest API: - a macro to assert that a condition is respected - a function that prints out the error message in case of failure
2020-07-17 13:39:56 +00:00
/*< private >
* gtk_accessible_state_get_attribute_name:
* @state: a #GtkAccessibleState
*
* Retrieves the name of a #GtkAccessibleState.
*
* Returns: (transfer none): the name of the accessible state
*/
const char *
gtk_accessible_state_get_attribute_name (GtkAccessibleState state)
{
g_return_val_if_fail (state >= GTK_ACCESSIBLE_STATE_BUSY &&
state <= GTK_ACCESSIBLE_STATE_SELECTED,
"<none>");
return state_attrs[state];
}
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
static void
gtk_at_context_init (GtkATContext *self)
{
a11y: Change default accessible role Only GtkWidget should use GTK_ACCESSIBLE_ROLE_WIDGET as its default accessible role; the default for GtkAccessible and GtkATContext should be GTK_ACCESSIBLE_ROLE_NONE, meaning "an element whose implicit native role semantics will not be mapped to the accessibility API", according to the WAI-ARIA specification.
2020-07-17 16:43:01 +00:00
self->accessible_role = GTK_ACCESSIBLE_ROLE_NONE;
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
self->properties =
a11y: Rework ownership and lifetime of GtkATContext Now that GtkATContext is explicitly realized and unrealized, we should always create an instance at widget initialization time, and drop it during the widget finalization. This should make it easier to set up the initial accessible state of a widget during the instance initialization, as well as reduce the chances of accidental creation of GtkATContext instances during the destruction sequence.
2020-11-11 18:17:41 +00:00
gtk_accessible_attribute_set_new (G_N_ELEMENTS (property_attrs),
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
property_attrs,
(GtkAccessibleAttributeDefaultFunc) gtk_accessible_value_get_default_for_property);
self->relations =
a11y: Rework ownership and lifetime of GtkATContext Now that GtkATContext is explicitly realized and unrealized, we should always create an instance at widget initialization time, and drop it during the widget finalization. This should make it easier to set up the initial accessible state of a widget during the instance initialization, as well as reduce the chances of accidental creation of GtkATContext instances during the destruction sequence.
2020-11-11 18:17:41 +00:00
gtk_accessible_attribute_set_new (G_N_ELEMENTS (relation_attrs),
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
relation_attrs,
(GtkAccessibleAttributeDefaultFunc) gtk_accessible_value_get_default_for_relation);
self->states =
a11y: Rework ownership and lifetime of GtkATContext Now that GtkATContext is explicitly realized and unrealized, we should always create an instance at widget initialization time, and drop it during the widget finalization. This should make it easier to set up the initial accessible state of a widget during the instance initialization, as well as reduce the chances of accidental creation of GtkATContext instances during the destruction sequence.
2020-11-11 18:17:41 +00:00
gtk_accessible_attribute_set_new (G_N_ELEMENTS (state_attrs),
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
state_attrs,
(GtkAccessibleAttributeDefaultFunc) gtk_accessible_value_get_default_for_state);
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
}
/**
* gtk_at_context_get_accessible:
* @self: a #GtkATContext
*
* Retrieves the #GtkAccessible using this context.
*
* Returns: (transfer none): a #GtkAccessible
*/
GtkAccessible *
gtk_at_context_get_accessible (GtkATContext *self)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
return self->accessible;
}
a11y: Rework ownership and lifetime of GtkATContext Now that GtkATContext is explicitly realized and unrealized, we should always create an instance at widget initialization time, and drop it during the widget finalization. This should make it easier to set up the initial accessible state of a widget during the instance initialization, as well as reduce the chances of accidental creation of GtkATContext instances during the destruction sequence.
2020-11-11 18:17:41 +00:00
/*< private >
* gtk_at_context_set_accessible_role:
* @self: a #GtkATContext
* @role: the accessible role for the context
*
* Sets the accessible role for the given #GtkATContext.
*
* This function can only be called if the #GtkATContext is unrealized.
*/
void
gtk_at_context_set_accessible_role (GtkATContext *self,
GtkAccessibleRole role)
{
g_return_if_fail (GTK_IS_AT_CONTEXT (self));
g_return_if_fail (!self->realized);
if (self->accessible_role == role)
return;
self->accessible_role = role;
g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_ACCESSIBLE_ROLE]);
}
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
/**
* gtk_at_context_get_accessible_role:
* @self: a #GtkATContext
*
* Retrieves the accessible role of this context.
*
* Returns: a #GtkAccessibleRole
*/
GtkAccessibleRole
gtk_at_context_get_accessible_role (GtkATContext *self)
{
a11y: Change default accessible role Only GtkWidget should use GTK_ACCESSIBLE_ROLE_WIDGET as its default accessible role; the default for GtkAccessible and GtkATContext should be GTK_ACCESSIBLE_ROLE_NONE, meaning "an element whose implicit native role semantics will not be mapped to the accessibility API", according to the WAI-ARIA specification.
2020-07-17 16:43:01 +00:00
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), GTK_ACCESSIBLE_ROLE_NONE);
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
return self->accessible_role;
}
a11y: Rework ownership and lifetime of GtkATContext Now that GtkATContext is explicitly realized and unrealized, we should always create an instance at widget initialization time, and drop it during the widget finalization. This should make it easier to set up the initial accessible state of a widget during the instance initialization, as well as reduce the chances of accidental creation of GtkATContext instances during the destruction sequence.
2020-11-11 18:17:41 +00:00
/*< private >
* gtk_at_context_set_display:
* @self: a #GtkATContext
* @display: a #GdkDisplay
*
* Sets the #GdkDisplay used by the #GtkATContext.
*
* This function can only be called if the #GtkATContext is
* not realized.
*/
void
gtk_at_context_set_display (GtkATContext *self,
GdkDisplay *display)
{
g_return_if_fail (GTK_IS_AT_CONTEXT (self));
g_return_if_fail (display == NULL || GDK_IS_DISPLAY (display));
if (self->display == display)
return;
if (self->realized)
return;
self->display = display;
g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_DISPLAY]);
}
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
/*< private >
* gtk_at_context_get_display:
* @self: a #GtkATContext
*
* Retrieves the #GdkDisplay used to create the context.
*
* Returns: (transfer none): a #GdkDisplay
*/
GdkDisplay *
gtk_at_context_get_display (GtkATContext *self)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
return self->display;
}
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
static const struct {
const char *name;
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
const char *env_name;
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
GtkATContext * (* create_context) (GtkAccessibleRole accessible_role,
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
GtkAccessible *accessible,
GdkDisplay *display);
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
} a11y_backends[] = {
#if defined(GDK_WINDOWING_WAYLAND)
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
{ "AT-SPI (Wayland)", "atspi", gtk_at_spi_create_context },
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
#endif
#if defined(GDK_WINDOWING_X11)
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
{ "AT-SPI (X11)", "atspi", gtk_at_spi_create_context },
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
#endif
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
{ "Test", "test", gtk_test_at_context_new },
{ NULL, NULL, NULL },
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
};
a11y: Make GtkATContext.create() public Implementations of the GtkAccessible interface should have a way to instantiate the appropriate GtkATContext.
2020-07-27 10:46:52 +00:00
/**
* gtk_at_context_create: (constructor)
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
* @accessible_role: the accessible role used by the #GtkATContext
* @accessible: the #GtkAccessible implementation using the #GtkATContext
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
* @display: the #GdkDisplay used by the #GtkATContext
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
*
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
* Creates a new #GtkATContext instance for the given accessible role,
* accessible instance, and display connection.
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
*
* The #GtkATContext implementation being instantiated will depend on the
* platform.
*
a11y: Make GtkATContext.create() public Implementations of the GtkAccessible interface should have a way to instantiate the appropriate GtkATContext.
2020-07-27 10:46:52 +00:00
* Returns: (nullable) (transfer full): the #GtkATContext
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
*/
GtkATContext *
gtk_at_context_create (GtkAccessibleRole accessible_role,
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
GtkAccessible *accessible,
GdkDisplay *display)
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
{
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
static const char *gtk_a11y_env;
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
if (gtk_a11y_env == NULL)
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
{
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
gtk_a11y_env = g_getenv ("GTK_A11Y");
if (gtk_a11y_env == NULL)
gtk_a11y_env = "0";
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
}
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
/* Short-circuit disabling the accessibility support */
if (g_ascii_strcasecmp (gtk_a11y_env, "none") == 0)
return NULL;
if (g_ascii_strcasecmp (gtk_a11y_env, "help") == 0)
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
{
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
g_print ("Supported arguments for GTK_A11Y environment variable:\n");
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
#if defined(GDK_WINDOWING_X11) || defined(GDK_WINDOWING_WAYLAND)
g_print (" atspi - Use the AT-SPI accessibility backend\n");
#endif
g_print (" test - Use the test accessibility backend\n");
g_print (" none - Disable the accessibility backend\n");
g_print (" help - Print this help\n\n");
g_print ("Other arguments will cause a warning and be ignored.\n");
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
}
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
GtkATContext *res = NULL;
for (guint i = 0; i < G_N_ELEMENTS (a11y_backends); i++)
{
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
if (a11y_backends[i].name == NULL)
break;
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
if (a11y_backends[i].create_context != NULL &&
(*gtk_a11y_env == '0' || g_ascii_strcasecmp (a11y_backends[i].env_name, gtk_a11y_env) == 0))
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
{
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
res = a11y_backends[i].create_context (accessible_role, accessible, display);
if (res != NULL)
break;
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
}
}
a11y: Consolidate accessibility environment variables Use a single environment variable for everything: - select the ATContext implementation - select the test ATContext - disable ATContext entirely We use the same pattern as GSK_RENDERER, GTK_DEBUG, etc. The documentation needs to be updated to include the environment variable.
2020-11-07 12:50:11 +00:00
if (*gtk_a11y_env != '0' && res == NULL)
g_warning ("Unrecognized accessibility backend \"%s\". Try GTK_A11Y=help", gtk_a11y_env);
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
/* Fall back to the test context, so we can get debugging data */
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
if (res == NULL)
a11y: Add a display to GtkATContext Since we need to check at run time what kind of AT context to use, we need a hook into the whole GDK backend machinery. The display connection seems to be the best choice, in this case, as it allows us to determine whether we're running on an X11 or Wayland system, and thus whether we should create a GtkAtSpiContext. This requires some surgery to fix the GtkATContext creation function, in order to include a GdkDisplay instance.
2020-09-29 17:40:44 +00:00
res = g_object_new (GTK_TYPE_TEST_AT_CONTEXT,
"accessible_role", accessible_role,
"accessible", accessible,
"display", display,
NULL);
a11y: Add dummy AT-SPI context Does not do anything, at the moment, but it's going to get filled out soon. The backend is selected depending on the platform being compiled in; since we're using AT-SPI on X11 and Wayland, and we don't have other accessibility implementations, we currently don't care about run time selection, but we're going to have to deal with that.
2020-09-29 17:18:36 +00:00
return res;
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
}
a11y: Add private API to clone a GtkATContext Some widgets might want to override GtkAccessible and create their own context in order to control the accessible role post-construction time. To avoid explicitly copying the existing state over from the original ATContext to the new one, we need a way to clone the context's state from inside the ATContext itself.
2020-11-10 14:19:32 +00:00
/*< private >
* gtk_at_context_clone: (constructor)
* @self: the #GtkATContext to clone
* @role: the accessible role of the clone, or %GTK_ACCESSIBLE_ROLE_NONE to
* use the same accessible role of @self
* @accessible: (nullable): the accessible creating the context, or %NULL to
* use the same #GtkAccessible of @self
* @display: (nullable): the display connection, or %NULL to use the same
* #GdkDisplay of @self
*
* Clones the state of the given #GtkATContext, using @role, @accessible,
* and @display.
*
* If @self is realized, the returned #GtkATContext will also be realized.
*
* Returns: (transfer full): the newly created #GtkATContext
*/
GtkATContext *
gtk_at_context_clone (GtkATContext *self,
GtkAccessibleRole role,
GtkAccessible *accessible,
GdkDisplay *display)
{
g_return_val_if_fail (self == NULL || GTK_IS_AT_CONTEXT (self), NULL);
g_return_val_if_fail (accessible == NULL || GTK_IS_ACCESSIBLE (accessible), NULL);
g_return_val_if_fail (display == NULL || GDK_IS_DISPLAY (display), NULL);
if (self != NULL && role == GTK_ACCESSIBLE_ROLE_NONE)
role = self->accessible_role;
if (self != NULL && accessible == NULL)
accessible = self->accessible;
if (self != NULL && display == NULL)
display = self->display;
GtkATContext *res = gtk_at_context_create (role, accessible, display);
if (self != NULL)
{
g_clear_pointer (&res->states, gtk_accessible_attribute_set_unref);
g_clear_pointer (&res->properties, gtk_accessible_attribute_set_unref);
g_clear_pointer (&res->relations, gtk_accessible_attribute_set_unref);
res->states = gtk_accessible_attribute_set_ref (self->states);
res->properties = gtk_accessible_attribute_set_ref (self->properties);
res->relations = gtk_accessible_attribute_set_ref (self->relations);
if (self->realized)
gtk_at_context_realize (res);
}
return res;
}
a11y: Move ATContext to an explicit realization model We are doing too much work during the construction phase of the AT-SPI backend for GtkATContext. Instead of having the AtSpiContext register itself at construction time, let's add explicit realize and unrealize operations, and connect the ATContext realization to the rooting operation of a GtkWidget.
2020-10-19 16:44:50 +00:00
gboolean
gtk_at_context_is_realized (GtkATContext *self)
{
return self->realized;
}
void
gtk_at_context_realize (GtkATContext *self)
{
if (self->realized)
return;
GTK_NOTE (A11Y, g_message ("Realizing AT context '%s'", G_OBJECT_TYPE_NAME (self)));
GTK_AT_CONTEXT_GET_CLASS (self)->realize (self);
self->realized = TRUE;
}
void
gtk_at_context_unrealize (GtkATContext *self)
{
if (!self->realized)
return;
GTK_NOTE (A11Y, g_message ("Unrealizing AT context '%s'", G_OBJECT_TYPE_NAME (self)));
GTK_AT_CONTEXT_GET_CLASS (self)->unrealize (self);
self->realized = FALSE;
}
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
/*< private >
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
* gtk_at_context_update:
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
* @self: a #GtkATContext
*
* Notifies the AT connected to this #GtkATContext that the accessible
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
* state and its properties have changed.
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
*/
void
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
gtk_at_context_update (GtkATContext *self)
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
{
g_return_if_fail (GTK_IS_AT_CONTEXT (self));
a11y: Move ATContext to an explicit realization model We are doing too much work during the construction phase of the AT-SPI backend for GtkATContext. Instead of having the AtSpiContext register itself at construction time, let's add explicit realize and unrealize operations, and connect the ATContext realization to the rooting operation of a GtkWidget.
2020-10-19 16:44:50 +00:00
if (!self->realized)
return;
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
/* There's no point in notifying of state changes if there weren't any */
if (self->updated_properties == 0 &&
self->updated_relations == 0 &&
a11y: Add a separate vfunc for platform changes The state_change vfunc is becoming unwieldy. Lets move the platform changes to their own vfunc, as a start.
2020-10-19 15:19:57 +00:00
self->updated_states == 0)
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
return;
a11y: Consolidate the attributes container While we have split the various attributes for convenience, there's no reason why we should have specialised data types for the attributes container object.
2020-07-17 11:49:59 +00:00
GtkAccessibleStateChange changed_states =
gtk_accessible_attribute_set_get_changed (self->states);
GtkAccessiblePropertyChange changed_properties =
gtk_accessible_attribute_set_get_changed (self->properties);
GtkAccessibleRelationChange changed_relations =
gtk_accessible_attribute_set_get_changed (self->relations);
a11y: Add relations API Since we split relation attributes from the generic properties, we need to add API for setting and retrieving their values.
2020-07-17 11:00:31 +00:00
a11y: Simplify the ATContext::state-change signal We cannot pass all the data we pass to the virtual function, because the types are private, but the class and the signal are public API. The signal is just a notification, so we can decouple the virtual function (which stays the same, for internal types that implement the ATContext API contract) from the signal.
2020-08-25 15:34:04 +00:00
GTK_AT_CONTEXT_GET_CLASS (self)->state_change (self,
changed_states, changed_properties, changed_relations,
self->states, self->properties, self->relations);
g_signal_emit (self, obj_signals[STATE_CHANGE], 0);
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
self->updated_properties = 0;
self->updated_relations = 0;
self->updated_states = 0;
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
}
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
/*< private >
a11y: Add testing API We want to test the accessibility API, as well as the implementation inside each widget. For that, we should expose an API that lets us verify that a GtkAccessible has a given role, as well as a given property. The API follows the pattern of other GTest API: - a macro to assert that a condition is respected - a function that prints out the error message in case of failure
2020-07-17 13:39:56 +00:00
* gtk_at_context_set_accessible_state:
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
* @self: a #GtkATContext
* @state: a #GtkAccessibleState
* @value: (nullable): #GtkAccessibleValue
*
* Sets the @value for the given @state of a #GtkATContext.
*
* If @value is %NULL, the state is unset.
*
a11y: GtkATContext.update_state() was renamed to update()
2020-08-05 14:05:06 +00:00
* This function will accumulate state changes until gtk_at_context_update()
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
* is called.
*/
void
gtk_at_context_set_accessible_state (GtkATContext *self,
GtkAccessibleState state,
GtkAccessibleValue *value)
{
g_return_if_fail (GTK_IS_AT_CONTEXT (self));
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
gboolean res = FALSE;
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
if (value != NULL)
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
res = gtk_accessible_attribute_set_add (self->states, state, value);
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
else
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
res = gtk_accessible_attribute_set_remove (self->states, state);
if (res)
self->updated_states |= (1 << state);
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
}
a11y: Add testing API We want to test the accessibility API, as well as the implementation inside each widget. For that, we should expose an API that lets us verify that a GtkAccessible has a given role, as well as a given property. The API follows the pattern of other GTest API: - a macro to assert that a condition is respected - a function that prints out the error message in case of failure
2020-07-17 13:39:56 +00:00
/*< private >
* gtk_at_context_has_accessible_state:
* @self: a #GtkATContext
* @state: a #GtkAccessibleState
*
* Checks whether a #GtkATContext has the given @state set.
*
* Returns: %TRUE, if the accessible state is set
*/
gboolean
gtk_at_context_has_accessible_state (GtkATContext *self,
GtkAccessibleState state)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), FALSE);
return gtk_accessible_attribute_set_contains (self->states, state);
}
a11y: Add API to retrieve accessible values We are going to use this for implementing ATContext subclasses, but also in the testing API.
2020-07-26 14:50:55 +00:00
/*< private >
* gtk_at_context_get_accessible_state:
* @self: a #GtkATContext
* @state: a #GtkAccessibleState
*
* Retrieves the value for the accessible state of a #GtkATContext.
*
* Returns: (transfer none): the value for the given state
*/
GtkAccessibleValue *
gtk_at_context_get_accessible_state (GtkATContext *self,
GtkAccessibleState state)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
return gtk_accessible_attribute_set_get_value (self->states, state);
}
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
/*< private >
* gtk_at_context_set_accessible_property:
* @self: a #GtkATContext
* @property: a #GtkAccessibleProperty
* @value: (nullable): #GtkAccessibleValue
*
* Sets the @value for the given @property of a #GtkATContext.
*
* If @value is %NULL, the property is unset.
*
a11y: GtkATContext.update_state() was renamed to update()
2020-08-05 14:05:06 +00:00
* This function will accumulate property changes until gtk_at_context_update()
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
* is called.
*/
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
void
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
gtk_at_context_set_accessible_property (GtkATContext *self,
GtkAccessibleProperty property,
GtkAccessibleValue *value)
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
{
g_return_if_fail (GTK_IS_AT_CONTEXT (self));
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
gboolean res = FALSE;
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
if (value != NULL)
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
res = gtk_accessible_attribute_set_add (self->properties, property, value);
Add accessible properties to GtkAccessible We propagate the accessible state and properties to each ATContext in the same virtual function, since they are functionally similar.
2020-07-13 14:51:39 +00:00
else
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
res = gtk_accessible_attribute_set_remove (self->properties, property);
if (res)
self->updated_properties |= (1 << property);
Add GtkATContext The ATContext type is meant to be used as the base class for implementations of the assistive technology API—the actual mechanism needed to communicate to components like the screen reader, or any other AT. Every time the widget state changes, the ATContext is meant to broadcast the state change; and every time the AT queries the state of a UI element, the ATContext is meant to provide that information. We also have a "test" ATContext implementation, which is meant to be used to write tests to verify that changes are propagated without requiring a whole desktop session.
2020-07-08 15:51:57 +00:00
}
a11y: Add relations API Since we split relation attributes from the generic properties, we need to add API for setting and retrieving their values.
2020-07-17 11:00:31 +00:00
a11y: Add testing API We want to test the accessibility API, as well as the implementation inside each widget. For that, we should expose an API that lets us verify that a GtkAccessible has a given role, as well as a given property. The API follows the pattern of other GTest API: - a macro to assert that a condition is respected - a function that prints out the error message in case of failure
2020-07-17 13:39:56 +00:00
/*< private >
* gtk_at_context_has_accessible_property:
* @self: a #GtkATContext
* @property: a #GtkAccessibleProperty
*
* Checks whether a #GtkATContext has the given @property set.
*
* Returns: %TRUE, if the accessible property is set
*/
gboolean
gtk_at_context_has_accessible_property (GtkATContext *self,
GtkAccessibleProperty property)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), FALSE);
return gtk_accessible_attribute_set_contains (self->properties, property);
}
a11y: Add API to retrieve accessible values We are going to use this for implementing ATContext subclasses, but also in the testing API.
2020-07-26 14:50:55 +00:00
/*< private >
* gtk_at_context_get_accessible_property:
* @self: a #GtkATContext
* @property: a #GtkAccessibleProperty
*
* Retrieves the value for the accessible property of a #GtkATContext.
*
* Returns: (transfer none): the value for the given property
*/
GtkAccessibleValue *
gtk_at_context_get_accessible_property (GtkATContext *self,
GtkAccessibleProperty property)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
return gtk_accessible_attribute_set_get_value (self->properties, property);
}
a11y: Add relations API Since we split relation attributes from the generic properties, we need to add API for setting and retrieving their values.
2020-07-17 11:00:31 +00:00
/*< private >
* gtk_at_context_set_accessible_relation:
* @self: a #GtkATContext
* @relation: a #GtkAccessibleRelation
* @value: (nullable): #GtkAccessibleValue
*
* Sets the @value for the given @relation of a #GtkATContext.
*
* If @value is %NULL, the relation is unset.
*
a11y: GtkATContext.update_state() was renamed to update()
2020-08-05 14:05:06 +00:00
* This function will accumulate relation changes until gtk_at_context_update()
a11y: Add relations API Since we split relation attributes from the generic properties, we need to add API for setting and retrieving their values.
2020-07-17 11:00:31 +00:00
* is called.
*/
void
gtk_at_context_set_accessible_relation (GtkATContext *self,
GtkAccessibleRelation relation,
GtkAccessibleValue *value)
{
g_return_if_fail (GTK_IS_AT_CONTEXT (self));
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
gboolean res = FALSE;
a11y: Add relations API Since we split relation attributes from the generic properties, we need to add API for setting and retrieving their values.
2020-07-17 11:00:31 +00:00
if (value != NULL)
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
res = gtk_accessible_attribute_set_add (self->relations, relation, value);
a11y: Add relations API Since we split relation attributes from the generic properties, we need to add API for setting and retrieving their values.
2020-07-17 11:00:31 +00:00
else
a11y: Do not notify of empty state changes If the ATContext state hasn't changed—for instance, if the accessible attributes have been set to their default value, or have been set to the same value—do not emit an accessible state change. State changes can be arbitrarily expensive, so we want to ensure that they are meaningful.
2020-08-05 17:05:46 +00:00
res = gtk_accessible_attribute_set_remove (self->relations, relation);
if (res)
self->updated_relations |= (1 << relation);
a11y: Add relations API Since we split relation attributes from the generic properties, we need to add API for setting and retrieving their values.
2020-07-17 11:00:31 +00:00
}
a11y: Add testing API We want to test the accessibility API, as well as the implementation inside each widget. For that, we should expose an API that lets us verify that a GtkAccessible has a given role, as well as a given property. The API follows the pattern of other GTest API: - a macro to assert that a condition is respected - a function that prints out the error message in case of failure
2020-07-17 13:39:56 +00:00
/*< private >
* gtk_at_context_has_accessible_relation:
* @self: a #GtkATContext
* @relation: a #GtkAccessibleRelation
*
* Checks whether a #GtkATContext has the given @relation set.
*
* Returns: %TRUE, if the accessible relation is set
*/
gboolean
gtk_at_context_has_accessible_relation (GtkATContext *self,
GtkAccessibleRelation relation)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), FALSE);
return gtk_accessible_attribute_set_contains (self->relations, relation);
}
a11y: Add API to retrieve accessible values We are going to use this for implementing ATContext subclasses, but also in the testing API.
2020-07-26 14:50:55 +00:00
/*< private >
* gtk_at_context_get_accessible_relation:
* @self: a #GtkATContext
* @relation: a #GtkAccessibleRelation
*
* Retrieves the value for the accessible relation of a #GtkATContext.
*
* Returns: (transfer none): the value for the given relation
*/
GtkAccessibleValue *
gtk_at_context_get_accessible_relation (GtkATContext *self,
GtkAccessibleRelation relation)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
return gtk_accessible_attribute_set_get_value (self->relations, relation);
}
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
a11y: Skip unlabelled structural roles If a structural role is left unlabelled, just leave it unnamed.
2020-11-11 17:50:42 +00:00
static gboolean
is_structural_role (GtkAccessibleRole role)
{
/* Keep the switch small while avoiding the compiler warning for
* unhandled enumeration values
*/
switch ((int) role)
{
case GTK_ACCESSIBLE_ROLE_FORM:
case GTK_ACCESSIBLE_ROLE_GROUP:
case GTK_ACCESSIBLE_ROLE_GENERIC:
a11y: Ignore more structural roles when computing labels These roles should not have a fallback name when explicitly unlabelled.
2020-11-12 14:38:01 +00:00
case GTK_ACCESSIBLE_ROLE_LANDMARK:
case GTK_ACCESSIBLE_ROLE_LIST_ITEM:
a11y: Skip unlabelled structural roles If a structural role is left unlabelled, just leave it unnamed.
2020-11-11 17:50:42 +00:00
case GTK_ACCESSIBLE_ROLE_REGION:
a11y: Ignore more structural roles when computing labels These roles should not have a fallback name when explicitly unlabelled.
2020-11-12 14:38:01 +00:00
case GTK_ACCESSIBLE_ROLE_SEARCH:
case GTK_ACCESSIBLE_ROLE_SEPARATOR:
a11y: Skip unlabelled structural roles If a structural role is left unlabelled, just leave it unnamed.
2020-11-11 17:50:42 +00:00
return TRUE;
default:
break;
}
return FALSE;
}
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
/* See the WAI-ARIA § 4.3, "Accessible Name and Description Computation" */
static void
gtk_at_context_get_name_accumulate (GtkATContext *self,
GPtrArray *names,
gboolean recurse)
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
{
GtkAccessibleValue *value = NULL;
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
if (gtk_accessible_attribute_set_contains (self->properties, GTK_ACCESSIBLE_PROPERTY_LABEL))
{
value = gtk_accessible_attribute_set_get_value (self->properties, GTK_ACCESSIBLE_PROPERTY_LABEL);
g_ptr_array_add (names, (char *) gtk_string_accessible_value_get (value));
}
if (recurse && gtk_accessible_attribute_set_contains (self->relations, GTK_ACCESSIBLE_RELATION_LABELLED_BY))
{
value = gtk_accessible_attribute_set_get_value (self->relations, GTK_ACCESSIBLE_RELATION_LABELLED_BY);
GList *list = gtk_reference_list_accessible_value_get (value);
a11y: Fix handling of LABELLED_BY relation There were several places where we were confusing GList and GSList and list->data and list->next, causing a crash in the accessible name computation for buttons with mnemonic labels.
2020-10-21 01:27:39 +00:00
for (GList *l = list; l != NULL; l = l->next)
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
{
GtkAccessible *rel = GTK_ACCESSIBLE (l->data);
GtkATContext *rel_context = gtk_accessible_get_at_context (rel);
gtk_at_context_get_name_accumulate (rel_context, names, FALSE);
}
}
GtkAccessibleRole role = gtk_at_context_get_accessible_role (self);
switch ((int) role)
{
case GTK_ACCESSIBLE_ROLE_RANGE:
{
int range_attrs[] = {
GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT,
GTK_ACCESSIBLE_PROPERTY_VALUE_NOW,
};
value = NULL;
for (int i = 0; i < G_N_ELEMENTS (range_attrs); i++)
{
if (gtk_accessible_attribute_set_contains (self->properties, range_attrs[i]))
{
value = gtk_accessible_attribute_set_get_value (self->properties, range_attrs[i]);
break;
}
}
if (value != NULL)
g_ptr_array_add (names, (char *) gtk_string_accessible_value_get (value));
}
break;
default:
break;
}
/* If there is no label or labelled-by attribute, hidden elements
* have no name
*/
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
if (gtk_accessible_attribute_set_contains (self->states, GTK_ACCESSIBLE_STATE_HIDDEN))
{
value = gtk_accessible_attribute_set_get_value (self->states, GTK_ACCESSIBLE_STATE_HIDDEN);
if (gtk_boolean_accessible_value_get (value))
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
return;
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
}
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
/* This fallback is in place only for unlabelled elements */
if (names->len != 0)
return;
a11y: Skip unlabelled structural roles If a structural role is left unlabelled, just leave it unnamed.
2020-11-11 17:50:42 +00:00
/* Ignore structural elements, namely: generic containers */
if (self->accessible != NULL && !is_structural_role (role))
a11y: Tweak name and description computation Instead of falling back to the role nick for both, fall back to the class name for the name, and to the empty string for the description. This makes labels show up in Accerciser the same way they did in GTK 3, and seems more useful to me than the alternative.
2020-10-19 18:58:34 +00:00
g_ptr_array_add (names, (char *)G_OBJECT_TYPE_NAME (self->accessible));
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
}
static void
gtk_at_context_get_description_accumulate (GtkATContext *self,
GPtrArray *labels,
gboolean recurse)
{
GtkAccessibleValue *value = NULL;
if (gtk_accessible_attribute_set_contains (self->properties, GTK_ACCESSIBLE_PROPERTY_DESCRIPTION))
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
{
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
value = gtk_accessible_attribute_set_get_value (self->properties, GTK_ACCESSIBLE_PROPERTY_DESCRIPTION);
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
g_ptr_array_add (labels, (char *) gtk_string_accessible_value_get (value));
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
}
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
if (recurse && gtk_accessible_attribute_set_contains (self->relations, GTK_ACCESSIBLE_RELATION_DESCRIBED_BY))
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
{
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
value = gtk_accessible_attribute_set_get_value (self->relations, GTK_ACCESSIBLE_RELATION_DESCRIBED_BY);
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
atcontext: labelled-by has a reference list This is unclear - our docs state that all the relations have value type reference, but in fact they all have value type reference list.
2020-10-10 16:12:03 +00:00
GList *list = gtk_reference_list_accessible_value_get (value);
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
for (GList *l = list; l != NULL; l = l->data)
{
GtkAccessible *rel = GTK_ACCESSIBLE (l->data);
GtkATContext *rel_context = gtk_accessible_get_at_context (rel);
gtk_at_context_get_description_accumulate (rel_context, labels, FALSE);
}
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
}
GtkAccessibleRole role = gtk_at_context_get_accessible_role (self);
switch ((int) role)
{
case GTK_ACCESSIBLE_ROLE_RANGE:
{
int range_attrs[] = {
GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT,
GTK_ACCESSIBLE_PROPERTY_VALUE_NOW,
};
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
value = NULL;
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
for (int i = 0; i < G_N_ELEMENTS (range_attrs); i++)
{
if (gtk_accessible_attribute_set_contains (self->properties, range_attrs[i]))
{
value = gtk_accessible_attribute_set_get_value (self->properties, range_attrs[i]);
break;
}
}
if (value != NULL)
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
g_ptr_array_add (labels, (char *) gtk_string_accessible_value_get (value));
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
}
break;
default:
break;
}
a11y: Tweak name and description computation Instead of falling back to the role nick for both, fall back to the class name for the name, and to the empty string for the description. This makes labels show up in Accerciser the same way they did in GTK 3, and seems more useful to me than the alternative.
2020-10-19 18:58:34 +00:00
/* If there is no description or described-by attribute, hidden elements
* have no description
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
*/
if (gtk_accessible_attribute_set_contains (self->states, GTK_ACCESSIBLE_STATE_HIDDEN))
{
value = gtk_accessible_attribute_set_get_value (self->states, GTK_ACCESSIBLE_STATE_HIDDEN);
if (gtk_boolean_accessible_value_get (value))
return;
}
}
/*< private >
* gtk_at_context_get_name:
* @self: a #GtkATContext
*
* Retrieves the accessible name of the #GtkATContext.
*
* This is a convenience function meant to be used by #GtkATContext implementations.
*
* Returns: (transfer full): the label of the #GtkATContext
*/
char *
gtk_at_context_get_name (GtkATContext *self)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
GPtrArray *names = g_ptr_array_new ();
gtk_at_context_get_name_accumulate (self, names, TRUE);
if (names->len == 0)
{
g_ptr_array_unref (names);
return g_strdup ("");
}
GString *res = g_string_new ("");
g_string_append (res, g_ptr_array_index (names, 0));
for (guint i = 1; i < names->len; i++)
{
g_string_append (res, " ");
g_string_append (res, g_ptr_array_index (names, i));
}
g_ptr_array_unref (names);
return g_string_free (res, FALSE);
}
/*< private >
* gtk_at_context_get_description:
* @self: a #GtkATContext
*
* Retrieves the accessible description of the #GtkATContext.
*
* This is a convenience function meant to be used by #GtkATContext implementations.
*
* Returns: (transfer full): the label of the #GtkATContext
*/
char *
gtk_at_context_get_description (GtkATContext *self)
{
g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
GPtrArray *names = g_ptr_array_new ();
gtk_at_context_get_description_accumulate (self, names, TRUE);
if (names->len == 0)
{
g_ptr_array_unref (names);
return g_strdup ("");
}
GString *res = g_string_new ("");
g_string_append (res, g_ptr_array_index (names, 0));
for (guint i = 1; i < names->len; i++)
{
g_string_append (res, " ");
g_string_append (res, g_ptr_array_index (names, i));
}
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
g_ptr_array_unref (names);
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
a11y: Rework accessible name/description computation The ARIA spec determines the name and description of accessible elements in a more complex way that simply mapping to a single property; instead, it will chain up multiple definitions (if it finds them). For instance, let's assume we have a button that saves a file selected from a file selection widget; the widgets have the following attributes: - the file selection widget has a "label" attribute set to the selected file, e.g. "Final paper.pdf" - the "download" button has a "label" attribute set to the "Download" string - the "download" button has a "labelled-by" attribute set to reference the file selection widget The ARIA spec says that the accessible name of the "Download" button should be computed as "Download Final paper.pdf". The algorithm defined in section 4.3 of the WAI-ARIA specification applies to both accessible names (using the "label" and "labelled-by" attributes), and to accessible descriptions (using the "description" and "described-by" attributes).
2020-10-16 16:03:50 +00:00
return g_string_free (res, FALSE);
a11y: Compute the label for a GtkATContext The ARIA spec defines the mechanism for determining the name of an accessible element—see §4.3 of the WAI-ARIA spec. We follow the specification as much as it makes sense for GTK to do so: 1. if the element is hidden, return an empty string 1. if the element has a labelled-by relation set, retrieve the label of the related element 2. if the element has a label property set, use the value of the property 3. if neither labelled-by nor label attributes are set, we use the role to compute the name: - for a `range` role, we return the contents of the value of the `value-text` or `value-now` properties - for any other role, we return a textual representation of the GtkAccessibleRole enumeration value
2020-10-09 20:23:19 +00:00
}
a11y: Pass on platform changes Add an enum for 'platform changes' to the at context change notification mechanism. This will let us pass along things that ARIA considers 'platform state' such as focus or editability. The difference between the platform state and other ARIA states is that we don't keep the platform state separately in the at context - backends are expected to just query the widgets. This is just about avoiding notify listeners for change notification.
2020-10-12 17:05:43 +00:00
void
gtk_at_context_platform_changed (GtkATContext *self,
GtkAccessiblePlatformChange change)
{
a11y: Move ATContext to an explicit realization model We are doing too much work during the construction phase of the AT-SPI backend for GtkATContext. Instead of having the AtSpiContext register itself at construction time, let's add explicit realize and unrealize operations, and connect the ATContext realization to the rooting operation of a GtkWidget.
2020-10-19 16:44:50 +00:00
if (!self->realized)
return;
a11y: Add a separate vfunc for platform changes The state_change vfunc is becoming unwieldy. Lets move the platform changes to their own vfunc, as a start.
2020-10-19 15:19:57 +00:00
GTK_AT_CONTEXT_GET_CLASS (self)->platform_change (self, change);
a11y: Pass on platform changes Add an enum for 'platform changes' to the at context change notification mechanism. This will let us pass along things that ARIA considers 'platform state' such as focus or editability. The difference between the platform state and other ARIA states is that we don't keep the platform state separately in the at context - backends are expected to just query the widgets. This is just about avoiding notify listeners for change notification.
2020-10-12 17:05:43 +00:00
}
a11y: Add bounds change api Add a way for GTK to pass bounds change information to the AT context.
2020-10-19 15:33:38 +00:00
void
gtk_at_context_bounds_changed (GtkATContext *self)
{
a11y: Move ATContext to an explicit realization model We are doing too much work during the construction phase of the AT-SPI backend for GtkATContext. Instead of having the AtSpiContext register itself at construction time, let's add explicit realize and unrealize operations, and connect the ATContext realization to the rooting operation of a GtkWidget.
2020-10-19 16:44:50 +00:00
if (!self->realized)
return;
a11y: Add bounds change api Add a way for GTK to pass bounds change information to the AT context.
2020-10-19 15:33:38 +00:00
GTK_AT_CONTEXT_GET_CLASS (self)->bounds_change (self);
}
a11y: Add child state change to GtkATContext And the required private API in GtkAccessible to notify AT contexts of changes in the children list.
2020-10-15 13:49:14 +00:00
void
gtk_at_context_child_changed (GtkATContext *self,
GtkAccessibleChildChange change,
GtkAccessible *child)
{
a11y: Move ATContext to an explicit realization model We are doing too much work during the construction phase of the AT-SPI backend for GtkATContext. Instead of having the AtSpiContext register itself at construction time, let's add explicit realize and unrealize operations, and connect the ATContext realization to the rooting operation of a GtkWidget.
2020-10-19 16:44:50 +00:00
if (!self->realized)
return;
a11y: Add child state change to GtkATContext And the required private API in GtkAccessible to notify AT contexts of changes in the children list.
2020-10-15 13:49:14 +00:00
GTK_AT_CONTEXT_GET_CLASS (self)->child_change (self, change, child);
}
Reference in New Issue Copy Permalink