AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity
7702670d86
gtk2/gtk/gtkatcontextprivate.h

167 lines
9.4 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
/* gtkatcontextprivate.h: Private header for GtkATContext
*
* 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/>.
*/
#pragma once
#include "gtkatcontext.h"
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
#include "gtkaccessibleattributesetprivate.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
G_BEGIN_DECLS
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
typedef enum {
a11y: Resync with the ARIA spec Drop roles and properties that were deprecated in WAI-ARIA 1.1, and add new roles and properties defined in WAI-ARIA 1.2 and later. We also split the relationship properties into their own enumeration, so we can keep the GtkAccessibleProperty type more compact.
2020-07-15 18:08:37 +00:00
GTK_ACCESSIBLE_PROPERTY_CHANGE_AUTOCOMPLETE = 1 << GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE,
GTK_ACCESSIBLE_PROPERTY_CHANGE_DESCRIPTION = 1 << GTK_ACCESSIBLE_PROPERTY_DESCRIPTION,
GTK_ACCESSIBLE_PROPERTY_CHANGE_HAS_POPUP = 1 << GTK_ACCESSIBLE_PROPERTY_HAS_POPUP,
GTK_ACCESSIBLE_PROPERTY_CHANGE_KEY_SHORTCUTS = 1 << GTK_ACCESSIBLE_PROPERTY_KEY_SHORTCUTS,
GTK_ACCESSIBLE_PROPERTY_CHANGE_LABEL = 1 << GTK_ACCESSIBLE_PROPERTY_LABEL,
GTK_ACCESSIBLE_PROPERTY_CHANGE_LEVEL = 1 << GTK_ACCESSIBLE_PROPERTY_LEVEL,
GTK_ACCESSIBLE_PROPERTY_CHANGE_MODAL = 1 << GTK_ACCESSIBLE_PROPERTY_MODAL,
GTK_ACCESSIBLE_PROPERTY_CHANGE_MULTI_LINE = 1 << GTK_ACCESSIBLE_PROPERTY_MULTI_LINE,
GTK_ACCESSIBLE_PROPERTY_CHANGE_MULTI_SELECTABLE = 1 << GTK_ACCESSIBLE_PROPERTY_MULTI_SELECTABLE,
GTK_ACCESSIBLE_PROPERTY_CHANGE_ORIENTATION = 1 << GTK_ACCESSIBLE_PROPERTY_ORIENTATION,
GTK_ACCESSIBLE_PROPERTY_CHANGE_PLACEHOLDER = 1 << GTK_ACCESSIBLE_PROPERTY_PLACEHOLDER,
GTK_ACCESSIBLE_PROPERTY_CHANGE_READ_ONLY = 1 << GTK_ACCESSIBLE_PROPERTY_READ_ONLY,
GTK_ACCESSIBLE_PROPERTY_CHANGE_REQUIRED = 1 << GTK_ACCESSIBLE_PROPERTY_REQUIRED,
GTK_ACCESSIBLE_PROPERTY_CHANGE_ROLE_DESCRIPTION = 1 << GTK_ACCESSIBLE_PROPERTY_ROLE_DESCRIPTION,
GTK_ACCESSIBLE_PROPERTY_CHANGE_SORT = 1 << GTK_ACCESSIBLE_PROPERTY_SORT,
GTK_ACCESSIBLE_PROPERTY_CHANGE_VALUE_MAX = 1 << GTK_ACCESSIBLE_PROPERTY_VALUE_MAX,
GTK_ACCESSIBLE_PROPERTY_CHANGE_VALUE_MIN = 1 << GTK_ACCESSIBLE_PROPERTY_VALUE_MIN,
GTK_ACCESSIBLE_PROPERTY_CHANGE_VALUE_NOW = 1 << GTK_ACCESSIBLE_PROPERTY_VALUE_NOW,
GTK_ACCESSIBLE_PROPERTY_CHANGE_VALUE_TEXT = 1 << GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT
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
} GtkAccessiblePropertyChange;
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
typedef enum {
GTK_ACCESSIBLE_RELATION_CHANGE_ACTIVE_DESCENDANT = 1 << GTK_ACCESSIBLE_RELATION_ACTIVE_DESCENDANT,
GTK_ACCESSIBLE_RELATION_CHANGE_COL_COUNT = 1 << GTK_ACCESSIBLE_RELATION_COL_COUNT,
GTK_ACCESSIBLE_RELATION_CHANGE_COL_INDEX = 1 << GTK_ACCESSIBLE_RELATION_COL_INDEX,
GTK_ACCESSIBLE_RELATION_CHANGE_COL_INDEX_TEXT = 1 << GTK_ACCESSIBLE_RELATION_COL_INDEX_TEXT,
GTK_ACCESSIBLE_RELATION_CHANGE_COL_SPAN = 1 << GTK_ACCESSIBLE_RELATION_COL_SPAN,
GTK_ACCESSIBLE_RELATION_CHANGE_CONTROLS = 1 << GTK_ACCESSIBLE_RELATION_CONTROLS,
GTK_ACCESSIBLE_RELATION_CHANGE_DESCRIBED_BY = 1 << GTK_ACCESSIBLE_RELATION_DESCRIBED_BY,
GTK_ACCESSIBLE_RELATION_CHANGE_DETAILS = 1 << GTK_ACCESSIBLE_RELATION_DETAILS,
GTK_ACCESSIBLE_RELATION_CHANGE_ERROR_MESSAGE = 1 << GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE,
GTK_ACCESSIBLE_RELATION_CHANGE_FLOW_TO = 1 << GTK_ACCESSIBLE_RELATION_FLOW_TO,
GTK_ACCESSIBLE_RELATION_CHANGE_LABELLED_BY = 1 << GTK_ACCESSIBLE_RELATION_LABELLED_BY,
GTK_ACCESSIBLE_RELATION_CHANGE_OWNS = 1 << GTK_ACCESSIBLE_RELATION_OWNS,
GTK_ACCESSIBLE_RELATION_CHANGE_POS_IN_SET = 1 << GTK_ACCESSIBLE_RELATION_POS_IN_SET,
GTK_ACCESSIBLE_RELATION_CHANGE_ROW_COUNT = 1 << GTK_ACCESSIBLE_RELATION_ROW_COUNT,
GTK_ACCESSIBLE_RELATION_CHANGE_ROW_INDEX = 1 << GTK_ACCESSIBLE_RELATION_ROW_INDEX,
GTK_ACCESSIBLE_RELATION_CHANGE_ROW_INDEX_TEXT = 1 << GTK_ACCESSIBLE_RELATION_ROW_INDEX_TEXT,
GTK_ACCESSIBLE_RELATION_CHANGE_ROW_SPAN = 1 << GTK_ACCESSIBLE_RELATION_ROW_SPAN,
GTK_ACCESSIBLE_RELATION_CHANGE_SET_SIZE = 1 << GTK_ACCESSIBLE_RELATION_SET_SIZE
} GtkAccessibleRelationChange;
typedef enum {
GTK_ACCESSIBLE_STATE_CHANGE_BUSY = 1 << GTK_ACCESSIBLE_STATE_BUSY,
GTK_ACCESSIBLE_STATE_CHANGE_CHECKED = 1 << GTK_ACCESSIBLE_STATE_CHECKED,
GTK_ACCESSIBLE_STATE_CHANGE_DISABLED = 1 << GTK_ACCESSIBLE_STATE_DISABLED,
GTK_ACCESSIBLE_STATE_CHANGE_EXPANDED = 1 << GTK_ACCESSIBLE_STATE_EXPANDED,
GTK_ACCESSIBLE_STATE_CHANGE_HIDDEN = 1 << GTK_ACCESSIBLE_STATE_HIDDEN,
GTK_ACCESSIBLE_STATE_CHANGE_INVALID = 1 << GTK_ACCESSIBLE_STATE_INVALID,
GTK_ACCESSIBLE_STATE_CHANGE_PRESSED = 1 << GTK_ACCESSIBLE_STATE_PRESSED,
GTK_ACCESSIBLE_STATE_CHANGE_SELECTED = 1 << GTK_ACCESSIBLE_STATE_SELECTED
} GtkAccessibleStateChange;
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
typedef enum {
accessible: Add gtk_accessible_get_platform_state As a companion to go with the platform_change api, add a gtk_accessible_get_platform_state() function that can be used by backends to get the platform state. This is in preparation for making entries inherit their focus states from the text widget within.
2020-10-12 23:00:03 +00:00
GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSABLE,
GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSED,
} GtkAccessiblePlatformState;
typedef enum {
GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSABLE = 1 << GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSABLE,
GTK_ACCESSIBLE_PLATFORM_CHANGE_FOCUSED = 1 << GTK_ACCESSIBLE_PLATFORM_STATE_FOCUSED,
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
} GtkAccessiblePlatformChange;
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
struct _GtkATContext
{
GObject parent_instance;
GtkAccessibleRole accessible_role;
GtkAccessible *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
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 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;
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
GtkAccessibleStateChange updated_states;
GtkAccessiblePropertyChange updated_properties;
GtkAccessibleRelationChange updated_relations;
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
GtkAccessiblePlatformChange updated_platform;
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
};
struct _GtkATContextClass
{
GObjectClass parent_class;
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
void (* state_change) (GtkATContext *self,
GtkAccessibleStateChange changed_states,
GtkAccessiblePropertyChange changed_properties,
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
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);
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
void (* platform_change) (GtkATContext *self,
GtkAccessiblePlatformChange changed_platform);
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 (* bounds_change) (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
};
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);
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
void gtk_at_context_update (GtkATContext *self);
void gtk_at_context_set_accessible_state (GtkATContext *self,
GtkAccessibleState state,
GtkAccessibleValue *value);
gboolean gtk_at_context_has_accessible_state (GtkATContext *self,
GtkAccessibleState state);
GtkAccessibleValue * gtk_at_context_get_accessible_state (GtkATContext *self,
GtkAccessibleState state);
void gtk_at_context_set_accessible_property (GtkATContext *self,
GtkAccessibleProperty property,
GtkAccessibleValue *value);
gboolean gtk_at_context_has_accessible_property (GtkATContext *self,
GtkAccessibleProperty property);
GtkAccessibleValue * gtk_at_context_get_accessible_property (GtkATContext *self,
GtkAccessibleProperty property);
void gtk_at_context_set_accessible_relation (GtkATContext *self,
GtkAccessibleRelation property,
GtkAccessibleValue *value);
gboolean gtk_at_context_has_accessible_relation (GtkATContext *self,
GtkAccessibleRelation relation);
GtkAccessibleValue * gtk_at_context_get_accessible_relation (GtkATContext *self,
GtkAccessibleRelation relation);
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
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);
char * gtk_at_context_get_description (GtkATContext *self);
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: 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: 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 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
const char * gtk_accessible_property_get_attribute_name (GtkAccessibleProperty property);
const char * gtk_accessible_relation_get_attribute_name (GtkAccessibleRelation relation);
const char * gtk_accessible_state_get_attribute_name (GtkAccessibleState 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
G_END_DECLS
Reference in New Issue Copy Permalink