AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity
b9da74590b
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/>.
*/
/**
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* 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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* `GtkATContext` is an abstract class provided by GTK to communicate to
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
* platform-specific assistive technologies API.
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Each platform supported by GTK implements a `GtkATContext` subclass, and
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
* is responsible for updating the accessible state in response to state
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* changes in `GtkAccessible`.
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 "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
/**
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* GtkATContext:accessible-role: (attributes org.gtk.Property.get=gtk_at_context_get_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
*
* 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);
/**
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* GtkATContext:accessible: (attributes org.gtk.Property.get=gtk_at_context_get_accessible)
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* The `GtkAccessible` that created the `GtkATContext` instance.
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
*/
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:
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* The `GdkDisplay` for 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
*/
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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: the `GtkATContext`
a11y: Document GtkATContext::state-changed
2020-07-29 02:19:35 +00:00
*
* Emitted when the attributes of the accessible for the
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* `GtkATContext` instance change.
a11y: Document GtkATContext::state-changed
2020-07-29 02:19:35 +00:00
*/
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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @property: a `GtkAccessibleProperty`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the name of a `GtkAccessibleProperty`.
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
*
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @relation: a `GtkAccessibleRelation`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the name of a `GtkAccessibleRelation`.
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
*
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @state: a `GtkAccessibleState`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the name of a `GtkAccessibleState`.
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
*
* 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
}
/**
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* gtk_at_context_get_accessible: (attributes org.gtk.Method.get_property=accessible)
* @self: a `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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the `GtkAccessible` using this 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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Returns: (transfer none): a `GtkAccessible`
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
*/
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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
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
* @role: the accessible role for the context
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Sets the accessible role for the given `GtkATContext`.
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* This function can only be called if the `GtkATContext` is unrealized.
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
*/
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
/**
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* gtk_at_context_get_accessible_role: (attributes org.gtk.Method.get_property=accessible-role)
* @self: a `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
*
* Retrieves the accessible role of this context.
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Returns: a `GtkAccessibleRole`
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
*/
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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @display: a `GdkDisplay`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Sets the `GdkDisplay` used by the `GtkATContext`.
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* This function can only be called if the `GtkATContext` is
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
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the `GdkDisplay` used to create the context.
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Returns: (transfer none): a `GdkDisplay`
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
*/
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)
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @accessible_role: the accessible role used by the `GtkATContext`
* @accessible: the `GtkAccessible` implementation using the `GtkATContext`
* @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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Creates a new `GtkATContext` instance for the given 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
* 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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* The `GtkATContext` implementation being instantiated will depend on the
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
* platform.
*
atcontext: Convert docs
2021-02-28 00:43:26 +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";
a11y: Only spew help once Make GTK_A11Y=help only spew once, and avoid a warning when we do.
2021-01-05 16:15:33 +00:00
if (g_ascii_strcasecmp (gtk_a11y_env, "help") == 0)
{
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)
a11y: Only spew help once Make GTK_A11Y=help only spew once, and avoid a warning when we do.
2021-01-05 16:15:33 +00:00
g_print (" atspi - Use the AT-SPI accessibility backend\n");
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
#endif
a11y: Only spew help once Make GTK_A11Y=help only spew once, and avoid a warning when we do.
2021-01-05 16:15:33 +00:00
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");
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: Only spew help once Make GTK_A11Y=help only spew once, and avoid a warning when we do.
2021-01-05 16:15:33 +00:00
/* Short-circuit disabling the accessibility support */
if (g_ascii_strcasecmp (gtk_a11y_env, "none") == 0)
return 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
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)
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: the `GtkATContext` to clone
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
* @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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Clones the state of the given `GtkATContext`, using @role, @accessible,
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
* and @display.
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* If @self is realized, the returned `GtkATContext` will also be realized.
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Returns: (transfer full): the newly created `GtkATContext`
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
*/
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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @state: a `GtkAccessibleState`
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
* @value: (nullable): #GtkAccessibleValue
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Sets the @value for the given @state of a `GtkATContext`.
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 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @state: a `GtkAccessibleState`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Checks whether a `GtkATContext` has the given @state set.
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
*
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @state: a `GtkAccessibleState`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the value for the accessible state of a `GtkATContext`.
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
*
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @property: a `GtkAccessibleProperty`
* @value: (nullable): `GtkAccessibleValue`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Sets the @value for the given @property of a `GtkATContext`.
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 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @property: a `GtkAccessibleProperty`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Checks whether a `GtkATContext` has the given @property set.
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
*
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @property: a `GtkAccessibleProperty`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the value for the accessible property of a `GtkATContext`.
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
*
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @relation: a `GtkAccessibleRelation`
* @value: (nullable): `GtkAccessibleValue`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Sets the @value for the given @relation of a `GtkATContext`.
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 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @relation: a `GtkAccessibleRelation`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Checks whether a `GtkATContext` has the given @relation set.
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
*
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
* @relation: a `GtkAccessibleRelation`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the value for the accessible relation of a `GtkATContext`.
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
*
* 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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the accessible name of the `GtkATContext`.
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* This is a convenience function meant to be used by `GtkATContext` implementations.
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Returns: (transfer full): the label of the `GtkATContext`
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
*/
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:
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* @self: a `GtkATContext`
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Retrieves the accessible description of the `GtkATContext`.
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* This is a convenience function meant to be used by `GtkATContext` implementations.
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
*
atcontext: Convert docs
2021-02-28 00:43:26 +00:00
* Returns: (transfer full): the label of the `GtkATContext`
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
*/
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