+2006-01-09 Bill Haneman <billh@gnome.org>
+
+ * configure.in: Removed po/Makefile.in inclusion, we do not need
+ it. Revved to 1.7.0.
+
+ * idl/
+
+ * libspi/spi_event.c:
+
+ * cspi/spi-private.h:
+ (cspi_role_from_spi_role): Expose this adapter method, since
+ we need it in the bridge (see below).
+
+ * cspi/spi.h:
+ (AccessibleEvent_getSourceName):
+ (AccessibleEvent_getSourceRole):
+ (AccessibleEvent_getSourceApplication):
+ (AccessibleEvent_getSourceDetails):
+
+ * cspi/spi_accessible.c: Use cspi_role_from_spi_role.
+ Make use of the new EventDetails struct in events, if present.
+ ():
+ ():
+ ():
+ ():
+ ():
+ (AccessibleEvent_getSourceName)
+ (AccessibleEvent_getSourceRole)
+ (AccessibleEvent_getSourceApplication)
+ (AccessibleEvent_getSourceDetails): Implement the newly exposed
+ methods from spi.h.
+
+ * atk-bridge/bridge.c:
+ Use new prototyped for init_any methods.
+ (spi_atk_bridge_init_nil, spi_atk_bridge_init_object)
+ (spi_atk_bridge_init_string, spi_atk_bridge_init_rect)
+ (spi_atk_bridge_init_base): Wrappers
+ for spi_init_any_* methods, due to refactor; include extended
+ information in the Accessibility_EventDetails struct, for instance
+ accessible-name, Role, and containing Application.
+
+ * registryd/registry.c:
+
2006-01-09 Kjartan Maraas <kmaraas@gnome.org>
* configure.in: Generate po/Makefile.in
+What's new in at-spi-1.7.0:
+
+* NEW API:
+
+ idl:
+ cspi:
+
+* BUGFIXES:
+
+
What's new in at-spi-1.6.5:
* Fixed some discrepancies in event listener deregistration, improves
README
-at-spi version 1.6.5
+at-spi version 1.7.0
*** Welcome to the Gnome Accessibility Project! ***
guint n_param_values,
const GValue *param_values,
gpointer data);
+
+static void spi_atk_bridge_init_nil (CORBA_any *any,
+ AtkObject *obj);
+static void spi_atk_bridge_init_object (CORBA_any *any,
+ AtkObject *obj,
+ CORBA_Object *c_obj);
+static void spi_atk_bridge_init_string (CORBA_any *any,
+ AtkObject *obj,
+ gchar **string);
+static void spi_atk_bridge_init_rect (CORBA_any *any,
+ AtkObject *obj,
+ AtkRectangle *rect);
+
static gboolean
spi_atk_bridge_window_event_listener (GSignalInvocationHint *signal_hint,
guint n_param_values,
{
SpiAccessible *source;
Accessibility_Event e;
-
+ const gchar *name = atk_object_get_name (object);
+
source = spi_accessible_new (object);
-
+
+ CORBA_exception_init (&ev);
+
e.type = "focus:";
e.source = BONOBO_OBJREF (source);
e.detail1 = 0;
e.detail2 = 0;
- spi_init_any_nil (&e.any_data);
-
- CORBA_exception_init (&ev);
- Accessibility_Registry_notifyEvent (spi_atk_bridge_get_registry (), &e, &ev);
+ spi_atk_bridge_init_nil (&e.any_data, object);
+ if (BONOBO_EX (&ev))
+ registry_died = TRUE;
+ else
+ Accessibility_Registry_notifyEvent (spi_atk_bridge_get_registry (),
+ &e, &ev);
if (BONOBO_EX (&ev))
registry_died = TRUE;
SpiAccessible *source;
AtkObject *aobject;
Accessibility_Registry registry;
+ const gchar *name;
#ifdef SPI_BRIDGE_DEBUG
CORBA_string s;
#endif
source = NULL;
DBG (0, g_warning ("received property-change event from non-AtkImplementor"));
}
-
+ name = atk_object_get_name (aobject);
if (source)
{
e.type = g_strdup_vprintf (format, args);
e.detail1 = detail1;
e.detail2 = detail2;
if (any) e.any_data = *any;
- else spi_init_any_nil (&e.any_data);
+ else spi_atk_bridge_init_nil (&e.any_data, aobject);
#ifdef SPI_BRIDGE_DEBUG
s = Accessibility_Accessible__get_name (BONOBO_OBJREF (source), &ev);
SpiAccessible *s_ao = NULL;
CORBA_Object c_obj;
gint i;
+ const gchar *name = NULL;
#ifdef SPI_BRIDGE_DEBUG
GSignalQuery signal_query;
- const gchar *name;
+ const gchar *signame;
const gchar *s, *s2;
g_signal_query (signal_hint->signal_id, &signal_query);
- name = signal_query.signal_name;
+ signame = signal_query.signal_name;
s2 = g_type_name (G_OBJECT_TYPE (g_value_get_object (param_values + 0)));
s = atk_object_get_name (ATK_OBJECT (g_value_get_object (param_values + 0)));
values = (AtkPropertyValues*) g_value_get_pointer (param_values + 1);
DBG (2, g_message ("Received (property) signal %s:%s:%s from object %s (gail %s)\n",
- g_type_name (signal_query.itype), name, values->property_name, s, s2));
+ g_type_name (signal_query.itype), signame, values->property_name, s, s2));
#endif
gobject = g_value_get_object (param_values + 0);
+ name = atk_object_get_name (ATK_OBJECT (gobject));
values = (AtkPropertyValues*) g_value_get_pointer (param_values + 1);
prop_name = values->property_name;
if (strcmp (prop_name, "accessible-name") == 0)
{
- sp = atk_object_get_name (ATK_OBJECT (gobject));
- spi_init_any_string (&any, (gchar **)&sp);
+ spi_atk_bridge_init_string (&any,
+ ATK_OBJECT (gobject),
+ (gchar **)&name);
}
else if (strcmp (prop_name, "accessible-description") == 0)
{
sp = atk_object_get_description (ATK_OBJECT (gobject));
- spi_init_any_string (&any, (gchar **)&sp);
+ spi_atk_bridge_init_string (&any,
+ ATK_OBJECT (gobject),
+ (gchar **)&sp);
}
else if (strcmp (prop_name, "accessible-parent") == 0)
{
{
s_ao = spi_accessible_new (ao);
c_obj = BONOBO_OBJREF (s_ao);
- spi_init_any_object (&any, &c_obj);
+ spi_atk_bridge_init_object (&any,
+ ATK_OBJECT (gobject),
+ &c_obj);
}
else
{
- spi_init_any_nil (&any);
+ spi_atk_bridge_init_nil (&any,
+ ATK_OBJECT (gobject));
}
}
else if (strcmp (prop_name, "accessible-table-summary") == 0)
{
s_ao = spi_accessible_new (ao);
c_obj = BONOBO_OBJREF (s_ao);
- spi_init_any_object (&any, &c_obj);
+ spi_atk_bridge_init_object (&any,
+ ATK_OBJECT (gobject),
+ &c_obj);
}
else
{
- spi_init_any_nil (&any);
+ spi_atk_bridge_init_nil (&any,
+ ATK_OBJECT (gobject));
}
}
else if (strcmp (prop_name, "accessible-table-column-header") == 0)
{
s_ao = spi_accessible_new (ao);
c_obj = BONOBO_OBJREF (s_ao);
- spi_init_any_object (&any, &c_obj);
+ spi_atk_bridge_init_object (&any,
+ ATK_OBJECT (gobject),
+ &c_obj);
}
else
{
- spi_init_any_nil (&any);
+ spi_atk_bridge_init_nil (&any, ATK_OBJECT (gobject));
}
}
else if (strcmp (prop_name, "accessible-table-row-header") == 0)
{
s_ao = spi_accessible_new (ao);
c_obj = BONOBO_OBJREF (s_ao);
- spi_init_any_object (&any, &c_obj);
+ spi_atk_bridge_init_object (&any, ATK_OBJECT (gobject), &c_obj);
}
else
{
- spi_init_any_nil (&any);
+ spi_atk_bridge_init_nil (&any, ATK_OBJECT (gobject));
}
}
else if (strcmp (prop_name, "accessible-table-row-description") == 0)
{
i = g_value_get_int (&(values->new_value));
sp = atk_table_get_row_description (ATK_TABLE (gobject), i);
- spi_init_any_string (&any, (gchar **)&sp);
+ spi_atk_bridge_init_string (&any, ATK_OBJECT (gobject),
+ (gchar **)&sp);
}
else if (strcmp (prop_name, "accessible-table-column-description") == 0)
{
i = g_value_get_int (&(values->new_value));
sp = atk_table_get_column_description (ATK_TABLE (gobject), i);
- spi_init_any_string (&any, (gchar **)&sp);
+ spi_atk_bridge_init_string (&any, ATK_OBJECT (gobject),
+ (gchar **)&sp);
}
else if (strcmp (prop_name, "accessible-table-caption-object") == 0)
{
ao = atk_table_get_caption (ATK_TABLE (gobject));
sp = atk_object_get_name (ao);
- spi_init_any_string (&any, (gchar **)&sp);
+ spi_atk_bridge_init_string (&any, ATK_OBJECT (gobject),
+ (gchar **)&sp);
}
else
{
- spi_init_any_nil (&any);
+ spi_atk_bridge_init_nil (&any, ATK_OBJECT (gobject));
}
spi_atk_emit_eventv (gobject, 0, 0, &any,
detail1 = atk_object_get_index_in_parent (ao);
s_ao = spi_accessible_new (ao);
c_obj = BONOBO_OBJREF (s_ao);
- spi_init_any_object (&any, &c_obj);
+ spi_atk_bridge_init_object (&any, ATK_OBJECT (gobject), &c_obj);
}
else if (signal_query.signal_id == atk_signal_link_selected)
{
if (G_VALUE_TYPE (param_values + 1) == G_TYPE_INT)
detail1 = g_value_get_int (param_values + 1);
- spi_init_any_nil (&any);
+ spi_atk_bridge_init_nil (&any, ATK_OBJECT (gobject));
}
else if (signal_query.signal_id == atk_signal_bounds_changed)
{
if (G_VALUE_HOLDS_BOXED (param_values + 1))
atk_rect = g_value_get_boxed (param_values + 1);
- spi_init_any_rect (&any, atk_rect);
+ spi_atk_bridge_init_rect (&any, ATK_OBJECT (gobject), atk_rect);
}
else if ((signal_query.signal_id == atk_signal_children_changed) && gobject)
{
{
s_ao = spi_accessible_new (ao);
c_obj = BONOBO_OBJREF (s_ao);
- spi_init_any_object (&any, &c_obj);
+ spi_atk_bridge_init_object (&any, ATK_OBJECT (gobject), &c_obj);
g_object_unref (ao);
}
else
{
- spi_init_any_nil (&any);
+ spi_atk_bridge_init_nil (&any, ATK_OBJECT (gobject));
}
}
else
sp = atk_text_get_text (ATK_TEXT (gobject),
detail1,
detail1+detail2);
- spi_init_any_string (&any, &sp);
+ spi_atk_bridge_init_string (&any, ATK_OBJECT (gobject),
+ (gchar **) &sp);
}
else if (signal_query.signal_id == atk_signal_text_selection_changed)
{
/* Return NULL as the selected string */
- spi_init_any_nil (&any);
+ spi_atk_bridge_init_nil (&any, ATK_OBJECT (gobject));
}
else
{
- spi_init_any_nil (&any);
+ spi_atk_bridge_init_nil (&any, ATK_OBJECT (gobject));
}
}
gobject = g_value_get_object (param_values + 0);
s = atk_object_get_name (ATK_OBJECT (gobject));
- spi_init_any_string (&any, (char **) &s);
+ spi_atk_bridge_init_string (&any, ATK_OBJECT (gobject), (gchar **) &s);
spi_atk_emit_eventv (gobject, 0, 0, &any,
"window:%s", name);
stateset = atk_object_ref_state_set (child);
name = atk_object_get_name (child);
- spi_init_any_string (&any, (char**) &name);
+ spi_atk_bridge_init_string (&any, child, (gchar**) &name);
if (atk_state_set_contains_state (stateset, ATK_STATE_ACTIVE))
{
spi_atk_emit_eventv (G_OBJECT (child), 0, 0, &any, "window:deactivate");
this_app = NULL;
}
+static void
+spi_atk_bridge_init_base (CORBA_any *any, AtkObject *obj,
+ Accessibility_Application *app, Accessibility_Role *role,
+ CORBA_string *name)
+{
+ const gchar *s = atk_object_get_name (obj);
+ *app = spi_accessible_new_return (atk_get_root (), FALSE, NULL);
+ *role = spi_role_from_atk_role (atk_object_get_role (obj));
+ *name = CORBA_string_dup (s ? s : "");
+}
+
+static void
+spi_atk_bridge_init_nil (CORBA_any *any, AtkObject *obj)
+{
+ Accessibility_Application app = CORBA_OBJECT_NIL;
+ Accessibility_Role role = Accessibility_ROLE_UNKNOWN;
+ CORBA_string name;
+ spi_atk_bridge_init_base (any, obj, &app, &role, &name);
+ spi_init_any_nil (any, app, role, name);
+}
+
+static void
+spi_atk_bridge_init_object (CORBA_any *any, AtkObject *obj, CORBA_Object *c_obj)
+{
+ Accessibility_Application app = CORBA_OBJECT_NIL;
+ Accessibility_Role role = Accessibility_ROLE_UNKNOWN;
+ CORBA_string name;
+ spi_atk_bridge_init_base (any, obj, &app, &role, &name);
+ spi_init_any_object (any, app, role, name, c_obj);
+}
+
+static void
+spi_atk_bridge_init_string (CORBA_any *any, AtkObject *obj, gchar **string)
+{
+ Accessibility_Application app = CORBA_OBJECT_NIL;
+ Accessibility_Role role = Accessibility_ROLE_UNKNOWN;
+ CORBA_string name;
+ spi_atk_bridge_init_base (any, obj, &app, &role, &name);
+ spi_init_any_string (any, app, role, name, string);
+}
+
+static void
+spi_atk_bridge_init_rect (CORBA_any *any, AtkObject *obj, AtkRectangle *rect)
+{
+ Accessibility_Application app = CORBA_OBJECT_NIL;
+ Accessibility_Role role = Accessibility_ROLE_UNKNOWN;
+ CORBA_string name;
+ spi_atk_bridge_init_base (any, obj, &app, &role, &name);
+ spi_init_any_rect (any, app, role, name, rect);
+}
+
AC_INIT(idl/Accessibility.idl)
AT_SPI_MAJOR_VERSION=1
-AT_SPI_MINOR_VERSION=6
-AT_SPI_MICRO_VERSION=5
-AT_SPI_INTERFACE_AGE=5
-AT_SPI_BINARY_AGE=5
+AT_SPI_MINOR_VERSION=7
+AT_SPI_MICRO_VERSION=0
+AT_SPI_INTERFACE_AGE=0
+AT_SPI_BINARY_AGE=0
AT_SPI_VERSION="$AT_SPI_MAJOR_VERSION.$AT_SPI_MINOR_VERSION.$AT_SPI_MICRO_VERSION"
AM_INIT_AUTOMAKE(at-spi, $AT_SPI_VERSION)
AC_SUBST(AT_SPI_MAJOR_VERSION)
# libtool versioning
LT_RELEASE=$AT_SPI_MAJOR_VERSION.$AT_SPI_MINOR_VERSION
LT_CURRENT=10
-LT_REVISION=5
+LT_REVISION=6
LT_AGE=10
LT_VERSION_INFO='-version-info ${LT_CURRENT}:${LT_REVISION}:${LT_AGE}'
AC_SUBST(LT_VERSION_INFO)
AM_DISABLE_STATIC
AM_PROG_LIBTOOL
+dnl DO NOT PUT THIS BACK: at-spi DOES NOT INCLUDE TRANSLATABLE STRINGS. wph 2006.
+dnl
dnl internationalization support; uncomment if translatable strings are reintroduced
dnl ALL_LINGUAS="ar az be bg bn bs ca cs cy da de el en_CA en_GB eo es et eu fa fi fr gl gu he hi hr hu id is it ja ka ko lt mn mr ms nb ne nl nn no or pa pl pt_BR pt ro ru rw sk sl sq sr@ije sr@Latn sr sv th ug uk vi wa xh zh_CN zh_HK zh_TW"
dnl AM_GLIB_GNU_GETTEXT
AC_OUTPUT([
Makefile
-po/Makefile.in
libspi-1.0.pc
libspi-1.0-uninstalled.pc
libloginhelper-1.0.pc
void cspi_object_return (Accessible *accessible);
SPIBoolean cspi_accessible_is_a (Accessible *accessible,
const char *interface_name);
+AccessibleRole cspi_role_from_spi_role (Accessibility_Role role);
void cspi_streams_close_all (void);
gboolean _cspi_exception_throw (CORBA_Environment *ev, char *desc_prefix);
* information for accessible events.
*/
+char* AccessibleEvent_getSourceName (const AccessibleEvent *e);
+AccessibleRole AccessibleEvent_getSourceRole (const AccessibleEvent *e);
+AccessibleApplication* AccessibleEvent_getSourceApplication (const AccessibleEvent *e);
+SPIBoolean AccessibleEvent_getSourceDetails (const AccessibleEvent *e, char **name,
+ AccessibleRole *role,
+ AccessibleApplication **app);
+
char* AccessibleTextChangedEvent_getChangeString (const AccessibleEvent *e);
Accessible * AccessibleChildChangedEvent_getChildAccessible (const AccessibleEvent *e);
return TRUE;
}
-static AccessibleRole
+AccessibleRole
cspi_role_from_spi_role (Accessibility_Role role)
{
/* array is sized according to IDL roles because IDL roles are the index */
g_return_val_if_fail (e, NULL);
g_return_val_if_fail (e->data, NULL);
any = (CORBA_any *) e->data;
- if (CORBA_TypeCode_equivalent (any->_type, TC_CORBA_string, NULL))
+ if (CORBA_TypeCode_equivalent (any->_type, TC_Accessibility_EventDetails, NULL))
+ {
+ Accessibility_EventDetails *details = (Accessibility_EventDetails *)any->_value;
+ return CORBA_string_dup (* (char **) (details->any_data._value));
+ }
+ else if (CORBA_TypeCode_equivalent (any->_type, TC_CORBA_string, NULL))
{
return CORBA_string_dup (* (char **) any->_value);
}
g_return_val_if_fail (e->data, NULL);
any = (CORBA_any *) e->data;
- if (CORBA_TypeCode_equal (any->_type, TC_CORBA_Object, cspi_ev()))
+ if (CORBA_TypeCode_equivalent (any->_type, TC_Accessibility_EventDetails, NULL))
+ {
+ Accessibility_EventDetails *details = (Accessibility_EventDetails *)any->_value;
+ return cspi_object_take (* (CORBA_Object *) (details->any_data._value));
+ }
+ else if (CORBA_TypeCode_equal (any->_type, TC_CORBA_Object, cspi_ev()))
return cspi_object_take (* (CORBA_Object *) any->_value);
else
return NULL;
g_return_val_if_fail (e, NULL);
g_return_val_if_fail (e->data, NULL);
any = (CORBA_any *) e->data;
+ if (CORBA_TypeCode_equivalent (any->_type, TC_Accessibility_EventDetails, NULL))
+ {
+ Accessibility_EventDetails *details = (Accessibility_EventDetails *)any->_value;
+ SPIRect *rect = g_new (SPIRect, 1);
+ Accessibility_BoundingBox *bounds = (Accessibility_BoundingBox *) details->any_data._value;
+ rect->x = bounds->x;
+ rect->y = bounds->y;
+ rect->width = bounds->width;
+ rect->height = bounds->height;
+ return rect;
+ }
if (CORBA_TypeCode_equivalent (any->_type, TC_Accessibility_BoundingBox, NULL))
{
SPIRect *rect = g_new (SPIRect, 1);
}
/**
+ * AccessibleEvent_getSourceName:
+ *
+ * Get the 'accessible-name' of the object emitting the event.
+ * @event: an #AccessibleEvent to be queried.
+ *
+ * Returns: The name of the event source, or NULL if the event source cannot be identified
+ * or does not report a name.
+ */
+char* AccessibleEvent_getSourceName (const AccessibleEvent *e)
+{
+ InternalEvent *ie = (InternalEvent *)e;
+ CORBA_any *any = ((ie && ie->data) ? (CORBA_any *)ie->data : NULL);
+ if (any &&
+ CORBA_TypeCode_equivalent (any->_type,
+ TC_Accessibility_EventDetails, NULL))
+ {
+ Accessibility_EventDetails *details = (Accessibility_EventDetails *) any->_value;
+ return CORBA_string_dup (details->source_name);
+ }
+ else
+ return NULL;
+}
+
+/**
+ * AccessibleEvent_getSourceRole:
+ *
+ * Get the #AccessibleRole of the object emitting the event.
+ * @event: an #AccessibleEvent to be queried.
+ *
+ * Returns: #AccessibleRole of the event source, or SPI_ROLE_UNKNOWN
+ * if the event source's role is unknown or unspecified.
+ * (Some kinds of events, such as 'mouse:' events or
+ * toolkit events, don't have associated object roles.)
+ */
+AccessibleRole AccessibleEvent_getSourceRole (const AccessibleEvent *e)
+{
+ InternalEvent *ie = (InternalEvent *)e;
+ CORBA_any *any = ((ie && ie->data) ? (CORBA_any *)ie->data : NULL);
+ if (any &&
+ CORBA_TypeCode_equivalent (any->_type,
+ TC_Accessibility_EventDetails, NULL))
+ {
+ Accessibility_EventDetails *details = (Accessibility_EventDetails *) any->_value;
+ return cspi_role_from_spi_role (details->source_role);
+ }
+ else
+ return SPI_ROLE_UNKNOWN;
+}
+
+/**
+ * AccessibleEvent_getSourceApplication:
+ *
+ * Get the #Application hosting the object which emitted the event.
+ * @event: an #AccessibleEvent to be queried.
+ *
+ * Returns: A pointer to the host #Application contining the event source
+ * component.
+ */
+AccessibleApplication* AccessibleEvent_getSourceApplication (const AccessibleEvent *e)
+{
+ InternalEvent *ie = (InternalEvent *)e;
+ CORBA_any *any = ((ie && ie->data) ? (CORBA_any *)ie->data : NULL);
+ if (any &&
+ CORBA_TypeCode_equivalent (any->_type,
+ TC_Accessibility_EventDetails, NULL))
+ {
+ Accessibility_EventDetails *details = (Accessibility_EventDetails *) any->_value;
+ return cspi_object_take (details->host_application);
+ }
+ else
+ return NULL;
+}
+
+/**
+ * AccessibleEvent_getSourceApplication:
+ *
+ * Get the host #Application, "accessible name", and #AccessibleRole
+ * of the object which emitted the event.
+ *
+ * @event: an #AccessibleEvent to be queried.
+ *
+ * Returns: TRUE if the source details were successfully retrieved,
+ * FALSE if they were not, either due to error, incomplete data,
+ * or the fact that the event did not encapsulate the required data.
+ */
+SPIBoolean AccessibleEvent_getSourceDetails (const AccessibleEvent *e,
+ char **name, AccessibleRole *role,
+ AccessibleApplication **app)
+{
+ InternalEvent *ie = (InternalEvent *)e;
+ CORBA_any *any = ((ie && ie->data) ? (CORBA_any *)ie->data : NULL);
+ if (any &&
+ CORBA_TypeCode_equivalent (any->_type,
+ TC_Accessibility_EventDetails, NULL))
+ {
+ Accessibility_EventDetails *details = (Accessibility_EventDetails *) any->_value;
+ *name = CORBA_string_dup (details->source_name);
+ *role = cspi_role_from_spi_role (details->source_role);
+ *app = cspi_object_take (details->host_application);
+ return TRUE;
+ }
+ else
+ {
+ *name = NULL;
+ *role = SPI_ROLE_UNKNOWN;
+ *app = NULL;
+ return FALSE;
+ }
+}
+
+/**
* AccessibleTextChangedEvent_getChangeString:
* @e: a pointer to the #AccessibleEvent being queried.
*
* AT-SPI - Assistive Technology Service Provider Interface
* (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
*
- * Copyright 2001 Ximian, Inc.
+ * Copyright 2001-2005 Ximian, Inc. and Sun Microsystems, Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
#endif
#endif
+#ifndef _BONOBO_IDL_INCLUDED_
+#define _BONOBO_IDL_INCLUDED_
+#include <Bonobo_Unknown.idl>
+#endif /* _BONOBO_IDL_INCLUDED_ */
+
+/*!\mainpage AT-SPI Interfaces and Subinterfaces
+ *
+ * This is the main documentation page for the
+ * Assistive Technology Service Provider Interface (AT-SPI).
+ *
+ * \section apps Applications and Interface Components
+ * Namespace Accessibility includes service APIs implemented by
+ * participating applications and their user interface components:\n\n
+ * Accessibility::Accessible\n
+ * Accessibility::Application\n
+ * Accessibility::Desktop\n
+ * Accessibility::Component\n
+ * Accessibility::Hypertext\n
+ * Accessibility::Image\n
+ * Accessibility::Selection\n
+ * Accessibility::StreamableContent\n
+ * Accessibility::Table\n
+ * Accessibility::Text\n
+ * Accessibility::EditableText\n
+ * Accessibility::Value
+ *
+ * \section types Enumerated Types
+ * Accessibility defines a number of key enumerated types, including:\n\n
+ * Accessibility::RelationType\n
+ * Accessibility::Role\n
+ * Accessibility::StateType\n
+ * Accessibility::Event\n
+ * Accessibility::EventDetails \n
+ *
+ * \section Registry
+ * Accessibility also includes Accessibility::Registry,
+ * which is the service used by assistive technologies and related
+ * AT-SPI clients to register interest in certain classes of events,
+ * enumerate the currently available desktop and application list,
+ * and to synthesize certain kinds of device events.
+ *
+ * \section listeners Event Listener Interfaces
+ * Accessibility::EventListener\n
+ * Accessibility::DeviceEventListener
+ *
+ * \section helpers Helper Interfaces
+ *
+ * The following interfaces may be implemented by assistive technologies
+ * themselves, in order to export their services in a consistent manner or
+ * in order to interoperate with other applications or desktop services.\n
+ *
+ * Accessibility::LoginHelper : Implemented by adaptive technologies which
+ * need to participate in user-authentication or login activities, and which
+ * therefore may need negotiation with authentication agents or processes.\n
+ *
+ * Accessibility::Selector [NEW]: Implemented by user agents or assistive
+ * technologies which export lists of choices from which the end-user is
+ * expected to make selections. Useful for various types of remote
+ * activation or intercommunication between multiple ATs.
+ **/
+
/*
* Accessibility interfaces and subinterfaces
*/
#include <Accessibility_Event.idl>
#include <Accessibility_Registry.idl>
#include <Accessibility_Role.idl>
+#include <Accessibility_LoginHelper.idl>
+#include <Accessibility_Selector.idl>
#ifndef __ACCESSIBILITY_COMPILATION__
#ifdef __ORBIT_IDL__
#ifndef _ACCESSIBILITY_ACCESSIBLE_IDL
#define _ACCESSIBILITY_ACCESSIBLE_IDL
-#include <Bonobo_Unknown.idl>
-
#include "Accessibility_Relation.idl"
#include "Accessibility_State.idl"
#include "Accessibility_Role.idl"
module Accessibility {
+ /** used by Text and Document: these correspond to the POSIX setlocale() enum values. **/
+ enum LOCALE_TYPE {
+ LOCALE_TYPE_MESSAGES,
+ LOCALE_TYPE_COLLATE,
+ LOCALE_TYPE_CTYPE,
+ LOCALE_TYPE_MONETARY,
+ LOCALE_TYPE_NUMERIC,
+ LOCALE_TYPE_TIME
+ };
+
+ /** A list of Relations, which may be many-to-many. */
typedef sequence<Relation> RelationSet;
+ /**
+ * A list of name-value pairs, returned as a sequence of strings;
+ * the name and value are separated by a colon.
+ * @note "Attributes" returned in AttributeSet lists are distinct from,
+ * and should not be confused with, "attribute" members of interfaces
+ * as defined by the IDL "attribute" keyword. IDL attributes are
+ * strongly-typed values which are individually obtained via
+ * language-specific bindings whose syntax is dictated by the OMG's
+ * IDL language bindings. For instance using the C language,
+ * the "Accessible::name" attribute is queried using
+ * \c Accessibility_Accessible__get_name (obj, &ev);
+ * Name-value pairs associated with Accessible instances are not
+ * normally redundant with these IDL attributes, i.e. there is no
+ * "accessible-name" attribute in the AttributeSet returned from
+ * Accessible::getAttributes().
+ *
+ * Where possible, the names and values in the name-value pairs
+ * should be chosen from well-established attribute namespaces
+ * using standard semantics. For example, metadata namespace and
+ * values should be chosen from the 'Dublin Core' Metadata
+ * namespace using Dublin Core semantics:
+ * http://dublincore.org/dcregistry/
+ * Similarly, relevant structural metadata should be exposed
+ * using attribute names and values chosen from the CSS2 and WICD specification:
+ * http://www.w3.org/TR/1998/REC-CSS2-19980512
+ * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
+ *
+ * Finally, note that typographic, semantic, and presentational annotations which
+ * are associated with text content, in particular which are associated with particular
+ * text ranges, should be exposed via Accessibility::Text::getAttributeRun instead of
+ * via these more general 'Object attributes'.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ typedef sequence<string> AttributeSet;
+
+ /**
+ * A list of accessible roles
+ * @since AT-SPI 1.7.0
+ **/
+ typedef sequence<Role> RoleSet;
+
+ /** Used by Component and Text, a struct defining a bounding rectangle.
+ * The relevant coordinate system is determined by the context of the
+ * API call which returned or receives the value.
+ */
struct BoundingBox {
- long x;
- long y;
- long width;
- long height;
+ long x; /**< the value corresponding to the minimum or leftmost x position. */
+ long y; /**< the value corresponding to the minimum y value. */
+ long width; /**< the horizontal extent of the bounding box,
+ * that is, the difference between the maximum and minimum
+ * x coordinate bounds.
+ */
+ long height; /**< the vertical extent of the bounding box,
+ * that is, the difference between the maximum and minimum
+ * y coordinate bounds.
+ */
};
+
+ interface Application; /**< defined in Accessibility_Application.idl **/
+
+ /**
+ * The base interface which is implemented by all accessible objects.
+ * All objects support interfaces for querying their contained 'children'
+ * and position in the accessible-object hierarchy, whether or not they
+ * actually have children.
+ *
+ * @note Events that may be emitted by instances of Accessible include:
+ * \li \c "object:property-change" A base (strongly-typed) object attribute has changed,
+ * for instance "object:property-change:accessible-name".
+ * Notifed property subtypes include accessible-name, accessible-description,
+ * and accessible-parent.
+ *
+ * \li \c "object:children-changed" The number or identity of an object's children
+ * has changed.
+ * \li \c "object:state-changed" The object's StateSet has had a state added
+ * or removed.
+ * \li \c "object:active-descendant-changed" If the object includes
+ * STATE_MANAGES_DESCENDANTS, this event is fired to indicate that the
+ * descendant having STATE_ACTIVE has changed; this corresponds to
+ * "micro" keyboard focus when the containing/emitting object has
+ * "macro" or technical keyboard focus. For instance, this event is
+ * usually emitted while traversing tables and/or spreadsheet cells.
+ * \li \c "object:attribute-change" A weakly-typed property, as contained in the
+ * AttributeSet returned by Accessible::getAttributes, has changed in value,
+ * been added, or been removed from the object.
+ * ("object:attribute-change" notifications were added in AT-SPI 1.7.0)
+ */
interface Accessible : Bonobo::Unknown {
/**
- * @name: a (short) #string representing the object's name.
+ * a (short) \c string representing the object's name.
**/
attribute string name;
/**
- * @description: a #string describing the object in more detail than @name.
+ * a \c string describing the object in more detail than \a name.
**/
attribute string description;
/**
- * @parent: an #Accessible object which is this object's containing object.
+ * an ::Accessible object which is this object's containing object.
**/
- readonly attribute Accessible parent;
+ readonly attribute Accessibility::Accessible parent;
/**
- * @childCount: the number of children contained by this object.
+ * childCount: the number of children contained by this object.
**/
readonly attribute long childCount;
/**
- * isEqual:
- * @obj: an #Accessible object reference to compare to
- *
- * Determine whether an #Accessible refers to the same object as another
+ * Determine whether an ::Accessible refers to the same object as another.
+ * This method should be used rather than brute-force comparison of
+ * object references (i.e. "by-value" comparison), as two object references
+ * may have different apparent values yet refer to the same object.
*
- * Returns: a #boolean indicating whether the two object references
+ * @param obj: an ::Accessible object reference to compare to
+ * @returns: a \c boolean indicating whether the two object references
* point to the same object.
**/
boolean isEqual (in Accessible obj);
/**
- * getChildAtIndex:
- * @index: an in parameter indicating which child is requested (zero-indexed).
- *
- * Get the accessible child of this object at index @index.
- *
- * Returns: the 'nth' @Accessible child of this object.
+ * Get the accessible child of this object at \c index.
+ * @param index: an in parameter indicating which child is requested (zero-indexed).
+ * @returns: the 'nth' ::Accessible child of this object.
**/
Accessible getChildAtIndex (in long index);
/**
- * getIndexInParent:
- *
* Get the index of this object in its parent's child list.
- *
- * Returns: a long integer indicating this object's index in the parent's list.
+ * @returns: a long integer indicating this object's index in the parent's list.
**/
long getIndexInParent ();
/**
- * getRelationSet:
- *
* Get a set defining this object's relationship to other accessible objects.
- *
- * Returns: a @RelationSet defining this object's relationships.
+ * @returns: a ::RelationSet defining this object's relationships.
**/
RelationSet getRelationSet ();
/**
- * getRole:
- * Get the @Role indicating the type of UI role played by this object.
+ * Get the ::Role indicating the type of UI role played by this object.
*
- * Returns: a @Role indicating the type of UI role played by this object.
+ * @returns: a ::Role indicating the type of UI role played by this object.
**/
Role getRole ();
/**
- * getRoleName:
* Get a string indicating the type of UI role played by this object.
*
- * Returns: a UTF-8 string indicating the type of UI role played by this object.
+ * @returns: a UTF-8 string indicating the type of UI role played by this object.
**/
string getRoleName ();
/**
- * getLocalizedRoleName:
* Get a string indicating the type of UI role played by this object,
* translated to the current locale.
*
- * Returns: a UTF-8 string indicating the type of UI role played by this object.
+ * @returns: a UTF-8 string indicating the type of UI role played by this object.
**/
string getLocalizedRoleName ();
/**
- * getState:
- *
- * Get the current state of the object as a @StateSet.
- * Returns: a @StateSet encapsulating the currently true states of the object.
+ * Get the current state of the object as a ::StateSet.
+ * @returns: a ::StateSet encapsulating the currently true states of the object.
**/
StateSet getState ();
- void unImplemented ();
- void unImplemented2 ();
- void unImplemented3 ();
+ /**
+ * Get a list of properties applied to this object as a whole, as an
+ * ::AttributeSet consisting of name-value pairs. As such these attributes
+ * may be considered weakly-typed properties or annotations, as distinct
+ * from the strongly-typed interface instance data declared using the IDL
+ * "attribute" keyword.
+ *
+ * Not all objects have explicit "name-value pair" AttributeSet properties.
+ *
+ * Attribute names and values may have any UTF-8 string value, however where possible,
+ * in order to facilitate consistent use and exposure of "attribute" properties by
+ * applications and AT clients, attribute names and values should chosen from
+ * a publicly-specified namespace where appropriate.
+ *
+ * Where possible, the names and values in the name-value pairs
+ * should be chosen from well-established attribute namespaces
+ * using standard semantics.
+ * For example, attributes of ::Accessible objects corresponding to XHTML content
+ * elements should correspond to attribute names and values specified in the w3c
+ * XHTML specification, at http://www.w3.org/TR/xhtml2, where such values are not
+ * already exposed via a more strongly-typed aspect of the AT-SPI API.
+ * Metadata names and
+ * values should be chosen from the 'Dublin Core' Metadata
+ * namespace using Dublin Core semantics:
+ * http://dublincore.org/dcregistry/
+ * Similarly, relevant structural metadata should be exposed
+ * using attribute names and values chosen from the CSS2 and WICD specification:
+ * http://www.w3.org/TR/1998/REC-CSS2-19980512
+ * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
+ *
+ * @note Clients seeking semantic or typographical attributes associated with
+ * specific character spans of text content should use ::Text::getAttributeRun instead.
+ * The attributes returned by Accessible::getAttributes do not include
+ * "text attributes".
+ *
+ * @see ::Accessibility::Text::getAttributeRun
+ *
+ * @returns: an ::AttributeSet encapsulating any "attribute values" currently
+ * defined for the object.
+ *
+ * @since AT-SPI 1.7.0
+ **/
+ AttributeSet getAttributes ();
+
+ /**
+ * Get the containing Application for this object.
+ *
+ * @returns the Application instance to which this object belongs.
+ * @since AT-SPI 1.7.0
+ **/
+ Application getApplication ();
+
+ /** /cond future expansion */
+ void unimplemented ();
+ /** /endcond */
+
};
};
*/
module Accessibility {
-
+ /**
+ * An interface through which a user-actionable user interface
+ * component can be manipulated. Components which react to mouse or
+ * keyboard input from the user, (with the exception of pure text entry
+ * fields with no other function), should implement this interface.
+ * Typical actions include "click", "press", "release" (for instance for
+ * buttons), "menu" (for objects which have context menus invokable from
+ * mouse or keyboard), "open" for icons representing files folders, and others.
+ */
interface Action : Bonobo::Unknown {
/**
- * nActions: a @long containing the number of actions this object supports.
+ * nActions: a \c long containing the number of actions this object supports.
*
**/
readonly attribute long nActions;
/**
* getDescription:
- * @index: an %in parameter specifying the index of the action
+ * @param index: the index of the action
* for which a description is desired.
*
- * Gets the description of the specified action.
+ * Get the description of the specified action. The description of an action
+ * may provide information about the result of action invocation, unlike the
+ * action name.
+ * @see getName.
*
- * Returns: a @wstring containing the description of the specified action.
+ * @returns: a \c string containing the description of the specified action.
*
**/
string getDescription (in long index);
/**
* getName:
- * @index: an %in parameter specifying the index of the action
+ * @param index: the index of the action
* whose name is requested.
*
- * Gets the name of the specified action.
+ * Get the name of the specified action. Action names generally describe
+ * the user action, i.e. "click" or "press", rather then the result of
+ * invoking the action.
*
- * Returns: a @string containing the name of the specified action.
+ * @returns: a \c string containing the name of the specified action.
*
**/
string getName (in long index);
/**
* doAction:
- * @index: an %in parameter specifying the 0-based index of the action to perform.
+ * @param index: the 0-based index of the action to perform.
*
* Causes the object to perform the specified action.
*
- * Returns: a @boolean indicating success or failure.
+ * @returns: a \c boolean indicating success or failure.
*
**/
boolean doAction (in long index);
/**
* getKeyBinding:
- * @index: an %in parameter specifying the 0-based index of the action
+ * @param index: the 0-based index of the action
* for which a key binding is requested.
*
- * Gets the key binding associated with a specific action.
+ * Get the key binding associated with a specific action.
*
- * Returns: a @string containing the key binding for the specified action,
- * "" if none exists.
+ * @returns: a \c string containing the key binding for the specified action,
+ * or an empty string ("") if none exists.
**/
string getKeyBinding (in long index);
+
/**
+ * \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};
* AT-SPI - Assistive Technology Service Provider Interface
* (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
*
- * Copyright 2001 Sun Microsystems Inc.
+ * Copyright 2001-2004 Sun Microsystems Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
module Accessibility {
- enum LOCALE_TYPE {
- LOCALE_TYPE_MESSAGES,
- LOCALE_TYPE_COLLATE,
- LOCALE_TYPE_CTYPE,
- LOCALE_TYPE_MONETARY,
- LOCALE_TYPE_NUMERIC,
- LOCALE_TYPE_TIME
- };
-
+ /**
+ * An interface identifying an object which is the root of the
+ * user interface Accessible hierarchy associated with a running application.
+ * Children of Application are typically, but not exclusively,
+ * top-level windows.
+ * @note It is possible for an element deeper in an Accessibility stack to
+ * implement Application, for instance in the case of "embedded applications"
+ * which draw into toplevel windows associated with other applications
+ * from the user's point of view.
+ */
interface Application : Accessible {
/**
- * @toolkitName:
* A string indicating the type of user interface toolkit
* which is used by the application.
- * Ordinarily clients of @AccessibleApplication should be
- * toolkit-agnostic, dependencies on this method probably
- * should be reconsidered!
+ * @note Ordinarily clients of ::Application should be
+ * toolkit-agnostic, dependencies on this property should
+ * be avoided where possible.
**/
readonly attribute string toolkitName;
/**
- * @version:
* A string indicating the version number of the application's
* accessibility bridge implementation.
**/
readonly attribute string version;
/**
- * @id:
* The application instance's unique ID as assigned by the registry.
**/
attribute long id;
/**
- * registerToolkitEventListener:
- * @listener: an #EventListener object which will receive the requested
+ * @param listener: an ::EventListener object which will receive the requested
* events from the application's toolkits via toolit 'bridges'
- * @eventName: a UTF-8 string indicating the type of (toolkit-specific) event
+ * @param eventName: a UTF-8 string indicating the type of (toolkit-specific) event
* being requested. Not all applications can generate toolkit events of
* a given type.
*
* Register with this application's toolkit for "toolkit-specific" event notifications.
+ * @note
* For most event support, clients should use non-toolkit-specific events
- * whenever possible, via #Registry::registerGlobalEventListener - this method
- * is provided as a 'back door' when generic names do not exist for the events in question.
- * SUBJECT TO DEPRECATION in favor of Registry::registerGlobalEventListener forms.
- *
+ * whenever possible, via ::Registry::registerGlobalEventListener - this method
+ * is provided as a 'back door' when generic names do not exist for the events in
+ * question.
**/
void registerToolkitEventListener (in EventListener listener, in string eventName);
/**
* registerObjectEventListener:
- * @listener: an #EventListener object which will receive the requested
+ * @param listener: an ::EventListener object which will receive the requested
* events
- * @eventName: a UTF-8 string indicating the type of (toolkit-specific) event
+ * @param eventName: a UTF-8 string indicating the type of (toolkit-specific) event
* being requested.
* Register with this application toolkit for "Accessibility::Accessible"
- * event notifications. SUBJECT TO DEPRECATION
- *
+ * event notifications.
+ * @note: SUBJECT TO DEPRECATION.
**/
void registerObjectEventListener (in EventListener listener, in string eventName);
/**
- * pause:
- *
* Request that the application temporarily stop sending events.
* In most cases this should pause the application's main event loop.
*
- * Returns: %true if the request succeeded, %false otherwise.
+ * @returns: \c true if the request succeeded, \c false otherwise.
+ *
+ * @note: This method is not implemented in most toolkits, and therefore should be treated with caution.
**/
boolean pause ();
/**
- * resume:
- *
* Request that the application resume sending events.
*
- * Returns: %true if the request succeeded, %false otherwise.
+ * @returns: \c True if the request succeeded, \c False otherwise.
**/
boolean resume ();
- /**
- * getLocale:
- *
- * @lctype: the LocaleType for which the locale is queried.
+ /**
* Gets the locale in which the application is currently operating.
- * For the current message locale, use @lctype LOCALE_TYPE_MESSAGES.
+ * For the current message locale, use \a lctype LOCALE_TYPE_MESSAGES.
*
- * Returns: a string compliant with the POSIX standard for locale description.
+ * @param lctype The LocaleType for which the locale is queried.
+ * @returns a string compliant with the POSIX standard for locale description.
**/
string getLocale (in LOCALE_TYPE lctype);
+ /**\cond (This comment tells doxygen not to document these) */
void unImplemented_ ();
void unImplemented2_ ();
void unImplemented3_ ();
+ /**\endcond */
};
};
module Accessibility {
+ /**
+ * The ComponentLayer of a Component instance indicates its relative stacking order
+ * with respect to the onscreen visual representation of the UI.
+ * ComponentLayer, in combination with Component bounds information, can be used
+ * to compute the visibility of all or part of a component. This is important in
+ * programmatic determination of region-of-interest for magnification, and in
+ * ¨flat screen review¨ models of the screen, as well as for other uses.
+ * Objects residing in two of the ComponentLayer categories support
+ * further z-ordering information, with respect to their peers in the same layer:
+ * namely, LAYER_WINDOW and LAYER_MDI. Relative stacking order for other objects within
+ * the same layer is not available; the recommended heuristic is ¨first child paints first¨,
+ * in other words, assume that the first siblings in the child list are subject to being
+ * overpainted by later siblings if their bounds intersect.
+ *
+ * The order of layers, from bottom to top, is:
+ * \li LAYER_BACKGROUND
+ * \li LAYER_WINDOW
+ * \li LAYER_MDI
+ * \li LAYER_CANVAS
+ * \li LAYER_WIDGET
+ * \li LAYER_POPUP
+ * \li LAYER_OVERLAY
+ */
enum ComponentLayer {
- LAYER_INVALID,
- LAYER_BACKGROUND,
- LAYER_CANVAS,
- LAYER_WIDGET,
- LAYER_MDI,
- LAYER_POPUP,
- LAYER_OVERLAY,
- LAYER_WINDOW,
- LAYER_LAST_DEFINED
+ LAYER_INVALID,/**< Indicates an error condition or uninitialized value. */
+ LAYER_BACKGROUND,/**< The bottom-most layer, over which everything else is painted.
+ * The 'desktop background' is generally in this layer. */
+ LAYER_CANVAS,/**< The 'background' layer for most content renderers and UI Component
+ * containers. */
+ LAYER_WIDGET,/**< The layer in which the majority of ordinary 'foreground' widgets reside.*/
+ LAYER_MDI,/**< A special layer between LAYER_CANVAS and LAYER_WIDGET, in which the
+ * 'pseudo windows' (e.g. the MDI frames) reside.
+ * @see Component::getMDIZOrder */
+ LAYER_POPUP,/**< A layer for popup window content, above LAYER_WIDGET. */
+ LAYER_OVERLAY,/**< The topmost layer. */
+ LAYER_WINDOW,/**< The layer in which a toplevel window background usually resides. */
+ LAYER_LAST_DEFINED/**< Used only to determine the end of the enumeration. */
};
+ /**
+ * The Component interface is implemented by objects which occupy on-screen space, e.g. objects
+ * which have onscreen visual representations. The methods in Component allow clients to identify
+ * where the objects lie in the onscreen coordinate system, their relative size, stacking order, and
+ * position. It also provides a mechanism whereby keyboard focus may be transferred to specific
+ * user interface elements programmatically. This is a 2D API, coordinates of 3D objects are projected into the
+ * 2-dimensional screen view for purposes of this interface.
+ *
+ * @note the meaning and defined values of the \c short \c coord_type parameter used by some
+ * Component methods is as follows:
+ * \li 0 indicates coord_type_xy_screen, coordinates are relative to the display screen, in pixels.
+ * \li 1 indicates coord_type_xy_window, coordinates are relative to the current toplevel window, in pixels.
+ *
+ * @note Events emitted by Component instances include:
+ * \li \c "object:bounds-changed"
+ * \li \c "object:visible-data-changed"
+ */
interface Component : Bonobo::Unknown {
-
+
+ /**
+ * @returns \c True if the specified point lies within the Component's bounding box,
+ * \c False otherwise.
+ */
boolean contains (in long x, in long y, in short coord_type);
+ /**
+ * @returns the Accessible child whose bounding box contains the specified point.
+ */
Accessible getAccessibleAtPoint (in long x, in long y, in short coord_type);
+ /**
+ * Obtain the Component's bounding box, in pixels, relative to the specified coordinate system.
+ * @returns a BoundingBox which entirely contains the object's onscreen visual representation.
+ **/
BoundingBox getExtents (in short coord_type);
+ /**
+ * Obtain the position of the current component in the coordinate system specified
+ * by \c coord_type.
+ * @param coord_type
+ * @param x an out parameter which will be back-filled with the returned x coordinate.
+ * @param y an out parameter which will be back-filled with the returned y coordinate.
+ */
void getPosition (out long x, out long y, in short coord_type);
+ /**
+ * Obtain the size, in the coordinate system specified by \c coord_type,
+ * of the rectangular area which fully contains the object's
+ * visual representation, without accounting for viewport clipping.
+ * @param width the object's horizontal extents in the specified coordinate system.
+ * @param height the object's vertical extents in the specified coordinate system.
+ */
void getSize (out long width, out long height);
+ /** @returns the ComponentLayer in which this object resides. */
ComponentLayer getLayer ();
+ /**
+ * Obtain the relative stacking order (i.e. 'Z' order) of an object.
+ * Larger values indicate that an object is on "top" of the stack, therefore
+ * objects with smaller MDIZOrder may be obscured by objects with a larger MDIZOrder,
+ * but not vice-versa.
+ * @note only relevant for objects in LAYER_MDI or LAYER_WINDOW
+ * @returns an integer indicating the object's place in the stacking order.
+ */
short getMDIZOrder ();
+ /**
+ * Request that the object obtain keyboard focus.
+ *
+ * @returns \c True if keyboard focus was successfully transferred to the Component.
+ */
boolean grabFocus ();
+ /**
+ * Register an EventListener for notification when this object receives keyboard focus.
+ * @note you probably want to register for ¨focus:¨ events via
+ * Registry::registerGlobalEventListener instead.
+ */
void registerFocusHandler (in EventListener handler);
+ /**
+ * Request that an EventListener registered via registerFocusHandler no longer be notified
+ * when this object receives keyboard focus.
+ */
void deregisterFocusHandler (in EventListener handler);
- /**
+ /**
+ * Obtain the alpha value of the component. An alpha value of 1.0 or greater
+ * indicates that the object is fully opaque, and an alpha value of 0.0 indicates
+ * that the object is fully transparent. Negative alpha values have no defined
+ * meaning at this time.
+ *
+ * @note alpha values are used in conjunction with Z-order calculations to
+ * determine whether an object wholly or partially obscures another object's
+ * visual intersection, in the event that their bounds intersect.
+ *
+ * @see STATE_OPAQUE
+ *
+ * @since AT-SPI 1.7.0
+ */
+ double getAlpha ();
+
+ /** \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented ();
void unImplemented2 ();
void unImplemented3 ();
- void unImplemented4 ();
+ /** \endcond */
};
};
#include <Accessibility_Accessible.idl>
module Accessibility {
- interface Desktop : Accessible {
/**
* At the moment this is only a marker interface, it acts just like
- * any other Accessible.
+ * any other Accessible. In all known implementations, the
+ * children are all instances of Application, but this is not
+ * guaranteed by this interface.
**/
- /**
+ interface Desktop : Accessible {
+ /** \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented2_ ();
void unImplemented3_ ();
void unImplemented4_ ();
+ /** \endcond */
};
};
module Accessibility {
+ /**
+ * Derived from interface Text, EditableText provides methods for
+ * modifying textual content of components which support editing.
+ * EditableText also interacts with the system clipboard via copyText,
+ * cutText, and pasteText.
+ *
+ * @note read-only instances of EditableText are possible;
+ * These may be instances of a general-purpose component type which are
+ * sometimes, but not always, user-editable, or may be
+ * components which are temporarily or circumstantially
+ * in a non-editable state.
+ */
interface EditableText : Text {
-
+ /**
+ * Replace the text contents with a new string, discarding the old contents.
+ *
+ * @param newContents a UTF-8 string with which the text object's contents will be replaced.
+ * @returns \c True if the text content was successfully changed, \c False otherwise.
+ */
boolean setTextContents (in string newContents);
+ /**
+ * Insert new text contents into an existing text object at a given location, while retaining
+ * the old contents.
+ * @param position the character offset into the Text implementor's content at which the
+ * new content will be inserted.
+ * @param text a UTF-8 string of which \c length characters will be inserted into the text
+ * object's text buffer.
+ * @param length the number of characters of \c text to insert. If the character count
+ * of \c text is less than or equal to \c length, the entire contents of \c text
+ * will be inserted.
+ *
+ * @returns \c True if the text content was successfully inserted, \c False otherwise.
+ */
boolean insertText (in long position, in string text, in long length);
+ /**
+ * Apply a particular set of attributes to a range of text.
+ *
+ *
+ * @returns \c True if the text attributes were successfully modified, \c False otherwise.
+ */
boolean setAttributes (in string attributes, in long startPos, in long endPos);
+ /**
+ * Copy a range of text into the system clipboard.
+ * @param startPos the character offset of the first character in the range of text being
+ * copied.
+ * @param endPos the offset of the first character past the end of the range of text
+ * being copied.
+ */
void copyText (in long startPos, in long endPos);
+ /**
+ * Excise a range of text from a Text object, copying it into the system clipboard.
+ * @param startPos the character offset of the first character in the range of text being
+ * cut.
+ * @param endPos the offset of the first character past the end of the range of text
+ * being cut.
+ * @returns \c True if the text was successfully cut, \c False otherwise.
+ */
boolean cutText (in long startPos, in long endPos);
+ /**
+ * Excise a range of text from a Text object without copying it into the system clipboard.
+ * @param startPos the character offset of the first character in the range of text being
+ * deleted.
+ * @param endPos the offset of the first character past the end of the range of text
+ * being deleted.
+ * @returns \c True if the text was successfully deleted, \c False otherwise.
+ */
boolean deleteText (in long startPos, in long endPos);
+ /**
+ * Copy the text contents of the system clipboard, if any, into a Text object,
+ * inserting it at a particular character offset.
+ *
+ * @param position the character offset before which the text will be inserted.
+ * @returns \c True if the text was successfully pasted into the Text object, \c False otherwise.
+ */
boolean pasteText (in long position);
+
/**
- * unImplemented7:
+ * unImplemented:
*
* placeholders for future expansion. Note that these are named
* 'unimplemented5 and unimplemented6' to avoid conflict with
{
interface Accessible;
+ /**
+ * A struct encapsulating detailed information about an Event.
+ * This struct supercedes the previous use of the 'any' field
+ * in EventDetails; the content previously stored in Event::any_data
+ * is now stored in EventDetails::any_data, and Event::any_data
+ * points to an instance of the EventDetails structure, if
+ * the object's implementation supports event detail reporting,
+ * otherwise Event::any_data contains CORBA_OBJECT_NIL.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ struct EventDetails {
+ Application host_application;
+ Role source_role;
+ string source_name;
+ any any_data;
+ };
+
+ /**
+ * A structure encapsulating information about an event
+ * for which notification was requested. Usually such notification
+ * is requested via a call to Registry::registerGlobalEventListener.
+ * The structure contains a colon-delimited string indicating the event
+ * type, a reference to the generating Accessible, two detail fields whose
+ * interpretation is event-type-specific, and a final field containing
+ * event-type-specific data.
+ *
+ * @note Since AT-SPI 1.7.0 the 'any' field contains an EventDetails
+ * struct, which encapsulates additional information about the event
+ * and its generating object.
+ */
struct Event {
+ /** A colon-delimited string indicating the type of the event.
+ * The string can be interpreted as
+ * \c class:type:subtype
+ * For instance ¨object:text-changed:insert¨ is an event
+ * from the 'Object' class, which corresponds to Accessible objects
+ * general, the type of the event is a ¨text-changed¨ event (i.e. a change in the
+ * content of an implementor of the Text interface), and the
+ * specific subtype of the change is an insertion event.
+ *
+ * Event classes include the following:
+ * \li focus: an object has received keyboard focus. This event has no type or subtype.
+ * \li window: a toplevel window has changed state.
+ * \li object: an object (i.e. Accessible) has undergone some change in state, content,
+ * or hierarchy
+ * \li document:a change to a document's content has occurred, or its
+ * content loading status has changed.
+ * \li mouse: an event originating from the pointing device. Rarely used;
+ * in most cases clients will wish to register for pointer events via
+ * the DeviceEventController::registerDeviceEvent method instead.
+ * \li keyboard: an event indicating that the keyboard state (for example, the
+ * modifier state) has changed significantly.
+ * "keyboard:" events are not sent for individual keystrokes except as
+ * a side-effect of certain keys, for instance modifier keys.
+ * Clients interested in key events should listen for DeviceEvents
+ * via DeviceEventController::registerKeystrokeListener instead.
+ *
+ * @note For more information on specific event types, see the documentation for
+ * each of the individual interfaces supported by some Accessible objects.
+ *
+ * @see Accessible, Component, Image, Selection, Table, Text, Value.
+ */
string type;
+ /**
+ * The Accessible object which is the source of the event. The source object is the object
+ * to which the change inferred by the event emission occurs; for instance,
+ * the object emitting a ¨object:parent-changed¨ event is the child, not the parent.
+ * Likewise, the event source of an ¨object:children-changed:insert¨ event is the parent,
+ * not the inserted child.
+ */
Accessible source;
+ /** An integer whose meaning is event type dependent. It may indicate the offset of
+ * text being inserted, in the case of ¨object:text-changed:insert¨, or the index of a
+ * newly added child in the case of ¨object:children-changed:add¨.
+ * @note since most AT-SPI clients react to events via an asynchronous queue, for
+ * performance reasons, this field may be of limited utility unless the client maintains
+ * a large client-side cache of the hierarchy and contained data. This is because by the time
+ * such an event is asynchronously processed, the state of the originating object may have
+ * changed. In other words, the data in the detail1 member is not state-coherent outside
+ * of the event handler. More useful results are gotten by examination of the 'any_data' field.
+ */
long detail1;
+ /** see description of detail2 */
long detail2;
+ /**
+ * A generic storage location for event-type-specific data which provides more specific
+ * information about the event; for instance, in AT-SPI versions prior to 1.7.0,
+ * in the case of ¨object:text-changed:insert¨ events, this field contains a string
+ * indicating the inserted text.
+ *
+ * @note Since AT-SPI 1.7.0, the data contained in this field is an EventDetails struct.
+ */
any any_data;
};
+ /**
+ * A generic interface implemented by objects for the
+ * receipt of event notifications. EventListener is the interface from which
+ * Accessibility::Registry is derived, and via which clients of the Registry
+ * receive notification of changes to an application's user interface and content.
+ */
interface EventListener : Bonobo::Unknown {
+ /**
+ * Synchronously notify an EventListener that an event has occurred, by passing it an
+ * Event struct.
+ * @param e The Event about which the listener is being notified.
+ */
void notifyEvent (in Event e);
+
+/** \cond */
void unImplemented_ ();
void unImplemented2_ ();
void unImplemented3_ ();
void unImplemented4_ ();
+/** \endcond */
};
};
module Accessibility {
+ /**
+ * Instances of Hyperlink are returned by Hypertext objects, and are
+ * the means by which end users and clients interact with linked, and in
+ * some cases embedded, content. Hyperlinks may have multiple "anchors",
+ * where an anchor corresponds to a reference to a particular resource with
+ * a corresponding resource identified (URI). Hyperlinks may be
+ * queried for their URIs, or queried for the objects corresponding to their
+ * anchors. The objects thus obtained are instances of Accessible,
+ * and may be queried, and manipulated via the Action interface.
+ *
+ * @note A Hyperlink implementor is normally NOT an Accessible;
+ * the preferred usage is for a Hyperlink's associated "objects"
+ * (accessed via the ::getObject method) are Accessibles. This means
+ * that Actions such as "open link" are normally invoked on
+ * the result of Hyperlink::getObject rather than directly on the
+ * Hyperlink instance. For historical reasons some implementors of Hyperlink
+ * implement Action as well. This usage on the part of implementing
+ * applications and toolkits is discouraged, but clients of Hyperlink
+ * should be aware of it and prepared to handle such usage.
+ */
interface Hyperlink : Bonobo::Unknown {
+ /** the number of separate anchors associated with this Hyperlink */
readonly attribute short nAnchors;
+ /**
+ * the starting offset within the containing Hypertext content
+ * with which this Hyperlink is associated
+ */
readonly attribute long startIndex;
+ /**
+ * the ending offset within the containing Hypertext content
+ * with which this Hyperlink is associated; that is, the offset of the
+ * first element past the range within the Hypertext associated with
+ * this Hyperlink.
+ */
readonly attribute long endIndex;
+ /**
+ * Gets the i'th object, (where i is an integer between 0 and
+ * Hyperlink::numAnchors - 1, inclusive) associated with a Hyperlink.
+ * The objects returned are usually actionable (i.e. they should implement
+ * Accessibility::Action), and the available actions often include
+ * "open", "bookmark", "save link as", etc. They may also implement
+ * Accessibility::StreamableContent, although clients can normally use
+ * ::getURI to obtain a resource locator via which the object's
+ * data may be accessed.
+ *
+ * @note the most common application for 'multi anchor'
+ * hyperlinks in HTML is probably "client side imagemaps".
+ * A clickable image which uses the HTML 'usemap' attribute
+ * should have one anchor for every <area> element that
+ * includes an HREF. The objects corresponding to these map
+ * areas may implement Accessibility::Component, to represent
+ * their onscreen bounding box, and may expose their 'shape' as
+ * as name-value pair via Accessibility::Accessible::getAttributeSet.
+ *
+ * @returns an Accessible object instance representing the
+ * Hyperlink's ith anchor, or through which the content associated with
+ * the \c ith anchor can be
+ * accessed.
+ */
Accessible getObject (in long i);
+ /**
+ * Obtain a resource locator ('URI') which can be used to
+ * access the content to which this link "points" or is connected.
+ * @returns a string corresponding to the URI of the Hyperlink's
+ * 'ith' anchor, if one exists, or a NIL string otherwise.
+ */
string getURI (in long i);
+ /**
+ * Check the hyperlink to see if a connection to its backing
+ * content can be established, or if its URI is valid.
+ * @note instances of invalid hyperlinks include links with malformed
+ * URIs, or for which a contact to the service provider
+ * specified in the URI cannot be established.
+ * @returns \c True if the object's content is available, or
+ * \c False if the hyperlink's URI is invalid, or
+ * a connection to the resource can not be established.
+ */
boolean isValid ();
- /**
+ /** \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};
#include <Accessibility.idl>
module Accessibility {
-
+ /**
+ * An interface used for objects which implement linking between
+ * multiple resource or content locations, or multiple 'markers'
+ * within a single document. A Hypertext instance is associated with
+ * one or more Hyperlinks, which are associated with particular
+ * offsets within the Hypertext's included content.
+ *
+ * @note While this interface is derived from ::Text,
+ * there is no requirement that Hypertext instances have
+ * textual content; they may implement ::Image as well,
+ * and Hyperlinks need not have non-zero text offsets.
+ */
interface Hypertext : Bonobo::Unknown {
+ /**
+ * Query the hypertext object for the number of Hyperlinks it
+ * contains.
+ *
+ * @returns the number of Hyperlinks associated with this Hypertext
+ * object, as a long integer.
+ */
long getNLinks ();
+ /**
+ * Get one of the Hyperlinks associated with this Hypertext object,
+ * by index.
+ *
+ * @param linkIndex an integer from 0 to getNLinks() - 1.
+ * @returns the Hyperlink in this Hypertext object.
+ */
Hyperlink getLink (in long linkIndex);
+ /**
+ * Get the hyperlink index, if any, associated with a
+ * particular character offset in the Hypertext object.
+ * For Hypertext implementors without textual content, all
+ * hyperlinks are associated with character offset '0'.
+ *
+ * @return the index of the Hyperlink associated with character
+ * offset \c characterIndex, or -1 if no Hyperlink is associated
+ * with that character offset.
+ */
long getLinkIndex (in long characterIndex);
+
+ /** \cond */
void unImplemented ();
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};
* AT-SPI - Assistive Technology Service Provider Interface
* (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
*
- * Copyright 2001 Sun Microsystems, Inc.
+ * Copyright 2001 - 2005 Sun Microsystems, Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* Boston, MA 02111-1307, USA.
*/
+#include "Accessibility_Accessible.idl"
+
module Accessibility {
+ /**
+ * An interface implemented by objects which render image data or
+ * pictorial information to the screen. When onscreen components include
+ * graphical information that is not purely intended to enhance "3d effect"
+ * or visual layout, but which conveys some semantic or informational
+ * content to the sighted user, they should implement Image, and that
+ * semantic content should be conveyed textually to the extent possible
+ * via the image description, as well as the Accessible::name and
+ * Accessible::description properties.
+ */
interface Image : Bonobo::Unknown {
+ /**
+ * A UTF-8 string providing a textual description
+ * of what is visually depicted in the image.
+ *
+ * @note It is recommended that imageDescription be the shorter
+ * of the available image descriptions, for instance "alt text"
+ * in HTML images, and a longer description be provided in
+ * Accessible::accessible-description, if available.
+ * A short, one or two word label for the image should be provided in
+ * Accessible::accessible-name.
+ */
readonly attribute string imageDescription;
+ /**
+ * A string corresponding to the POSIX LC_MESSAGES locale used
+ * by the imageDescription.
+ * @since AT-SPI 1.7.0
+ */
+ readonly attribute string imageLocale;
+ /**
+ * Obtain a bounding box which entirely contains the image contents,
+ * as displayed on screen. The bounds returned do not account for
+ * any viewport clipping or the fact that the image may be
+ * partially or wholly obscured by other onscreen content.
+ * @note This method returns the bounds of the current onscreen
+ * view, and not the nominal size of the source data in the
+ * event that the original image has been rescaled.
+ *
+ * @param coordType If 0, the returned bounding box position is returned
+ * relative to the screen; if 1, the bounding box position is returned
+ * relative to the containing window.
+ * @returns a BoundingBox enclosing the image's onscreen representation.
+ */
BoundingBox getImageExtents (in short coordType);
+ /**
+ * Get the coordinates of the current image position on screen.
+ *
+ * @param x Back-filled with the x coordinate of the
+ * onscreen image (i.e. the minimum x coordinate)
+ * @param y Back-filled with the y coordinate of the
+ * onscreen image (i.e. the minimum y coordinate)
+ * @param coordType If 0, the returned x and y coordinates are
+ * returned relative to the screen;
+ * if 1, they are returned relative to the containing window.
+ */
void getImagePosition (out long x, out long y, in short coordType);
+ /**
+ * Obtain the width and height of the current onscreen view of the
+ * image. The extents returned do not account for
+ * any viewport clipping or the fact that the image may be
+ * partially or wholly obscured by other onscreen content.
+ * @note This method returns the size of the current onscreen
+ * view, and not the nominal or "original" size of the source
+ * image, in the event that the original image has been rescaled.
+ *
+ * @param width Back-filled with the x extents of the
+ * onscreen image (i.e. the image width in pixels)
+ * @param height Back-filled with the y extents of the
+ * onscreen image (i.e. the image height in pixels)
+ */
void getImageSize (out long width, out long height);
+
/**
+ * \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented ();
void unImplemented2 ();
void unImplemented3 ();
- void unImplemented4 ();
+ /** \endcond */
};
};
module Accessibility {
/**
- * LoginHelper:
+ * @brief An interface for use by assistive technologies by which
+ * they can access system information and services on a 'need to know'
+ * basis while the screen is locked, during user authentication, or
+ * during other sensitive operations.
*
* This interface is intended for use by assistive technologies
* and related user-enabling services, and by applications and
* service.
*
* Such 'applications' (for instance, screen lock dialogs and
- * security-enabled web browsers) use the @LoginHelper client
+ * security-enabled web browsers) use the ::LoginHelper client
* interfaces, and the bonobo-activation query service, to
- * query for assistive technologies which advertise the @LoginHelper
+ * query for assistive technologies which advertise the ::LoginHelper
* service. The client then queries these assistive technologies
- * for their device I/O requirements, via the @getDeviceReqs call.
- * The client may then issue the advisory request @setSafe (TRUE),
- * which requests that the @LoginHelper-implementing service make a
+ * for their device I/O requirements, via the ::getDeviceReqs call.
+ * The client may then issue the advisory request ::setSafe (TRUE),
+ * which requests that the ::LoginHelper -implementing service make a
* best-effort attempt to make itself more secure (for instance,
* an onscreen keyboard might turn off word prediction, and a
* screenreader may turn off keyboard echo via speech). The return
- * value of @setSafe is an advisory indication of whether this attempt
+ * value of ::setSafe is an advisory indication of whether this attempt
* was successful (no specific guarantees are implied).
* Once the 'security sensitive' state is exited, the client should
- * call @setSafe (FALSE).
+ * call ::setSafe (FALSE).
*
- * The return values from @getDeviceReqs inform the client of which
- * services the @LoginHelper service (e. g. assistive technology) needs
+ * The return values from ::getDeviceReqs inform the client of which
+ * services the ::LoginHelper service (e. g. assistive technology) needs
* in order to do its job. The client may use this information to
* loosen any restrictions on access which it may currently have in
* place (for instance, keyboard grabs, etc.). If it does not do so,
**/
interface LoginHelper : Bonobo::Unknown {
- /*
- * WindowInfo:
+ /**
* A structure containing info about toplevel X windows that
- * the @LoginHelper instance wishes to have raised.
+ * the ::LoginHelper instance wishes to have raised.
*
- * @winID: The windowing-system-dependeny Window ID of the toplevel window.
+ * @param winID: The windowing-system-dependeny Window ID of the toplevel window.
*/
struct WindowInfo {
/* string display; */
/*
* DeviceReq:
*
- * The system and device access and services which the @LoginHelper-implementing
+ * The system and device access and services which the LoginHelper-implementing
* assistive technology requires in order to enable the user to use the system.
*
*/
/**
* setSafe:
+ * @param safe_mode: \c TRUE if the client is requesting that 'safe mode' be
+ * initiated, \c FALSE if the client is advising that 'safe mode' may be
+ * exited, i.e. normal operation may be resumed.
*
* Request a LoginHelper to enter "safe" mode, or
* inform LoginHelper that "safe" mode may be exited.
- * If @safe_mode is %TRUE, but the return value is %FALSE,
+ * If \a safe_mode is \c TRUE, but the return value is \c FALSE,
* the requesting client may wish to deny services to the
- * %LoginHelper, for instance avoid raising its toplevels.
+ * ::LoginHelper, for instance avoid raising its toplevels.
* The return value is purely advisory, and no guarantees are
* intended about what the implementing LoginHelper will do
* to improve security when in "safe" mode.
*
- * Returns: whether the %LoginHelper is now "safe" or not.
+ * @returns: whether the ::LoginHelper is now "safe" or not.
**/
boolean setSafe (in boolean safe_mode);
/**
* getDeviceReqs:
*
- * Query a @LoginHelper for the types of
+ * Query a ::LoginHelper for the types of
* device I/O it requires, in order to do its job.
- * For instance, a @LoginHelper which needs to receive keyboard
+ * For instance, a ::LoginHelper which needs to receive keyboard
* events will include
* Accessibility_LoginHelper_CORE_KEYBOARD in this list.
*
- * Returns: A sequence of @LoginHelper_DeviceReq indicating
+ * @returns: A sequence of ::LoginHelper_DeviceReq indicating
* the device I/O required in order to facilitate end-user access
* to the system.
**/
*
* Get a list of window IDs that need raising on login.
*
- * Returns: a sequence containing window IDS for toplevels which
+ * @returns: a sequence containing window IDS for toplevels which
* need to be raised/made visible during user authentication, in
- * order for the @LoginHelper to facilitate end-user access to the
+ * order for the ::LoginHelper to facilitate end-user access to the
* system.
**/
WindowList getRaiseWindows ();
/**
+ * \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};
interface DeviceEventController;
+ /**
+ * The Registry is a service through which applications providing
+ * accessibility services (servers) can rendezvous with consumers of those
+ * services (Assistive Technologies). The Registry is the first "port of call" for
+ * accessible applications and for assistive technologies wishing to query and
+ * interact with those applications.
+ *
+ * The Registry service provides four basic functions to Assistive Technology (AT) clients:
+ * \li it provides a list of the applications who have registered with the AT-SPI
+ * framework, thereby announcing their participation in the AT-SPI framework;
+ * \li it allows AT clients to register for notification of changes in application
+ * state (at-spi Events);
+ * \li it dispatches/relays said events from participating applications to
+ * the registered listeners;
+ * \li it gives access to system device events via the associated DeviceEventController
+ * interface.
+ *
+ * From the point of view of accessible applications (i.e. AT-SPI service producers),
+ * the Registry is primarily a registration and event delivery service. Applications
+ * normally only call the registerApplication and deregisterApplication Registry methods,
+ * and its inherited EventListener::notifyEvent method.
+ *
+ * @note Although all application events are dispatched via the Registry, other AT client
+ * calls are serviced directly by the applications, rather than being relayed via the
+ * Registry. The AT client obtains references to these application objects
+ * via the enumeration of Desktop instances whose children are Application instances
+ * (Registry::getDesktopList) and via examination of the 'source' member of the Event
+ * structure.
+ *
+ * The Registry normally lives in its own process space; communication via Registry and
+ * both application services and AT clients takes place via IPC. A process space diagram
+ * illustrating the relationship between applications, Registry, and AT is shown below.
+ * @image html "http://developer.gnome.org/projects/gap/tech-docs/SPIBlockDiagram.png"
+ *
+ *
+ * @see Desktop, Application, Event, EventListener
+ **/
interface Registry : EventListener {
/**
- * registerApplication:
- * @application: a reference to the requesting @Application
- *
* Register a new application with the accessibility broker.
- *
+ * @param application: a reference to the requesting Application
**/
oneway void registerApplication (in Application application);
/**
+ * De-register an application previously registered with the broker.
* deregisterApplication:
- * @application: a reference to the @Application
+ * @param application: a reference to the Application
* to be deregistered.
- *
- * De-register an application previously registered with the broker.
- *
**/
void deregisterApplication (in Application application);
/**
- * registerGlobalEventListener:
- * @listener: a reference to the requesting @EventListener.
- * @eventName: a string which indicates the type of events about
- * which the client desires notification.
- *
* Register a client's interest in (all) application events of
* a certain type.
- *
+ * @param listener: a reference to the requesting ::EventListener.
+ * @param eventName: a string which indicates the type of events about
+ * which the client desires notification.
**/
void registerGlobalEventListener (in EventListener listener,
in string eventName);
/**
- * deregisterGlobalEventListener:
- * @listener: the requesting @EventListener
- * @eventName: a string indicating the type of events
+ * deregisterGlobalEventListenerAll:
+ * @param listener: the requesting EventListener
*
* Request that a previously registered client stop receiving
- * global notifications for events of a certain type.
+ * global notifications for all events for which it was registered.
*
**/
-
void deregisterGlobalEventListenerAll (in EventListener listener);
+
/**
* deregisterGlobalEventListener:
- * @listener: the requesting @EventListener
- * @eventName: a string indicating the type of events
+ * @param listener: the requesting EventListener
+ * @param eventName: a string indicating the type of events
*
* Request that a previously registered client stop receiving
* global notifications for events of a certain type.
*
**/
-
void deregisterGlobalEventListener (in EventListener listener,
- in string event_name);
+ in string eventName);
/**
* event types: "Window" "Desktop"
* "Window:Create" "Window:Destroy"
* getDesktopCount:
*
* Get the current number of desktops.
- * Returns: a short integer indicating the current number of
- * @Desktops.
+ * @returns a short integer indicating the current number of
+ * Desktops.
**/
short getDesktopCount ();
/**
* getDesktop:
- * @n: the index of the requested @Desktop.
+ * @n: the index of the requested Desktop.
*
* Get the nth accessible desktop.
*
- * Returns: a reference to the requested @Desktop.
+ * @returns a reference to the requested Desktop.
**/
Desktop getDesktop (in short n);
/**
- * getDesktopList:
- *
* Get a list of accessible desktops.
*
- * Returns: a sequence containing references to
- * the @Desktops.
+ * @returns: a sequence containing references to
+ * the Desktops.
**/
DesktopSeq getDesktopList ();
/**
- * getDeviceEventController:
+ * Obtain an object which can be used to request device event notifications.
*
- * Returns: an object implementing DeviceEventController
+ * @returns: an object implementing DeviceEventController
**/
DeviceEventController getDeviceEventController ();
- /**
+ /** \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented4 ();
void unImplemented5 ();
void unImplemented6 ();
+ /** \endcond */
};
- /* Deprecated, DO NOT USE! */
+ /** Deprecated, DO NOT USE! */
enum KeyEventType {
KEY_PRESSED,
KEY_RELEASED
};
+ /** Used to specify the event types of interest to an EventListener, or
+ * to identify the type of an event for which notification has been sent.
+ * @see EventTypeSeq, DeviceEvent::type
+ */
enum EventType {
- KEY_PRESSED_EVENT,
- KEY_RELEASED_EVENT,
- BUTTON_PRESSED_EVENT,
- BUTTON_RELEASED_EVENT
+ KEY_PRESSED_EVENT, /**< key on a keyboard device was pressed. */
+ KEY_RELEASED_EVENT, /**< key on a keyboard device was released. */
+ BUTTON_PRESSED_EVENT,/**< button on a non-keyboard human interface device
+ * (HID) was pressed */
+ BUTTON_RELEASED_EVENT /**< button on a non-keyboard human interface device
+ * (HID) was pressed */
};
+ /** Used when synthesizing keyboard input via DeviceEventController:generateKeyboardEvent.*/
enum KeySynthType {
- KEY_PRESS,
- KEY_RELEASE,
- KEY_PRESSRELEASE,
- KEY_SYM,
- KEY_STRING
+ KEY_PRESS,/** emulate the pressing of a hardware keyboard key. */
+ KEY_RELEASE,/** emulate the release of a hardware keyboard key. */
+ KEY_PRESSRELEASE,/** a hardware keyboard key is pressed and immediately released. */
+ KEY_SYM,/** a symbolic key event is generated, without specifying a hardware key.
+ * @note if the keysym is not present in the current keyboard map,
+ * the DeviceEventController instance has a limited ability to generate
+ * such keysyms on-the-fly. Reliability of generateKeyboardEvent calls
+ * using out-of-keymap keysyms will vary from system to system, and on the
+ * number of different out-of-keymap being generated in quick succession.
+ * In practice this is rarely significant, since the keysyms of interest to
+ * AT clients and keyboard emulators are usually part of the current keymap, i.e.
+ * present on the system keyboard for the current locale (even if a physical
+ * hardware keyboard is not connected.
+ */
+ KEY_STRING /** a string is converted to its equivalent keyboard events and emitted.
+ * If the string consists of complex character or composed characters
+ * which are not in the current keymap, string emission is subject to the
+ * out-of-keymap limitations described for KeySynthType::KEY_SYM.
+ * In practice this limitation primarily effects Chinese and Japanese locales.
+ */
};
enum ModifierType {
- MODIFIER_SHIFT,
- MODIFIER_SHIFTLOCK,
- MODIFIER_CONTROL,
- MODIFIER_ALT,
- MODIFIER_META,
+ MODIFIER_SHIFT, /** The left or right 'Shift' key */
+ MODIFIER_SHIFTLOCK, /** The ShiftLock or CapsLock key */
+ MODIFIER_CONTROL,/** 'Control'/'Ctrl' */
+ MODIFIER_ALT,/** The Alt key (as opposed to AltGr) */
+ MODIFIER_META,/** depending on the platform this may map to 'Window', 'Function', 'Meta',
+ * 'Menu', or 'NumLock'.
+ * Such 'Meta keys' will map to one of META, META2, META3.
+ * On X Windows platforms these META values map to
+ * the modifier masks Mod1Mask, Mod2Mask, Mod3Mask, e.g. an event having
+ * ModifierType::MODIFIER_META2 means that the 'Mod2Mask' bit is
+ * set in the corresponding XEvent.
+ */
MODIFIER_META2,
MODIFIER_META3,
- MODIFIER_NUMLOCK
+ MODIFIER_NUMLOCK/** A symbolic meta key name that is mapped by AT-SPI to the
+ * appropriate META value, for the convenience of the client.
+ */
};
+ /** A structure that encapsulates the characteristics of the event notifications
+ * that should be sent to an EventListener in response to a call to
+ * DeviceEventController::registerKeystrokeListener or
+ * DeviceEventController::registerDeviceEventListener. */
struct EventListenerMode {
- boolean synchronous;
- boolean preemptive;
- boolean global;
+ boolean synchronous; /**< If \c True, specifies that
+ * DeviceEventController should block while waiting
+ * for client to process the requested event notifications;
+ * ordinarily should be used only when client needs to perform
+ * operations synchronously with event delivery. Note that because
+ * of the architecture of device event systems in general,
+ * use of this flag may not block delivery of the event to
+ * the currently focussed application unless it is used in
+ * conjunction with the preemptive flag. */
+ boolean preemptive; /**< If \c True, specifies that
+ * Listener is allowed to pre-empt the delivery of the event,
+ * effectively "consuming" it such that it is not delivered
+ * to the currently focussed desktop application.
+ * Key events consumed via this API will not be
+ * available for use by other applications or services, so this
+ * option should be used sparingly. */
+ boolean global; /**< If \c True, specifies that
+ * Event notifications should be sent regardless of whether the
+ * currently focussed application participates in the AT-SPI
+ * infrastructure. On systems with the XEvIE X extension, this flag
+ * also allows access to events which are already subject to
+ * interception via a "system keygrab" (as described in the X Window System
+ * documentation for XGrabKey). The 'global' and 'preemptive' flags
+ * should only be used together for the purposes of registering
+ * "system global key shortcuts" i.e. command keys for use by the
+ * assistive technology. */
};
+ /**
+ * an unsigned short int consisting of zero or more of the following
+ * values OR'ed together:
+ *
+ * \li \c 1<<::KEY_PRESSED_EVENT = 1
+ * \li \c 1<<::KEY_RELEASED_EVENT = 2
+ * \li \c 1<<::BUTTON_PRESSED_EVENT = 3,
+ * \li \c 1<<::BUTTON_RELEASED_EVENT = 4
+ **/
typedef unsigned long ControllerEventMask;
+ /** A structure which encapsulates information about a device event. */
struct DeviceEvent {
- EventType type;
- long id;
- short hw_code;
- unsigned short modifiers;
- unsigned long timestamp;
- string event_string;
- boolean is_text;
+ EventType type; /**< Identifies the type of the containing DeviceEvent. */
+ long id; /**< an identifier which identifies this event in the event stream.
+ * On X Window systems this corresponds to the XEvent serial number.
+ */
+ short hw_code; /**< a numeric code which is hardware and system-dependent, identifying the
+ * specific hardware button or key on the device for which the event has
+ * occurred. On X Window systems, for global key notifications and for most
+ * non-global key notifications as well, this code corresponds to the
+ * XKeycode. For switch and button events it indicates the switch
+ * or button number.
+ * @note
+ * For technical reasons, this code may differ from the XKeycode
+ * when generated by Java applications for consumption by non-global
+ * key listeners. This is subject to change in future versions of the
+ * DeviceEventController implementation.
+ */
+
+ unsigned short modifiers; /**< an unsigned short int consisting of zero or more of the following
+ * values OR'ed together:
+ * \li \c 1<<::MODIFIER_SHIFT (=1, corresponds to Xlib's ShiftMask)
+ * \li \c 1<<::MODIFIER_SHIFTLOCK (=2, corresponds to Xlib's LockMask)
+ * \li \c 1<<::MODIFIER_CONTROL (=4, corresponds to Xlib's ControlMask)
+ * \li \c 1<<::MODIFIER_ALT (=8, corresponds to Xlib's Mod1Mask)
+ * \li \c 1<<::MODIFIER_META (=16, corresponds to Xlib's Mod2Mask)
+ * \li \c 1<<::MODIFIER_META2 (=32, corresponds to Xlib's Mod3Mask)
+ * \li \c 1<<::MODIFIER_META3 (=64, corresponds to Xlib's Mod4Mask)
+ **/
+ unsigned long timestamp; /**< an unsigned integer representing the time that the
+ * event occurred. On X Window systems this event is
+ * a time in milliseconds from some arbitrary starting
+ * point; it therefore has a cycle time of approximately
+ * 50 days.
+ */
+ string event_string; /**< A string representation of the event. If is_text is
+ * \c True, then this string represents the character or typographic
+ * sequence that would be received by a focussed text input field.
+ * event_string is in general suitable for exposure to the
+ * end-user for purposes of keyboard echo.
+ */
+ boolean is_text; /**< \c True if the event results in the insertion of characters
+ * into an input text buffer, or would do so if delivered to a focussed
+ * text input field. ¨Typographical¨ key events have this field set to
+ * \c True, whereas ¨control¨ key events generally do not.
+ */
};
+ /**
+ * A structure which defines the identity of a key for which notifications
+ * are to be requested. The data in the members of a ::KeyDefinition are used to
+ * determine which keyboard events 'match' the notification request filed by a client.
+ *
+ * @note Ordinarily a KeyDefinition specifies one and only one of the criteria below;
+ * the result of using a KeyDefinition with multiple members defined as nonzero is
+ * undefined.
+ *
+ * @param keycode if nonzero, the numeric, system-dependent value corresponding to a
+ * physical key on the keyboard. Keycode values have no semantic meaning to the end-user,
+ * and may depend on the user's hardware and operating environment. They therefore are
+ * rarely useful "as-is" to AT clients, unless the client has used operating system
+ * services to identify the hardward keycode associated with a particular key symbol.
+ * Notifications for key events requested by keycode are less dependent on modifier state
+ * than \c keysym based notifications, but some hardware (notably many laptops) may generate
+ * more than one keycode for the same physical key, depending on the state of physical
+ * shift/modifier keys.
+ * @param keysym if nonzero, the numeric value corresponding to the X Keysym of the key for which
+ * notification is requested. Note that the presence of active modifiers will affect
+ * whether notification for key events requested via "keysym" specification takes place,
+ * since the keysym depends on the modifier state for most keys.
+ * @param keystring if non-NULL, the string value of the inserted characters if the corresponding
+ * key event has ::KeyEvent:is_text set to \c True, or the string representing the
+ * 'name' of the key. On X11 systems, the string 'name' of non-printing keysyms corresponds
+ * to the values in "keysymdef.h" as provided by Xlib, with the leading "XK_" stripped off.
+ **/
struct KeyDefinition {
long keycode;
long keysym;
typedef sequence< EventType > KeyEventTypeSeq;
typedef sequence< EventType > EventTypeSeq;
+ /** This interface should be implemented by AT-SPI clients who wish to
+ * make use of the DeviceEventController to receive device event notifications.
+ * DeviceEvents include keyboard events and mouse button/motion events.
+ **/
interface DeviceEventListener : Bonobo::Unknown {
+ /** Notify an interested DeviceEventListener that a DeviceEvent has occurred.
+ * @returns \c True if the recipient/consumer wishes to consume the event, i.e.
+ * prevent it from being delivered to the desktop, \c False if the event should
+ * continue to be delivered as normal.
+ */
boolean notifyEvent (in DeviceEvent event);
+ /** \cond */
void unImplemented__ ();
void unImplemented_2_ ();
void unImplemented_3_ ();
void unImplemented_4_ ();
void unImplemented_5_ ();
void unImplemented_6_ ();
+ /** \endcond */
};
+ /**
+ * The interface via which clients request notification of device events, and
+ * through which device events may be simulated.
+ ***/
interface DeviceEventController : Bonobo::Unknown {
/**
- * registerKeystrokeListener:
- * @listener: a @DeviceEventListener which will intercept key events.
- * @keys: a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
- * @mask: a @ControllerEventMask filtering the intercepted key events.
- * @type: an @EventType mask that may created by ORing event types together.
- * @is_synchronous: a @boolean indicating whether the listener should
- * receive the events synchronously, potentially consuming them,
- * or just be notified asynchronously of those events that have
- * been generated.
- * Returns: %true if successful, %false if not
- *
* Register to intercept keyboard events, and either pass them on or
* consume them.
*
+ * @param listener: a DeviceEventListener which will intercept key events.
+ * @param keys: a KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
+ * @param mask: a ControllerEventMask filtering the intercepted key events.
+ * @param type: a KeyEventTypeSeq that may created by ORing event types together.
+ * @param mode: an EventListenerMode indicating whether the listener should
+ * receive the events synchronously, potentially consuming them,
+ * or just be notified asynchronously of those events that have
+ * been generated.
+ * @note Some platforms have limited support for global, preemptive EventListenerMode.
+ * Such a registration may fail if another client already has priority for preemptive
+ * access to one or more of the members of the KeySet. AT consumers have the option
+ * of re-trying the request without the global flag, or without the preemptive flag,
+ * or of re-trying with a different KeySet. The best support for pre-emptive
+ * global keyboard listeners is provided on platforms whose Xserver implementation
+ * provides the XEvIE extension.
+ *
+ * @returns \c True if the DeviceEventListener was successfully registered
+ * for the requested KeySet, ControllerEventMask, event types, and EventListenerMode;
+ * otherwise returns \c False.
**/
boolean registerKeystrokeListener (in DeviceEventListener listener,
in KeySet keys,
in EventListenerMode mode);
/**
- * deregisterKeystrokeListener:
- * @listener: a @DeviceEventListener which will intercept key events.
- * @keys: a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
- * @mask: a @ControllerEventMask filtering the intercepted key events.
- * @type: an @EventType mask that may created by ORing event types together.
- *
- * Returns: void
- *
* De-register a previously registered keyboard eventlistener.
- *
+ * @param listener: a DeviceEventListener which will intercept key events.
+ * @param keys: a KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
+ * @param mask: a ControllerEventMask filtering the intercepted key events.
+ * @param type: an EventType mask that may created by ORing event types together.
**/
void deregisterKeystrokeListener (in DeviceEventListener listener,
in KeySet keys,
in KeyEventTypeSeq type);
/**
- * registerDeviceEventListener:
- * @listener: a @DeviceEventListener which will intercept events.
- * @typeseq: an @EventTypeSeq indicating which event types to listen for.
- * Returns: %true if successful, %false if not
- *
* Register to intercept events, and either pass them on or
* consume them. To listen to keyboard events use registerKeystrokeListener
* instead.
- *
+ * @param listener: a DeviceEventListener which will intercept events.
+ * @param typeseq: an EventTypeSeq indicating which event types to listen for.
+ * @returns \c True if successful, \c False if not
**/
boolean registerDeviceEventListener (in DeviceEventListener listener,
in EventTypeSeq typeseq);
/**
- * deregisterDeviceEventListener:
- * @listener: a @DeviceEventListener which will intercept events.
- * @typeseq: an @EventTypeSeq indicating which event types to stop
- * listening for.
- *
- * Returns: void
- *
* De-register a previously registered keyboard eventlistener.
- *
+ * @param listener: a DeviceEventListener which will intercept events.
+ * @param typeseq: an EventTypeSeq indicating which event types to stop
+ * listening for.
**/
void deregisterDeviceEventListener (in DeviceEventListener listener,
in EventTypeSeq typeseq);
+ /**
+ * Notify the Registry instance that a device event has taken place, and
+ * allow pre-emptive listeners the opportunity to 'consume' the event
+ * and thus prevent its further issuance/forwarding. This is the
+ * method used by accessibility bridges to forward "toolkit dependent"
+ * device events to the Registry from the application's process space.
+ *
+ * @note AT clients do not normally need to use this method, it is intended for use
+ * by toolkit bridges and special-purpose applications.
+ *
+ * @returns \c True if the event was consumed by a (pre-emptive) listener,
+ * \c False if not (in which case the device event will be forwarded
+ * as normal to any application which would normally receive it, e.g.
+ * the currently active application in the case of mouse or keyboard events).
+ **/
boolean notifyListenersSync (in DeviceEvent event);
+ /**
+ * Notify the Registry instance that a device event has taken place in
+ * an asynchronous manner. This is the
+ * method used by accessibility bridges to forward "toolkit dependent"
+ * device events to the Registry from the application's process space.
+ * If the event in question is potentially pre-emptible.
+ * ::notifyListenersSync should be used instead.
+ *
+ * @note AT clients do not normally need to use this method, it is intended for use
+ * by toolkit bridges and special-purpose applications.
+ **/
oneway void notifyListenersAsync (in DeviceEvent event);
/**
- * generateKeyboardEvent:
- * @keycode: a long integer indicating the keycode of
+ * Synthesize a keyboard event.
+ * @param keycode: a long integer indicating the keycode of
* the keypress to be synthesized.
- * @keystring: an optional UTF-8 string indicating a complex
+ * @param keystring: an optional UTF-8 string indicating a complex
* keyboard input event.
- * @type: a #KeySynthType indicating the type of event(s) to be
+ * @param type: a KeySynthType indicating the type of event(s) to be
* synthesized: a key press, release, press-release pair,
* or a complex input string (for instance from an
* internationalized or complex text input method, or
* a composed character).
*
- * Note that @keycode may be truncated before being
+ * @note keycode may be truncated before being
* processed, as keycode length may be platform-dependent
* and keycode ranges are generally much smaller than
* CORBA_long.
- * One or the other of @keycode or @keystring are generally NULL,
- * (but not both), depending on the value of @type.
+ * One or the other of keycode or keystring are generally NULL,
+ * (but not both), depending on the value of \c type.
*
- * Returns: void
- *
- * Synthesize a keyboard event.
- *
**/
void generateKeyboardEvent (in long keycode,
in string keystring,
in KeySynthType type);
/**
- * generateMouseEvent:
- * @x: a long integer indicating the screen x coord for the mouse event.
- * @y: a long integer indicating the screen y coord for the mouse event.
- * @eventName: a string indicating the type of mouse event, e.g. "button1up"
- * Returns: void
- *
* Synthesize a mouse event.
- *
+ * @param x: a long integer indicating the screen x coord for the mouse event.
+ * @param y: a long integer indicating the screen y coord for the mouse event.
+ * @param eventName: a string indicating the type of mouse event, e.g. "button1up"
**/
void generateMouseEvent (in long x, in long y, in string eventName);
- /**
+ /** \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};
module Accessibility {
+ /**
+ * RelationType specifies a relationship between objects (possibly one-to-many or many-to-one)
+ * outside of the normal parent/child hierarchical relationship. It allows better semantic
+ * identification of how objects are associated with one another.
+ * For instance the RELATION_LABELLED_BY relationship may be used to identify labelling information
+ * that should accompany the accessibleName property when presenting an object's content or identity
+ * to the end user. Similarly, RELATION_CONTROLLER_FOR can be used to further specify the context
+ * in which a valuator is useful, and/or the other UI components which are directly effected by
+ * user interactions with the valuator. Common examples include association of scrollbars with
+ * the viewport or panel which they control.
+ */
enum RelationType {
+ /** Not a meaningful relationship; clients should not normally encounter this RelationType value. */
RELATION_NULL,
+ /** Object is a label for one or more other objects. */
RELATION_LABEL_FOR,
+ /** Object is labelled by one or more other objects. */
RELATION_LABELLED_BY,
+ /** Object is an interactive object which modifies the state, onscreen location, or other attributes
+ * of one or more target objects. */
RELATION_CONTROLLER_FOR,
+ /** Object state, position, etc. is modified/controlled by user interaction with one or
+ * more other objects. For instance a viewport or scroll pane may be CONTROLLED_BY scrollbars. */
RELATION_CONTROLLED_BY,
+ /** Object has a grouping relationship (e.g. ¨same group as¨) to one or more other objects. */
RELATION_MEMBER_OF,
+ /** Object is a tooltip associated with another object. */
RELATION_TOOLTIP_FOR,
+ /** Reserved for future use. */
RELATION_NODE_CHILD_OF,
+ /** Used to indicate that a relationship exists, but its type is not specified in the enumeration
+ * and must be obtained via a call to getRelationTypeName. */
RELATION_EXTENDED,
+ /** Object renders content which flows logically to another object.
+ * For instance, text in a paragraph may flow to another object which is not the
+ * ¨next sibling¨ in the accessibility hierarchy. */
RELATION_FLOWS_TO,
+ /** Reciprocal of RELATION_FLOWS_TO. */
RELATION_FLOWS_FROM,
+ /** Object is visually and semantically considered a subwindow of another object, even though
+ * it is not the object's child. Useful when dealing with embedded applications and other cases
+ * where the widget hierarchy does not map cleanly to the onscreen presentation. */
RELATION_SUBWINDOW_OF,
+ /** Similar to SUBWINDOW_OF, but specifically used for cross-process embedding. */
RELATION_EMBEDS,
+ /** Reciprocal of RELATION_EMBEDS; Used to denote content rendered by embedded renderers that
+ * live in a separate process space from the embedding context. */
RELATION_EMBEDDED_BY,
+ /** Denotes that the object is a transient window or frame associated with another onscreen object.
+ * Similar to TOOLTIP_FOR, but more general. Useful for windows which are technically
+ * toplevels but which, for one or more reasons, do not explicitly cause their associated
+ * window to lose ¨window focus¨. Creation of a ROLE_WINDOW object with the POPUP_FOR relation
+ * usually requires some presentation action on the part of assistive technology clients, even though
+ * the previous toplevel ROLE_FRAME object may still be the active window. */
RELATION_POPUP_FOR,
+ /** This is the reciprocal relation to RELATION_POPUP_FOR. */
+ RELATION_PARENT_WINDOW_OF,
+ /** Do not use as a parameter value, used to determine the size of the enumeration. */
RELATION_LAST_DEFINED
};
- /*
- * This interface inherits from a base class implementing ref counts.
+ /**
+ * An interface via which objects' non-hierarchical relationships to one another
+ * are indicated. An instance of Relations represents a "one-to-many" correspondance.
+ *
+ * @note This interface inherits from a base class implementing ref counts.
*/
-
interface Relation : Bonobo::Unknown {
+
+ /** @returns the RelationType of this Relation. */
RelationType getRelationType ();
- string getRelationTypeName ();
+
+ /** @returns an unlocalized string representing the relation type. */
+ string getRelationTypeName ();
+
+ /** @returns the number of objects to which this relationship applies. */
short getNTargets ();
+
+ /** @returns an Object which is the 'nth'target of this Relation, e.g. the Object at index i
+ * in the list of Objects having the specified relationship to this Accessible.
+ * \note This target should always implement Accessible, though it is returned as an Object.
+ * (In this respect this method is probably ill-specified.)
+ **/
Object getTarget (in short index);
- /* placeholders for future expansion */
+
+ /** \cond placeholders for future expansion */
void unImplemented ();
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};
module Accessibility {
enum Role {
+ /** A Role indicating an error condition, such as uninitialized Role data. */
ROLE_INVALID,
- /* Object is a label indicating the keyboard accelerators for the parent */
+ /** Object is a label indicating the keyboard accelerators for the parent */
ROLE_ACCELERATOR_LABEL,
- /* Object is used to alert the user about something */
+ /** Object is used to alert the user about something */
ROLE_ALERT,
- /* Object contains a dynamic or moving image of some kind */
+ /** Object contains a dynamic or moving image of some kind */
ROLE_ANIMATION,
- /* Object is a 2d directional indicator */
+ /** Object is a 2d directional indicator */
ROLE_ARROW,
- /* Object contains one or more dates, usually arranged into a 2d list */
+ /** Object contains one or more dates, usually arranged into a 2d list */
ROLE_CALENDAR,
- /* Object that can be drawn into and is used to trap events */
+ /** Object that can be drawn into and is used to trap events */
ROLE_CANVAS,
- /*
+ /**
* A choice that can be checked or unchecked and provides a separate
* indicator for the current state.
*/
ROLE_CHECK_BOX,
- /* A menu item that behaves like a check box (see ROLE_CHECK_BOX) */
+ /** A menu item that behaves like a check box (see ROLE_CHECK_BOX) */
ROLE_CHECK_MENU_ITEM,
- /* A specialized dialog that lets the user choose a color. */
+ /** A specialized dialog that lets the user choose a color. */
ROLE_COLOR_CHOOSER,
- /* The header for a column of data */
+ /** The header for a column of data */
ROLE_COLUMN_HEADER,
- /* A list of choices the user can select from */
+ /** A list of choices the user can select from */
ROLE_COMBO_BOX,
- /* An object which allows entry of a date */
+ /** An object which allows entry of a date */
ROLE_DATE_EDITOR,
- /* An inconifed internal frame within a DESKTOP_PANE */
+ /** An inconifed internal frame within a DESKTOP_PANE */
ROLE_DESKTOP_ICON,
- /*
+ /**
* A pane that supports internal frames and iconified versions of those
* internal frames.
*/
ROLE_DESKTOP_FRAME,
- /*
+ /**
* An object that allows a value to be changed via rotating a visual element,
* or which displays a value via such a rotating element.
*/
ROLE_DIAL,
- /* A top level window with title bar and a border */
+ /** A top level window with title bar and a border */
ROLE_DIALOG,
- /*
+ /**
* A pane that allows the user to navigate through and select the contents
* of a directory
*/
ROLE_DIRECTORY_PANE,
- /*
+ /**
* A specialized dialog that displays the files in the directory and lets
* the user select a file, browse a different directory, or specify a
* filename.
*/
ROLE_DRAWING_AREA,
- /*
+ /**
* An object used for drawing custom user interface elements.
*/
ROLE_FILE_CHOOSER,
- /*
+ /**
* A object that fills up space in a user interface
*/
ROLE_FILLER,
- /* XXX Don't know sure about this. */
+ /** XXX Don't use, reserved for future use. */
ROLE_FOCUS_TRAVERSABLE,
- /* Allows selection of a display font */
+ /** Allows selection of a display font */
ROLE_FONT_CHOOSER,
- /* A top level window with a title bar, border, menubar, etc. */
+ /** A top level window with a title bar, border, menubar, etc. */
ROLE_FRAME,
- /* A pane that is guaranteed to be painted on top of all panes beneath it */
+ /** A pane that is guaranteed to be painted on top of all panes beneath it */
ROLE_GLASS_PANE,
- /*
+ /**
* A document container for HTML, whose children
* represent the document content.
*/
ROLE_HTML_CONTAINER,
- /* A small fixed size picture, typically used to decorate components */
+ /** A small fixed size picture, typically used to decorate components */
ROLE_ICON,
- /* An image, typically static. */
+ /** An image, typically static. */
ROLE_IMAGE,
- /* A frame-like object that is clipped by a desktop pane. */
+ /** A frame-like object that is clipped by a desktop pane. */
ROLE_INTERNAL_FRAME,
- /* An object used to present an icon or short string in an interface */
+ /** An object used to present an icon or short string in an interface */
ROLE_LABEL,
- /*
+ /**
* A specialized pane that allows its children to be drawn in layers,
* providing a form of stacking order.
*/
ROLE_LAYERED_PANE,
- /*
+ /**
* An object that presents a list of objects to the user and allows the
* user to select one or more of them.
*/
ROLE_LIST,
- /* An object that represents an element of a list. */
+ /** An object that represents an element of a list. */
ROLE_LIST_ITEM,
- /*
+ /**
* An object usually found inside a menu bar that contains a list of
* actions the user can choose from.
*/
ROLE_MENU,
- /*
+ /**
* An object usually drawn at the top of the primary dialog box of an
* application that contains a list of menus the user can choose from.
*/
ROLE_MENU_BAR,
- /*
+ /**
* An object usually contained in a menu that presents an action the
* user can choose.
*/
ROLE_MENU_ITEM,
- /* A specialized pane whose primary use is inside a DIALOG */
+ /** A specialized pane whose primary use is inside a DIALOG */
ROLE_OPTION_PANE,
- /* An object that is a child of a page tab list */
+ /** An object that is a child of a page tab list */
ROLE_PAGE_TAB,
- /*
+ /**
* An object that presents a series of panels (or page tabs), one at a time,
* through some mechanism provided by the object.
*/
ROLE_PAGE_TAB_LIST,
- /* A generic container that is often used to group objects. */
+ /** A generic container that is often used to group objects. */
ROLE_PANEL,
- /*
+ /**
* A text object uses for passwords, or other places where the text
* content is not shown visibly to the user.
*/
ROLE_PASSWORD_TEXT,
- /*
+ /**
* A temporary window that is usually used to offer the user a list of
* choices, and then hides when the user selects one of those choices.
*/
ROLE_POPUP_MENU,
- /* An object used to indicate how much of a task has been completed. */
+ /** An object used to indicate how much of a task has been completed. */
ROLE_PROGRESS_BAR,
- /*
+ /**
* An object the user can manipulate to tell the application to do
* something.
*/
ROLE_PUSH_BUTTON,
- /*
+ /**
* A specialized check box that will cause other radio buttons in the
* same group to become uncghecked when this one is checked.
*/
ROLE_RADIO_BUTTON,
- /* Object is both a menu item and a "radio button" (see ROLE_RADIO_BUTTON) */
+ /** Object is both a menu item and a "radio button" (see ROLE_RADIO_BUTTON) */
ROLE_RADIO_MENU_ITEM,
- /*
+ /**
* A specialized pane that has a glass pane and a layered pane as its
* children.
*/
ROLE_ROOT_PANE,
- /* The header for a row of data */
+ /** The header for a row of data */
ROLE_ROW_HEADER,
- /*
+ /**
* An object usually used to allow a user to incrementally view a large
- * amount of data.
+ * amount of data by moving the bounds of a viewport along a one-dimensional axis.
*/
ROLE_SCROLL_BAR,
- /*
+ /**
* An object that allows a user to incrementally view a large amount
- * of information.
+ * of information. ROLE_SCROLL_PANE objects are usually accompanied by
+ * ROLE_SCROLL_BAR controllers, on which the RELATION_CONTROLLER_FOR and
+ * RELATION_CONTROLLED_BY reciprocal relations are set; \see
+ * Accessibility::RelationSet.
*/
ROLE_SCROLL_PANE,
- /*
+ /**
* An object usually contained in a menu to provide a visible and
* logical separation of the contents in a menu.
*/
ROLE_SEPARATOR,
- /* An object that allows the user to select from a bounded range */
+ /** An object that allows the user to select from a bounded range */
ROLE_SLIDER,
- /*
+ /**
* An object which allows one of a set of choices to be selected,
- * and which displays the current choice.
+ * and which displays the current choice. Unlike ROLE_SCROLL_BAR,
+ * ROLE_SLIDER objects need not control 'viewport'-like objects.
*/
ROLE_SPIN_BUTTON,
- /* A specialized panel that presents two other panels at the same time. */
+ /** A specialized panel that presents two other panels at the same time. */
ROLE_SPLIT_PANE,
- /* Object displays non-quantitative status information (c.f. ROLE_PROGRESS_BAR) */
+ /** Object displays non-quantitative status information (c.f. ROLE_PROGRESS_BAR) */
ROLE_STATUS_BAR,
- /* An object used to repesent information in terms of rows and columns. */
+ /** An object used to repesent information in terms of rows and columns. */
ROLE_TABLE,
+ /** A 'cell' or discrete child within a Table. \note Table cells need not have ROLE_TABLE_CELL,
+ * other RoleType values are valid as well. */
ROLE_TABLE_CELL,
+ /** An object which labels a particular column in a Table. */
ROLE_TABLE_COLUMN_HEADER,
+ /** An object which labels a particular row in a Table. Table rows and columns may also be
+ * labelled via the RELATION_LABEL_FOR/RELATION_LABELLED_BY relationships;
+ * \see Accessibility::RelationSet. */
ROLE_TABLE_ROW_HEADER,
- /* Object allows menu to be removed from menubar and shown in its own window. */
+ /** Object allows menu to be removed from menubar and shown in its own window. */
ROLE_TEAROFF_MENU_ITEM,
- /* An object that emulates a terminal */
+ /** An object that emulates a terminal */
ROLE_TERMINAL,
- /* An object that presents text to the user */
+ /** An object that presents text to the user, of nonspecific type. */
ROLE_TEXT,
- /*
+ /**
* A specialized push button that can be checked or unchecked, but does
* not procide a separate indicator for the current state.
*/
ROLE_TOGGLE_BUTTON,
- /*
+ /**
* A bar or palette usually composed of push buttons or toggle buttons
*/
ROLE_TOOL_BAR,
- /*
+ /**
* An object that provides information about another object
*/
ROLE_TOOL_TIP,
- /* An object used to repsent hierarchical information to the user. */
+ /** An object used to repsent hierarchical information to the user. */
ROLE_TREE,
- /* An object that presents both tabular and hierarchical info to the user */
+ /** An object that presents both tabular and hierarchical info to the user */
ROLE_TREE_TABLE,
- /*
+ /**
* The object contains some Accessible information, but its role is
- * not known.
+ * not known.
*/
ROLE_UNKNOWN,
- /* An object usually used in a scroll pane. */
+ /** An object usually used in a scroll pane, or to otherwise clip a larger object or
+ * content renderer to a specific onscreen viewport. */
ROLE_VIEWPORT,
- /* A top level window with no title or border */
+ /** A ¨top level window¨ with no title or border. */
ROLE_WINDOW,
- /*
+ /**
* means that the role for this item is known, but not included in the
* core enumeration
*/
ROLE_EXTENDED,
- /* An object that serves as a document header. */
+ /** An object that serves as a document header. */
ROLE_HEADER,
- /* An object that serves as a document footer. */
+ /** An object that serves as a document footer. */
ROLE_FOOTER,
- /* An object which is contains a paragraph of text content. */
+ /** An object which is contains a single paragraph of text content. \see also ROLE_TEXT. */
ROLE_PARAGRAPH,
- /*
+ /**
* An object which describes margins and tab stops, etc.
* for text objects which it controls
* (should have CONTROLLER_FOR relation to such).
*/
ROLE_RULER,
- /*
+ /**
* An object corresponding to the toplevel accessible of an
* application, which may contain ROLE_FRAME objects or other
* accessible objects. Children of AccessibleDesktop objects
* are generally ROLE_APPLICATION objects.
*/
ROLE_APPLICATION,
- /*
+ /**
* The object is a dialog or list containing items for insertion
* into an entry widget, for instance a list of words for completion
* of a text entry.
*/
ROLE_AUTOCOMPLETE,
- /*
+ /**
* The object is an editable text object in a toolbar.
*/
ROLE_EDITBAR,
- /*
+ /**
* The object is an embedded component container. This role is a
* "grouping" hint that the contained objects share a context which is
* different from the container in which this accessible is embedded.
* for embedding of out-of-process component, "panel applets", etc.
*/
ROLE_EMBEDDED,
- /* not a valid role, used for finding end of enumeration. */
+
+ /**
+ * The object is a link to some other content, for instance to a URI in this or another
+ * document. ROLE_LINK can occur primarily in two situations; as the role of an
+ * object returned via the Hypertext::getLink, or, more importantly, as the role
+ * of a standalone object that implements the Hypertext interface but points to only
+ * one link object.
+ *
+ * @note NOT SURE ABOUT THIS ONE, the description makes it sound pretty ropy.
+ * Why aren't links just identified via the Hypertext interface? For non-textual
+ * hyperlinks (as allowed in XHTML 2.0), shouldn't this role be ROLE_IMAGE
+ * or ROLE_ICON?
+ *
+ * @since AT-SPI 1.7.0
+ */
+ ROLE_LINK,
+ /**
+ * The object is a component whose textual content may be entered or modified by the user,
+ * provided STATE_EDITABLE is present.
+ * @note a readonly ROLE_ENTRY object (i.e. where STATE_EDITABLE is not present) implies a
+ * read-only ¨text field¨ in a form, as opposed to a title, label, or caption.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ ROLE_ENTRY,
+ /**
+ * The object is a graphical depiction of quantitative data. It may contain multiple
+ * subelements whose attributes and/or description may be queried to obtain both the
+ * quantitative data and information about how the data is being presented.
+ * The LABELLED_BY relation is particularly important in interpreting objects of this type,
+ * as is the accessible-description property.
+ * @see ROLE_CAPTION
+ *
+ * @since AT-SPI 1.7.0
+ */
+ ROLE_CHART,
+ /**
+ * The object contains descriptive information, usually textual, about another user interface
+ * element such as a table, chart, or image.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ ROLE_CAPTION,
+ /**
+ * The object is a visual frame or container which contains a view of document content.
+ * Document frames may occur within another Document instance, in which case the second
+ * document may be said to be embedded in the containing instance. HTML frames are
+ * often ROLE_DOCUMENT_FRAME. Either this object, or a singleton descendant, should implement
+ * the Document interface.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ ROLE_DOCUMENT_FRAME,
+ /**
+ * The object serves as a heading for content which follows it in a document.
+ * The 'heading level' of the heading, if availabe, may be obtained by
+ * querying the object's attributes.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ ROLE_HEADING,
+ /**
+ * The object is a containing instance which encapsulates a page of
+ * information. ROLE_PAGE is used in documents and content which support
+ * a paginated navigation model.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ ROLE_PAGE,
+ /**
+ * The object is a containing instance of document content which constitutes
+ * a particular 'logical' section of the document. The type of content within
+ * a section, and the nature of the section division itself, may be obtained
+ * by querying the object's attributes. Sections may be nested.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ ROLE_SECTION,
+
+ /** not a valid role, used for finding end of enumeration. */
ROLE_LAST_DEFINED
};
};
module Accessibility {
+ /**
+ * An interface which indicates that an object exposes a 'selection' model,
+ * allowing the selection of one or more of its children. Read-only Selection
+ * instances are possible, in which case the interface is used to programmatically
+ * determine the selected-ness of its children. A selected child has ::State::STATE_SELECTED,
+ * and a child which may hypothetically be selected (though possibly not programmatically
+ * selectable) has ::State::STATE_SELECTABLE.
+ * @note Events emitted by implementors of Selection include:
+ * \li \c "object:selection-changed" An instance of Selection has undergone a change in the
+ * 'selected-ness' of its children, i.e. had a selection added,
+ * removed, and/or modified. Usually accompanied by
+ * corresponding \c "object:state-changed:selected" events
+ * from the corresponding children, unless the children are
+ * previously un-queried via AT-SPI and the Selection instance
+ * has ::State::STATE_MANAGES_DESCENDANTS.
+ **/
interface Selection : Bonobo::Unknown {
+ /**
+ * The number of children of a Selection implementor which are
+ * currently selected.
+ */
readonly attribute long nSelectedChildren;
+ /**
+ * Get the i-th selected Accessible child of a Selection.
+ * @note \c selectedChildIndex refers to the index in the list of
+ * 'selected' children as opposed to the more general 'child index'
+ * of an object; as such it generally differs from that used in
+ * Accessible::getChildAtIndex() or returned by
+ * Accessible::getIndexInParent().
+ * \c selectedChildIndex must lie between 0
+ * and Selection::nSelectedChildren-1, inclusive.
+ * @param selectedChildIndex: a long integer indicating which of the
+ * selected children of an object is being requested.
+ * @returns a pointer to a selected Accessible child object,
+ * specified by \c selectedChildIndex.
+ */
Accessible getSelectedChild (in long selectedChildIndex);
+ /**
+ * Add a child to the selected children list of a Selection.
+ * @note For Selection implementors that only allow
+ * single selections, this call may result in the
+ * replacement of the (single) current
+ * selection. The call may return \c False if
+ * the child is not selectable (i.e. does not have ::State::STATE_SELECTABLE),
+ * if the user does not have permission to change the selection,
+ * or if the Selection instance does not have ::State::STATE_SENSITIVE.
+ *
+ * @param childIndex: a long integer indicating which child of the
+ * Selection is to be selected.
+ *
+ * @returns \c True if the child was successfully selected,
+ * \c False otherwise.
+ */
boolean selectChild (in long childIndex);
+ /**
+ * Remove a child to the selected children list of a Selection.
+ * @note \c childIndex is the index in the selected-children list,
+ * not the index in the parent container. \c selectedChildIndex in this
+ * method, and \c childIndex in Selection::selectChild
+ * are asymmettric.
+ *
+ * @param selectedChildIndex: a long integer indicating which of the
+ * selected children of the Selection is to be deselected. The index
+ * is a zero-offset index into the 'selected child list', not
+ * a zero-offset index into the list of all children of the Selection.
+ *
+ * @returns \c True if the child was successfully deselected,
+ * \c False otherwise.
+ *
+ * @see deselectChild
+ **/
boolean deselectSelectedChild (in long selectedChildIndex);
+ /**
+ * Determine whether a particular child of an Selection implementor
+ * is currently selected. Note that \c childIndex is the zero-offset
+ * index into the standard Accessible container's list of children.
+ *
+ * @param childIndex: an index into the Selection's list of children.
+ *
+ * @returns \c True if the specified child is currently selected,
+ * \c False otherwise.
+ **/
boolean isChildSelected (in long childIndex);
+ /**
+ * Attempt to select all of the children of a Selection implementor.
+ * Not all Selection implementors support this operation (for instance,
+ * implementations which support only "single selection" do not support this operation).
+ *
+ * @returns \c True if successful, \c False otherwise.
+ */
boolean selectAll ();
+ /**
+ * Attempt to clear all selections (i.e. deselect all children) of a Selection.
+ * Not all Selection implementations allow the removal of all selections.
+ *
+ * @note this operation may fail if the object must have at least one selected child,
+ * if the user does not have permission to change the selection, or if the Selection
+ * does not have ::State::STATE_SENSITIVE.
+ *
+ * @returns \c True if the selections were successfully cleared, \c False otherwise.
+ */
boolean clearSelection ();
-
/**
* unImplemented:
*
enum StateType {
STATE_INVALID,
- /* Indicates a window is currently the active window */
+ /** Indicates a window is currently the active window, or is an active subelement within a container or table **/
STATE_ACTIVE,
- /* Indicates that the object is armed */
+ /** Indicates that the object is armed */
STATE_ARMED,
- /* Indicates the current object is busy */
+ /**
+ * Indicates the current object is busy, i.e. onscreen representation is in the process of changing, or
+ * the object is temporarily unavailable for interaction due to activity already in progress.
+ */
STATE_BUSY,
- /* Indicates this object is currently checked */
+ /** Indicates this object is currently checked */
STATE_CHECKED,
- /* Indicates this object is collapsed */
+ /** Indicates this object is collapsed */
STATE_COLLAPSED,
- /* Indicates that this object no longer contains a backing widget */
+ /** Indicates that this object no longer has a valid backing widget
+ * (for instance, if its peer object has been destroyed) */
STATE_DEFUNCT,
- /* Indicates the user can change the contents of this object */
+ /** Indicates the user can change the contents of this object */
STATE_EDITABLE,
- /* Indicates that this object is enabled */
+ /** Indicates that this object is enabled, i.e. that it currently reflects some application state.
+ * Objects that are "greyed out" may lack this state, and may lack the STATE_SENSITIVE if direct user
+ * interaction cannot cause them to acquire STATE_ENABLED. @see STATE_SENSITIVE.
+ */
STATE_ENABLED,
- /* Indicates this object allows progressive disclosure of its children */
+ /** Indicates this object allows progressive disclosure of its children */
STATE_EXPANDABLE,
- /* Indicates this object its expanded */
+ /** Indicates this object its expanded */
STATE_EXPANDED,
- /*
+ /**
* Indicates this object can accept keyboard focus, which means all
* events resulting from typing on the keyboard will normally be passed
* to it when it has focus
*/
STATE_FOCUSABLE,
- /* Indicates this object currently has the keyboard focus */
+ /** Indicates this object currently has the keyboard focus */
STATE_FOCUSED,
- /* Indicates that the object has an associated tooltip */
+ /** Indicates that the object has an associated tooltip */
STATE_HAS_TOOLTIP,
- /* Indicates the orientation of thsi object is horizontal */
+ /** Indicates the orientation of thsi object is horizontal */
STATE_HORIZONTAL,
- /* Indicates this object is minimized and is represented only by an icon */
+ /** Indicates this object is minimized and is represented only by an icon */
STATE_ICONIFIED,
- /*
+ /**
* Indicates something must be done with this object before the user can
* interact with an object in a different window.
*/
STATE_MODAL,
- /* Indicates this (text) object can contain multiple lines of text */
+ /** Indicates this (text) object can contain multiple lines of text */
STATE_MULTI_LINE,
- /*
+ /**
* Indicates this object allows more than one of its children to be
- * selected at the same time
+ * selected at the same time, or in the case of text objects,
+ * that the object supports non-contiguous text selections.
*/
STATE_MULTISELECTABLE,
- /* Indicates this object paints every pixel within its rectangular region. */
+ /** Indicates this object paints every pixel within its rectangular region.
+ * It also indicates an alpha value of unity, if it supports alpha blending.
+ */
STATE_OPAQUE,
- /* Indicates this object is currently pressed */
+ /** Indicates this object is currently pressed */
STATE_PRESSED,
- /* Indicates the size of this object is not fixed */
+ /** Indicates the size of this object's size is not fixed */
STATE_RESIZABLE,
- /*
+ /**
* Indicates this object is the child of an object that allows its
* children to be selected and that this child is one of those children
* that can be selected.
*/
STATE_SELECTABLE,
- /*
+ /**
* Indicates this object is the child of an object that allows its
* children to be selected and that this child is one of those children
* that has been selected.
*/
STATE_SELECTED,
- /* Indicates this object is sensitive */
+ /** Indicates this object is sensitive, e.g. to user interaction.
+ * STATE_SENSITIVE usually accompanies STATE_ENABLED for user-actionable controls,
+ * but may be found in the absence of STATE_ENABLED if the current visible state of the
+ * control is "disconnected" from the application state. In such cases, direct user interaction
+ * can often result in the object gaining STATE_SENSITIVE, for instance if a user makes
+ * an explicit selection using an object whose current state is ambiguous or undefined.
+ * @see STATE_ENABLED, STATE_INDETERMINATE. */
STATE_SENSITIVE,
- /*
+ /**
* Indicates this object, the object's parent, the object's parent's
- * parent, and so on, are all visible
+ * parent, and so on, are all 'shown' to the end-user, i.e.
+ * subject to "exposure" if blocking or obscuring objects do not interpose
+ * between this object and the top of the window stack.
*/
STATE_SHOWING,
- /* Indicates this (text) object can contain only a single line of text */
+ /** Indicates this (text) object can contain only a single line of text */
STATE_SINGLE_LINE,
- /* Indicates that this object's index within parent information may be invalid */
+ /** Indicates that the information returned for this object may no longer be
+ * synchronized with the application state. This can occur if the object has STATE_TRANSIENT,
+ * and can also occur towards the end of the object peer's lifecycle. */
STATE_STALE,
- /* Indicates this object is transient */
+ /** Indicates this object is transient */
STATE_TRANSIENT,
- /* Indicates the orientation of this object is vertical */
+ /** Indicates the orientation of this object is vertical; for example this state may appear on
+ * such objects as scrollbars, text objects (with vertical text flow), separators, etc.
+ */
STATE_VERTICAL,
- /* Indicates this object is visible */
+ /** Indicates this object is visible, e.g. has been explicitly marked for exposure to the user.
+ * @note: STATE_VISIBLE is no guarantee that the object is actually unobscured on the screen, only
+ * that it is 'potentially' visible, barring obstruction, being scrolled or clipped out of the
+ * field of view, or having an ancestor container that has not yet made visible.
+ * A widget is potentially onscreen if it has both STATE_VISIBLE and STATE_SHOWING.
+ * The absence of STATE_VISIBLE and STATE_SHOWING is semantically equivalent to saying
+ * that an object is 'hidden'.
+ */
STATE_VISIBLE,
- /*
+ /**
* Indicates that "active-descendant-changed" event is sent when children
* become 'active' (i.e. are selected or navigated to onscreen). Used to
* prevent need to enumerate all children in very large containers, like
- * tables.
+ * tables. The presence of STATE_MANAGES_DESCENDANTS is an indication to the client.
+ * that the children should not, and need not, be enumerated by the client.
+ * Objects implementing this state are expected to provide relevant state
+ * notifications to listening clients, for instance notifications of visibility
+ * changes and activation of their contained child objects, without the client
+ * having previously requested references to those children.
*/
STATE_MANAGES_DESCENDANTS,
- /*
- * Indicates that a check box is in a state other than checked or not checked.
+ /**
+ * Indicates that a check box or other boolean indicator is in a state other than
+ * checked or not checked. This usually means that the boolean value reflected or
+ * controlled by the object does not apply consistently to the entire current context.
+ * For example, a checkbox for the "Bold" attribute of text may have STATE_INDETERMINATE
+ * if the currently selected text contains a mixture of weight attributes.
+ * In many cases interacting with a STATE_INDETERMINATE object will cause
+ * the context's corresponding boolean attribute to be homogenized, whereupon the object
+ * will lose STATE_INDETERMINATE and a corresponding state-changed event will be fired.
*/
STATE_INDETERMINATE,
+ /**
+ * Indicates that user interaction with this object is 'required' from the user,
+ * for instance before completing the processing of a form.
+ */
+ STATE_REQUIRED,
+ /**
+ * Indicates that an object's onscreen content is truncated, e.g. a text value in a spreadsheet cell.
+ * @since AT-SPI 1.7.0.
+ */
+ STATE_TRUNCATED,
+ /**
+ * Indicates this object's visual representation is dynamic, not static.
+ * This state may be applied to an object during an animated 'effect' and
+ * be removed from the object once its visual representation becomes static.
+ * @note some applications, notably content viewers, may not be able to detect
+ * all kinds of animated content. Therefore the absence of this state should not
+ * be taken as definitive evidence that the object's visual representation is
+ * static; this state is advisory.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_ANIMATED,
+ /**
+ * This object has indicated an error condition due to failure of input
+ * validation. For instance, a form control may acquire this state in response
+ * to invalid or malformed user input.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_INVALID_ENTRY,
+ /**
+ * This state indicates that the object in question implements some form of ¨typeahead¨ or
+ * pre-selection behavior whereby entering the first character of one or more sub-elements
+ * causes those elements to scroll into view or become selected. Subsequent character input
+ * may narrow the selection further as long as one or more sub-elements match the string.
+ * This state is normally only useful and encountered on objects that implement Selection.
+ * In some cases the typeahead behavior may result in full or partial ¨completion¨ of
+ * the data in the input field, in which case these input events may trigger text-changed
+ * events from the source.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_SUPPORTS_AUTOCOMPLETION,
+ /**
+ * This state indicates that the object in question supports text selection.
+ * It should only be exposed on objects which implement the Text interface,
+ * in order to distinguish this state from STATE_SELECTABLE, which infers that
+ * the object in question is a selectable child of an object which implements
+ * Selection. While similar, text selection and subelement selection are
+ * distinct operations.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_SELECTABLE_TEXT,
+ /**
+ * This state indicates that the object in question is the 'default' interaction object
+ * in a dialog, i.e. the one that gets activated if the user presses "Enter" when the
+ * dialog is initially posted.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ STATE_IS_DEFAULT,
+ /** This value of the enumeration should not be used as a parameter, it indicates the number of
+ * items in the StateType enumeration.
+ */
STATE_LAST_DEFINED
};
typedef sequence <StateType> StateSeq;
+ /**
+ * The StateSet interface encapsulates a collection of state information.
+ * It allows comparison of state information between object instances, and comparisons
+ * of an object's state with some hypothetical collection of states.
+ */
interface StateSet : Bonobo::Unknown {
+
+ /** Query a StateSet for a specific StateType.
+ * @param state the StateType being queried for.
+ * @returns \c TRUE if the StateSet contains StateType \a state.
+ */
boolean contains (in StateType state);
+
+ /** Add a StateType to an existing StateSet, if not already present. */
void add (in StateType state);
+
+ /** Remove a StateType to an existing StateSet, if it is present. */
void remove (in StateType state);
+
+ /** Compare two statesets for equivalence.
+ * @param stateSet the StateSet to be compared with this one.
+ * @returns \c TRUE if the two StateSet objects are composed of the same StateTypes.
+ */
boolean equals (in StateSet stateSet);
- /* returns a 'difference set' */
+
+ /** Compare two StateSet instances and obtain their differences.
+ * @returns a 'difference set', i.e. a StateSet consisting of those states
+ * not shared by the two sets being compared. */
StateSet compare (in StateSet compareState);
+
+ /** @returns \c TRUE if the StateSet contains no states. */
boolean isEmpty ();
+ /** \cond */
/* Private */
StateSeq getStates ();
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};
typedef sequence<string> StringSeq;
+ /**
+ * An interface whereby an object allows its backing content
+ * to be streamed to clients. Negotiation of content type
+ * is allowed. Clients may examine the backing data and
+ * transform, convert, or parse the content in order to
+ * present it in an alternate form to end-users.
+ *
+ * @note The StreamableContent interface is particularly useful for saving,
+ * printing, or post-processing entire documents, or for persisting
+ * alternate views of a document.
+ * If document content itself is being serialized, stored, or converted,
+ * then use of the StreamableContent interface can help address performance
+ * issues. Unlike most AT-SPI/Accessibility interfaces, this interface
+ * is not strongly tied to the current user-agent view of the
+ * a particular document, but may in some cases give access to the
+ * underlying model data.
+ */
interface StreamableContent {
+
+ /**
+ * Specifies the meaning of a seek 'offset'. Not all SeekTypes are
+ * supported by all StreamableContent data sources, for instance
+ * some streams may not support seeking from the beginning or other
+ * types of 'backwards' seeks.
+ */
+ enum SeekType {
+ SEEK_SET, /**< Seek from the start of the stream or data source.*/
+ SEEK_CURRENT, /**< Seek relative to the current position. */
+ SEEK_END /**< Seek from the end of the file, stream, or data source. */
+ };
+
+ /**
+ * Indicates that a transmission error has occurred while
+ * reading or seeking the stream or data source.
+ */
+ exception IOError {
+ string reason;
+ };
+ /**
+ * Indicates that the requested operation is not supported by the stream instance.
+ */
+ exception NotSupported {
+ string reason;
+ };
+
+ /**
+ * The operation is supported, but the current requestor does not have
+ * permission to t the request, for instance does not have permission to read
+ * the stream.
+ */
+ exception NoPermission {
+ string reason;
+ };
+
+ /**
+ * getContentTypes:
+ * @returns the list of available mimetypes for this object's content.
+ */
StringSeq getContentTypes ();
+ /**
+ * Retrieve this object's content, in a format appropriate to a
+ * requested mimetype.
+ *
+ * @note the data is returned as an object of type ::Bonobo::Stream.
+ * The primary methods which are supported on Bonobo::Streams for the
+ * purposes of the ::StreamableContent API are \c seek and \c read.
+ * \c seek may not be supported for all mimetypes or
+ * all implementors.
+ *
+ \verbatim
+ long Bonobo::Stream:seek (in long offset, in SeekType whence)
+ raises (NoPermission, IOError)
+ void Bonobo::Stream:read (in long count, out iobuf buffer)
+ raises (NoPermission, IOError)
+ \endverbatim
+ *
+ * @see ::Bonobo::Stream
+ *
+ * @returns a ::Bonobo::Stream whose mimetype matches \a contentType,
+ * if available, or \c NIL.
+ */
Bonobo::Stream getContent (in string contentType);
- /* methods used from Bonobo::Stream : seek, read. Others unsupported. */
/**
+ * \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};
typedef sequence<long> LongSeq;
+ /**
+ * An interface used by containers whose contained data is arranged in
+ * a "tabular" (i.e.\ row-column) fashion. Tables may resemble a two-dimensional
+ * grid, as in a spreadsheet, or may feature objects which span multiple rows and/or
+ * columns, but whose bounds are aligned on a row/column matrix. Thus, the Table
+ * interface may be used to represent "spreadsheets" as well as "frames".
+ *
+ * Objects within tables are children of the Table instance, and they may be referenced
+ * either via a child index or via a row/column pair.
+ * Their role may be ROLE_TABLE_CELL, but table 'cells' may have other roles as well.
+ * These 'cells' may implement other interfaces, such as Text, Action, Image,
+ * and Component, and should do so as appropriate to their onscreen representation
+ * and/or behavior.
+ */
interface Table : Bonobo::Unknown {
+ /**
+ * The total number of rows in this table (including empty rows),
+ * exclusive of any rows which are programmatically hidden.
+ * Rows which are merely scrolled out of view are included.
+ */
readonly attribute long nRows;
+ /**
+ * The total number of columns in this table (including empty columns),
+ * exclusive of columns which are programmatically hidden.
+ * Columns which are scrolled out of view or clipped by the current
+ * viewport are included.
+ */
readonly attribute long nColumns;
+ /**
+ * An Accessible which represents of a caption for a Table.
+ **/
readonly attribute Accessible caption;
+ /**
+ * An accessible object which summarizes the contents of a Table.
+ * This object is frequently itself a Table instance, albeit a simplified one.
+ */
readonly attribute Accessible summary;
+ /**
+ * The number of rows currently selected.
+ * A selected row is one in which all included cells are selected.
+ * @note Not all tables support row selection.
+ */
readonly attribute long nSelectedRows;
+ /**
+ * The number of columns currently selected.
+ * A selected column is one in which all included cells are selected.
+ * @note Not all tables support column selection.
+ */
readonly attribute long nSelectedColumns;
-
+ /**
+ * Get the table cell at the specified row and column indices.
+ * @note To get the accessible object at a particular (x, y) screen coordinate,
+ * use Accessible::getAccessibleAtPoint ().
+ *
+ * @param row: the specified table row, zero-indexed.
+ * @param column: the specified table column, zero-indexed.
+ *
+ * @returns an Accessible object representing the specified table cell.
+ **/
Accessible getAccessibleAt (in long row, in long column);
+ /**
+ * Get the 1-D child index corresponding to the specified 2-D row and column indices.
+ * @note To get the accessible object at a particular (x, y) screen coordinate,
+ * use Accessible::getAccessibleAtPoint.
+ *
+ * @param row: the specified table row, zero-indexed.
+ * @param column: the specified table column, zero-indexed.
+ *
+ * @see getRowAtIndex, getColumnAtIndex
+ *
+ * @returns a long integer which serves as the index of a specified cell in the
+ * table, in a form usable by Accessible::getChildAtIndex.
+ **/
long getIndexAt (in long row, in long column);
+ /**
+ * Get the table row index occupied by the child at a particular 1-D child index.
+ *
+ * @param index: the specified child index, zero-indexed.
+ *
+ * @see getIndexAt(), getColumnAtIndex()
+ *
+ * @returns a long integer indicating the first row spanned by the child of a
+ * table, at the specified 1-D (zero-offset) \c index.
+ **/
long getRowAtIndex (in long index);
+ /**
+ * Get the table column index occupied by the child at a particular 1-D child index.
+ *
+ * @param index: the specified child index, zero-indexed.
+ *
+ * @see getIndexAt(), getRowAtIndex()
+ *
+ * @returns a long integer indicating the first column spanned by the child of a
+ * table, at the specified 1-D (zero-offset) \c index.
+ **/
long getColumnAtIndex (in long index);
+ /**
+ * Get a text description of a particular table row. This differs from
+ * AccessibleTable_getRowHeader, which returns an Accessible.
+ * @param row: the specified table row, zero-indexed.
+ *
+ * @returns a UTF-8 string describing the specified table row, if available.
+ **/
string getRowDescription (in long row);
+ /**
+ * Get a text description of a particular table column. This differs from
+ * AccessibleTable_getColumnHeader, which returns an Accessible.
+ * @param column: the specified table column, zero-indexed.
+ *
+ * @returns a UTF-8 string describing the specified table column, if available.
+ **/
string getColumnDescription (in long column);
+ /**
+ * Get the number of rows spanned by the table cell at the specific row and column.
+ * (some tables can have cells which span multiple rows and/or columns).
+ *
+ * @param row: the specified table row, zero-indexed.
+ * @param column: the specified table column, zero-indexed.
+ *
+ * @returns a long integer indicating the number of rows spanned by the specified cell.
+ **/
long getRowExtentAt (in long row, in long column);
+ /**
+ * Get the number of columns spanned by the table cell at the specific row and column.
+ * (some tables can have cells which span multiple rows and/or columns).
+ *
+ * @param row: the specified table row, zero-indexed.
+ * @param column: the specified table column, zero-indexed.
+ *
+ * @returns a long integer indicating the number of columns spanned by the
+ * specified cell.
+ **/
long getColumnExtentAt (in long row, in long column);
+ /**
+ * Get the header associated with a table row, if available. This differs from
+ * getRowDescription, which returns a string.
+ *
+ * @param row: the specified table row, zero-indexed.
+ *
+ * @returns an Accessible representatin of the specified table row, if available.
+ **/
Accessible getRowHeader (in long row);
+ /**
+ * Get the header associated with a table column, if available, as an
+ * instance of Accessible. This differs from
+ * getColumnDescription, which returns a string.
+ *
+ * @param column: the specified table column, zero-indexed.
+ *
+ * @returns an Accessible representatin of the specified table column, if available.
+ **/
Accessible getColumnHeader (in long column);
+ /**
+ * Obtain the indices of all rows which are currently selected.
+ * @note Not all tables support row selection.
+ *
+ * @returns a sequence of integers comprising the indices of rows currently selected.
+ **/
LongSeq getSelectedRows ();
+ /**
+ * Obtain the indices of all columns which are currently selected.
+ * @note Not all tables support column selection.
+ *
+ * @returns a sequence of integers comprising the indices of columns currently selected.
+ **/
LongSeq getSelectedColumns ();
+ /**
+ * Determine whether a table row is selected.
+ * @note Not all tables support row selection.
+ *
+ * @param row: the row being queried.
+ *
+ * @returns \c True if the specified row is currently selected, \c False if not.
+ **/
boolean isRowSelected (in long row);
+ /**
+ * Determine whether a table column is selected.
+ * @note Not all tables support column selection.
+ *
+ * @param column: the column being queried.
+ *
+ * @returns \c True if the specified column is currently selected, \c False if not.
+ **/
boolean isColumnSelected (in long column);
+ /**
+ * Determine whether the cell at a specific row and column is selected.
+ * @param row a row occupied by the cell whose state is being queried.
+ * @param column a column occupied by the cell whose state is being queried.
+ *
+ * @returns \c True if the specified cell is currently selected,
+ * \c False if not.
+ **/
boolean isSelected (in long row, in long column);
+ /**
+ * Select the specified row, adding it to the current row selection,
+ * if the table's selection model permits it.
+ *
+ * @param row
+ * @note Possible reasons for addRowSelection to return \c False
+ * include:
+ * \li The table does not support Selection
+ * \li The table row includes cells which do not have STATE_SELECTABLE
+ * \li The table does not support selection by row
+ * \li The table does not support selection of multiple rows, and
+ * one row is already selected.
+ * \li The table does not support non-contiguous selections (i.e.
+ * does not include STATE_MULTISELECTABLE), and the specified row
+ * would result in selection of non-contiguous rows.
+ * \li The table does not support user-instigated selection.
+ *
+ * @returns \c True if the specified row was successfully selected,
+ * \c False if not.
+ **/
boolean addRowSelection (in long row);
+ /**
+ * Select the specified column, adding it to the current column selection,
+ * if the table's selection model permits it.
+ *
+ * @param column
+ * @note Possible reasons for addColumnSelection to return \c False
+ * include:
+ * \li The table does not support Selection
+ * \li The table column includes cells which do not have STATE_SELECTABLE
+ * \li The table does not support selection by column
+ * \li The table does not support selection of multiple columns, and
+ * one column is already selected.
+ * \li The table does not support non-contiguous selections (i.e.
+ * does not include STATE_MULTISELECTABLE), and the specified column
+ * would result in selection of non-contiguous columns.
+ * \li The table does not support user-instigated selection.
+ *
+ * @returns \c True if the specified column was successfully selected,
+ * \c False if not.
+ **/
boolean addColumnSelection (in long column);
+ /**
+ * Remove the specified row from current row selection,
+ * if the table's selection model permits it.
+ *
+ * @param row
+ * @note Possible reasons for removeRowSelection to return \c False
+ * include:
+ * \li The table does not support user-instigated Selection
+ * \li The table has no selected rows or does not support deselection by row
+ *
+ * @returns \c True if the specified row was successfully de-selected,
+ * \c False if not.
+ **/
boolean removeRowSelection (in long row);
+ /**
+ * Remove the specified column from current column selection,
+ * if the table's selection model permits it.
+ *
+ * @param column
+ * @note Possible reasons for removeColumnSelection to return \c False
+ * include:
+ * \li The table does not support user-instigated modification of
+ * selection state
+ * \li The table has no selected columns or does not support
+ * deselection by column.
+ *
+ * @returns \c True if the specified column was successfully de-selected,
+ * \c False if not.
+ **/
boolean removeColumnSelection (in long column);
- /**
+
+ /** \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented6 ();
void unImplemented7 ();
void unImplemented8 ();
+ /** \endcond */
};
};
module Accessibility {
+ /**
+ * Specifies the boundary conditions determining a run of text as returned from
+ * getTextAtOffset, getTextAfterOffset, and getTextBeforeOffset.
+ */
enum TEXT_BOUNDARY_TYPE {
- TEXT_BOUNDARY_CHAR,
- TEXT_BOUNDARY_WORD_START,
- TEXT_BOUNDARY_WORD_END,
- TEXT_BOUNDARY_SENTENCE_START,
- TEXT_BOUNDARY_SENTENCE_END,
- TEXT_BOUNDARY_LINE_START,
- TEXT_BOUNDARY_LINE_END
+ TEXT_BOUNDARY_CHAR,/**< Text is bounded by this character only.
+ * Start and end offsets differ by one, by definition, for this value.
+ */
+ TEXT_BOUNDARY_WORD_START,/**< Boundary condition is start of a word; i.e. range is from start of
+ * one word to the start of another word.
+ */
+ TEXT_BOUNDARY_WORD_END,/**< Boundary condition is the end of a word; i.e. range is from
+ * the end of one word to the end of another.
+ * @note some locales may not distinguish between words and
+ * characters or glyphs, in particular those locales which use
+ * wholly or partially ideographic character sets. In these cases,
+ * characters may be returned in lieu of multi-character substrings.
+ */
+ TEXT_BOUNDARY_SENTENCE_START,/**< Boundary condition is start of a sentence, as determined
+ * by the application.
+ * @note Some locales or character sets may not include explicit sentence
+ * delimiters, so this boundary type can not always be honored.
+ * Some locales will return lines of text instead of grammatical sentences.
+ */
+ TEXT_BOUNDARY_SENTENCE_END,/**< Boundary condition is end of a sentence, as determined by the application,
+ * including the sentence-delimiting character, for instance '.'
+ * @note Some locales or character sets may not include explicit sentence
+ * delimiters, so this boundary type can not always be honored.
+ * Some locales will return lines of text instead of grammatical sentences.
+ */
+ TEXT_BOUNDARY_LINE_START,/**< Boundary condition is the start of a line; i.e. range is
+ * from start of one line to the start of another. This generally
+ * means that an end-of-line character will appear at the end of the range.
+ */
+ TEXT_BOUNDARY_LINE_END /**< Boundary condition is the end of a line; i.e. range is
+ * from start of one line to the start of another. This generally
+ * means that an end-of-line character will be the first character of the range.
+ */
};
/**
**/
enum TEXT_CLIP_TYPE {
TEXT_CLIP_NONE,
- TEXT_CLIP_MIN,
- TEXT_CLIP_MAX,
- TEXT_CLIP_BOTH
+ TEXT_CLIP_MIN,/**< characters/glyphs clipped by the minimum coordinate are omitted */
+ TEXT_CLIP_MAX,/**< characters/glyphs which intersect the maximum coordinate are omitted */
+ TEXT_CLIP_BOTH /**< only glyphs falling entirely within the region bounded by min and max are retained. */
};
+ /**
+ * The text interface should be implemented by objects which place textual information onscreen as character
+ * strings or glyphs. The text interface allows access to textual content, including display attributes and
+ * semantic hints associated with runs of text, and access to bounding box information for glyphs and substrings.
+ * It also allows portions of textual content to be selected, if the object's StateSet includes
+ * STATE_SELECTABLE_TEXT.
+ *
+ * In some cases a Text object may have, as its content, an empty string. In particular this can
+ * occur in the case of Hypertext objects which do not display explicitly textual information onscreen,
+ * as Hypertext is derived from the Text interface. @see Hypertext.
+ *
+ * Typographic and semantic attributes of onscreen textual content, for instance typeface, weight,
+ * language, and such qualities as 'emphasis' or 'blockquote', are represented as text attributes.
+ * Contiguous sequences of characters over which these attributes are unchanged are referred to as
+ * "attribute runs", and are available via Text::getAttributeRun. Where possible, implementing clients
+ * will report textual attributes which are the same over the entire text object, for instance those
+ * inherited from a default or document-scope style, via getDefaultAttributes instead of reporting them
+ * explicitly for each character. Therefore, for any span of text, the attributes in effect are the union
+ * of the set returned by Text::getDefaultAttributes, and the set returned at a particular character
+ * offset via Text::getAttributeRun.
+ *
+ * @note Events that may be emitted by instances of Text include:
+ * \li \c "object:text-attributes-changed" The attributes of a range of text, or the range over
+ * which attributes apply, has changed.
+ * \li \c "object:text-changed" The text content of this object has changed.
+ * \li \c "object:text-bounds-changed" The character bounds of a text object have changed,
+ * for instance in response to a reformatting or reflow operation.
+ * \li \c "object:text-caret-moved" The character offset of the text caret (visible or notional) within
+ * this object has changed. Events of this type may also be generated when an onscreen
+ * text caret appears or disappears.
+ * \li \c "object:text-selection-changed" The range or number of text selections within this text object
+ * has changed.
+ *
+ * @note In some cases, objects which are not onscreen may implement Text, but if such objects
+ * implement Component, their potential visibility should be examined (via comparison with STATE_VISIBLE
+ * and STATE_SHOWING) before exposing them to the user. Objects which implement Text but not Component
+ * may be encountered in special-purpose interfaces or as special ¨accessibility¨ extensions to visual
+ * interfaces to allow non-graphical access to application features. These instances should be considered
+ * the exception, rather than the rule.
+ */
interface Text : Bonobo::Unknown {
+ /** A structure used to define a continguous range of text, including its
+ * (unattributed) textual content.
+ **/
struct Range {
long startOffset;
long endOffset;
};
typedef sequence<Range> RangeList;
-
+
+ /** The total current number of characters in the Text object,
+ * including whitespace and non-spacing characters.
+ **/
readonly attribute long characterCount;
+
+ /** The current offset of the text caret in the Text object.
+ * This caret may be virtual, e.g. non-visual and notional-only, but if an
+ * onscreen representation of the caret position is visible, it will correspond to this offset.
+ * The caret offset is given as a character offset, as opposed to a byte offset into
+ * a text buffer or a column offset.
+ **/
readonly attribute long caretOffset;
+
+ /**
+ * Obtain all or part of the onscreen textual content of a Text object. If endOffset is specified as
+ * "-1", then this method will return the entire onscreen textual contents of the Text object.
+ * @note 'onscreen' in this context means "potentially onscreen", this method does not perform any sort
+ * of coordinate visibility clipping or window-stack-ordering clipping. The text thus reported
+ * corresponds to the text which would be presented onscreen if the object implementing the Text interface
+ * were entirely unobscured.
+ * @returns the textual content of the current Text object beginning startOffset (inclusive)
+ * up to but not including the character at endOffset.
+ **/
string getText (in long startOffset, in long endOffset);
+
+ /** Programmatically move the text caret (visible or virtual, as above) to a given position.
+ * @param offset a long int indicating the desired character offset. Not all implementations of
+ * Text will honor setCaretOffset requests, so the return value below should be checked by the client.
+ * @returns \c TRUE if the request was carried out, or \c FALSE if the caret could not be moved to
+ * the requested position.
+ **/
boolean setCaretOffset (in long offset);
+
+ /**
+ * Obtain a subset of the text content of an object which entirely precedes \c offset,
+ * delimited by character, word, line, or sentence boundaries as specified by \c type. The
+ * starting and ending offsets of the resulting substring are returned in \c startOffset
+ * and \c endOffset. By definition, if such a substring exists, \c endOffset is less than or
+ * equal to \c offset.
+ * @param offset the offset from which the substring search begins.
+ * @param type the text-boundary delimiter which determines whether the returned text constitures
+ * a character, word, line, or sentence (and possibly attendant whitespace),
+ * and whether the start or ending of such a substring forms the boundary condition.
+ * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
+ * @param endOffset back-filled with the offset of the character immediately following the resulting
+ * substring, if one exists.
+ * @see TEXT_BOUNDARY_TYPE
+ * @returns a string which is a substring of the text content of the object, delimited by the
+ * specified boundary condition.
+ */
string getTextBeforeOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
out long startOffset, out long endOffset);
+ /**
+ * Obtain a subset of the text content of an object which includes the specified \c offset,
+ * delimited by character, word, line, or sentence boundaries as specified by \c type. The
+ * starting and ending offsets of the resulting substring are returned in \c startOffset
+ * and \c endOffset.
+ * @param offset the offset from which the substring search begins, and which must
+ * lie within the returned substring.
+ * @param type the text-boundary delimiter which determines whether the returned text constitures
+ * a character, word, line, or sentence (and possibly attendant whitespace),
+ * and whether the start or ending of such a substring forms the boundary condition.
+ * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
+ * @param endOffset back-filled with the offset of the character immediately following the resulting
+ * substring, if one exists.
+ * @see TEXT_BOUNDARY_TYPE
+ * @returns a string which is a substring of the text content of the object, delimited by the
+ * specified boundary condition.
+ */
string getTextAtOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
out long startOffset, out long endOffset);
+ /**
+ * Obtain a subset of the text content of an object which entirely follows \c offset,
+ * delimited by character, word, line, or sentence boundaries as specified by \c type. The
+ * starting and ending offsets of the resulting substring are returned in \c startOffset
+ * and \c endOffset. By definition, if such a substring exists, \c startOffset must be greater than
+ * \c offset.
+ * @param offset the offset from which the substring search begins, and which must
+ * lie before the returned substring.
+ * @param type the text-boundary delimiter which determines whether the returned text constitures
+ * a character, word, line, or sentence (and possibly attendant whitespace),
+ * and whether the start or ending of such a substring forms the boundary condition.
+ * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
+ * @param endOffset back-filled with the offset of the character immediately following the resulting
+ * substring, if one exists.
+ * @see TEXT_BOUNDARY_TYPE
+ * @returns a string which is a substring of the text content of the object, delimited by the
+ * specified boundary condition.
+ */
string getTextAfterOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
out long startOffset, out long endOffset);
+ /**
+ * @returns an unsigned long integer whose value corresponds to the UCS-4 representation of the
+ * character at the specified text offset, or 0 if offset is out of range.
+ */
unsigned long getCharacterAtOffset (in long offset); /* long instead of wchar,
* to allow unicode chars > 16 bits
*/
+ /**
+ * Get the string value of a named attribute at a given offset, if defined.
+ * @param offset the offset of the character for which the attribute run is to be obtained.
+ * @param attributeName the name of the attribute for which the value is to be returned, if defined.
+ * @param startOffset back-filled with the offset of the first character in the attribute run
+ * containing the character at \c offset.
+ * @param endOffset back-filled with the offset of the first character past the end of the
+ * attribute run containing the character at \c offset.
+ * @param defined back-filled with \c True if the attributeName has a defined value at \c offset,
+ * \c False otherwise.
+ * @returns the value of attribute (name-value pair) corresponding to "name", if defined.
+ **/
+ string getAttributeValue (in long offset, in string attributeName,
+ out long startOffset,
+ out long endOffset,
+ out boolean defined);
+ /**
+ * getAttributes is deprecated in favor of getAttributeRun.
+ * @returns the attributes at offset, as a semicolon-delimited set of colon-delimited name-value pairs.
+ * @see getAttributeRun
+ **/
string getAttributes (in long offset,
out long startOffset, out long endOffset);
+ /**
+ * Deprecated in favor of getDefaultAttributeSet.
+ * @returns the attributes which apply to the entire text content, but which were not explicitly
+ * specified by the content creator.
+ * @see getDefaultAttributeSet
+ **/
string getDefaultAttributes ();
+ /**
+ * Obtain a the bounding box, as x, y, width, and height, of the character or glyph at a particular
+ * character offset in this object's text content. The coordinate system in which the results are
+ * reported is specified by coordType. If an onscreen glyph corresponds to multiple character offsets,
+ * for instance if the glyph is a ligature, the bounding box reported will include the entire glyph and
+ * therefore may apply to more than one character offset.
+ * @param offset the character offset of the character or glyph being queried.
+ * @param x the minimum horizontal coordinate of the bounding box of the glyph representing
+ * the character at \c offset.
+ * @param y the minimum vertical coordinate of the bounding box of the glyph representing
+ * the character at \c offset.
+ * @param width the horizontal extent of the bounding box of the glyph representing
+ * the character at \c offset.
+ * @param height the vertical extent of the bounding box of the glyph representing
+ * the character at \c offset.
+ * @param coordType If 0, the results will be reported in screen coordinates, i.e. in pixels
+ * relative to the upper-left corner of the screen, with the x axis pointing right
+ * and the y axis pointing down.
+ * If 1, the results will be reported relative to the containing toplevel window,
+ * with the x axis pointing right and the y axis pointing down.
+ **/
void getCharacterExtents (in long offset, out long x, out long y, out long width, out long height, in short coordType);
+ /**
+ * Get the offset of the character at a given onscreen coordinate. The coordinate system used to interpret
+ * x and y is determined by parameter coordType.
+ * @param x
+ * @param y
+ * @param coordType if 0, the input coordinates are interpreted relative to the entire screen, if 1,
+ * they are relative to the toplevel window containing this Text object.
+ * @returns the text offset (as an offset into the character array) of the glyph whose onscreen bounds contain the point x,y, or -1 if the point is outside the bounds of any glyph.
+ **/
long getOffsetAtPoint (in long x, in long y, in short coordType);
+ /**
+ * Obtain the number of separate, contiguous selections in the current Text object.
+ * Text objects which do not implement selection of discontiguous text regions will always
+ * return '0' or '1'. Note that "contiguous" is defined by continuity of the offsets, i.e.
+ * a text 'selection' is defined by a start/end offset pair. In the case of bidirectional text,
+ * this means that a continguous selection may appear visually discontiguous, and vice-versa.
+ *
+ * @returns the number of contiguous selections in the current Text object.
+ **/
long getNSelections ();
+ /**
+ * The result of calling getSelection with an out-of-range selectionNum (i.e. for a selection
+ * which does not exist) is not strictly defined, but should set endOffset equal to startOffset.
+ **/
void getSelection (in long selectionNum, out long startOffset, out long endOffset);
+ /**
+ * The result of calling addSelection on objects which already have one selection present, and which
+ * do not include STATE_MULTISELECTABLE, is undefined, other than the return value.
+ * @returns \c True of the selection was successfully added, \c False otherwise. Selection may
+ * fail if the object does not support selection of text (see STATE_SELECTABLE_TEXT), if the
+ * object does not support multiple selections and a selection is already defined, or for other reasons
+ * (for instance if the user does not have permission to copy the text into the relevant selection
+ * buffer).
+ **/
boolean addSelection (in long startOffset, in long endOffset);
+ /**
+ * Deselect the text contained in the specified selectionNum, if such a selection
+ * exists, otherwise do nothing. Removal of a non-existant selectionNum has no effect.
+ * @returns \c True if the selection was successfully removed, \c False otherwise.
+ **/
boolean removeSelection (in long selectionNum);
+ /**
+ * Modify an existing selection's start or ending offset.
+ *
+ * Calling setSelection for a selectionNum that is not already defined has no effect.
+ * The result of calling setSelection with a selectionNum greater than 0 for objects that
+ * do not include STATE_MULTISELECTABLE is undefined.
+ * @param selectionNum indicates which of a set of non-contiguous selections to modify.
+ * @param startOffset the new starting offset for the selection
+ * @param endOffset the new ending offset for the selection
+ * @returns \c True if the selection corresponding to selectionNum is successfully modified,
+ * \c False otherwise.
+ **/
boolean setSelection (in long selectionNum, in long startOffset, in long endOffset);
+ /**
+ * Obtain the bounding box which entirely contains a given text range.
+ * Negative values may be returned for the bounding box parameters in the event
+ * that all or part of the text range is offscreen or not mapped to the screen.
+ * @param startOffset the offset of the first character in the specified range.
+ * @param endOffset the offset of the character immediately after the last
+ * character in the specified range.
+ * @param x an integer parameter which is back-filled with the minimum
+ * horizontal coordinate of the resulting bounding box.
+ * @param y an integer parameter which is back-filled with the minimum
+ * vertical coordinate of the resulting bounding box.
+ * @param width an integer parameter which is back-filled with the
+ * horizontal extent of the bounding box.
+ * @param height an integer parameter which is back-filled with the
+ * vertical extent of the bounding box.
+ * @param coordType If 0, the above coordinates are reported in pixels relative to
+ * corner of the screen; if 1, the coordinates are reported relative to the
+ * corner of the containing toplevel window.
+ **/
void getRangeExtents (in long startOffset, in long endOffset,
out long x, out long y,
out long width, out long height, in short coordType);
+
+ /**
+ * Return the text content within a bounding box,
+ * as a list of Range structures.
+ * Depending on the TEXT_CLIP_TYPE parameters, glyphs which are clipped by the
+ * bounding box (i.e. which lie partially inside and partially outside it)
+ * may or may not be included in the ranges returned.
+ * @note This method may be of particular interest to screen review algorithms.
+ * @see TEXT_CLIP_TYPE.
+ * @param x the minimum x ( i.e. leftmost) coordinate of the bounding box.
+ * @param y the minimum y coordinate of the bounding box.
+ * @param width the horizontal size of the bounding box. The rightmost bound of the bounding box
+ * is (x + width);
+ * @param height the vertical size of the bounding box. The maximum y value of the bounding box
+ * is (y + height);
+ * @param coordType If 0, the above coordinates are interpreted as pixels relative to
+ * corner of the screen; if 1, the coordinates are interpreted as pixels relative to the
+ * corner of the containing toplevel window.
+ * @param xClipType determines whether text which intersects the bounding box in the x direction
+ * is included.
+ * @param yClipType determines whether text which intersects the bounding box in the y direction
+ * is included.
+ **/
RangeList getBoundedRanges (in long x, in long y,
in long width, in long height,
in short coordType,
in TEXT_CLIP_TYPE xClipType,
in TEXT_CLIP_TYPE yClipType);
- /**
+ /** \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented ();
void unImplemented2 ();
void unImplemented3 ();
+ void unImplemented4 ();
+ /** \endcond **/
};
};
module Accessibility {
+ /**
+ * An interface supporting controls which allow a
+ * one-dimensional, scalar quantity to be modified or which
+ * reflect a scalar quantity. (If STATE_EDITABLE is not present,
+ * the valuator is treated as "read only".
+ *
+ * @note Events generated by Image instances include:
+ * \li \c "object:value-changed"
+ */
interface Value : Bonobo::Unknown {
+ /**
+ * The minimum value allowed by this valuator.
+ */
readonly attribute double minimumValue;
+ /**
+ * The maximum value allowed by this valuator.
+ */
readonly attribute double maximumValue;
+ /**
+ * The smallest incremental change which this valuator allows.
+ * If 0, the incremental changes to the valuator are
+ * limited only by the precision of a double precision value
+ * on the platform.
+ */
readonly attribute double minimumIncrement;
+ /**
+ * The current value of the valuator.
+ */
attribute double currentValue;
- /**
+ /** \cond
* unImplemented:
*
* placeholders for future expansion.
void unImplemented2 ();
void unImplemented3 ();
void unImplemented4 ();
+ /** \endcond */
};
};
#include <bonobo/bonobo-exception.h>
#include <atk/atk.h>
#include <libspi/libspi.h>
+#include "spi-private.h"
/* Our parent Gtk object type */
#define PARENT_TYPE SPI_TYPE_BASE
static gboolean spi_init_role_lookup_table (Accessibility_Role *role_table);
-static Accessibility_Role spi_role_from_atk_role (AtkRole role);
+Accessibility_Role spi_accessible_role_from_atk_role (AtkRole role);
static gboolean
spi_init_role_lookup_table (Accessibility_Role *role_table)
role_table [ATK_ROLE_AUTOCOMPLETE] = Accessibility_ROLE_AUTOCOMPLETE;
role_table [ATK_ROLE_EDITBAR] = Accessibility_ROLE_EDITBAR;
role_table [ATK_ROLE_EMBEDDED] = Accessibility_ROLE_EMBEDDED;
+ role_table [ATK_ROLE_ENTRY] = Accessibility_ROLE_ENTRY;
+ role_table [ATK_ROLE_CHART] = Accessibility_ROLE_CHART;
+ role_table [ATK_ROLE_CAPTION] = Accessibility_ROLE_CAPTION;
+ role_table [ATK_ROLE_DOCUMENT_FRAME] = Accessibility_ROLE_DOCUMENT_FRAME;
+ role_table [ATK_ROLE_HEADING] = Accessibility_ROLE_HEADING;
+ role_table [ATK_ROLE_PAGE] = Accessibility_ROLE_PAGE;
+ role_table [ATK_ROLE_SECTION] = Accessibility_ROLE_SECTION;
return TRUE;
}
-static Accessibility_Role
-spi_role_from_atk_role (AtkRole role)
+Accessibility_Role
+spi_accessible_role_from_atk_role (AtkRole role)
{
static gboolean is_initialized = FALSE;
static Accessibility_Role spi_role_table [ATK_ROLE_LAST_DEFINED];
return CORBA_string_dup ("");
}
+static Accessibility_Accessible
+impl_accessibility_accessible_get_application (PortableServer_Servant servant,
+ CORBA_Environment *ev)
+{
+ return spi_accessible_new_return (atk_get_root (), FALSE, ev);
+}
+
+static Accessibility_AttributeSet*
+impl_accessibility_accessible_get_attributes (PortableServer_Servant servant,
+ CORBA_Environment *ev)
+{
+ Accessibility_AttributeSet *retval;
+ GSList *attributes;
+ gint n_attributes = 0;
+ gint i;
+
+ AtkObject *object = get_atkobject_from_servant (servant);
+
+ g_return_val_if_fail (object != NULL, NULL);
+ attributes = atk_object_get_attributes (object);
+
+ bonobo_return_val_if_fail (attributes != NULL, NULL, ev);
+ n_attributes = g_slist_length (attributes);
+
+ retval = CORBA_sequence_CORBA_string__alloc ();
+ retval->_length = retval->_maximum = n_attributes;
+ retval->_buffer = CORBA_sequence_CORBA_string_allocbuf (n_attributes);
+ CORBA_sequence_set_release (retval, CORBA_TRUE);
+
+ for (i = 0; i < n_attributes; ++i)
+ {
+ retval->_buffer[i] = CORBA_string_dup (g_slist_nth_data (attributes, i));
+ }
+
+ return retval;
+}
+
static void
spi_accessible_class_init (SpiAccessibleClass *klass)
{
epv->getRole = impl_accessibility_accessible_get_role;
epv->getRoleName = impl_accessibility_accessible_get_role_name;
epv->getLocalizedRoleName = impl_accessibility_accessible_get_local_role_name;
+ epv->getApplication = impl_accessibility_accessible_get_application;
+ epv->getAttributes = impl_accessibility_accessible_get_attributes;
}
static void
e.source = CORBA_OBJECT_NIL;
e.detail1 = 0;
e.detail2 = 0;
- spi_init_any_nil (&e.any_data);
+ spi_init_any_nil (&e.any_data,
+ spi_accessible_new_return (atk_get_root (), FALSE, NULL),
+ Accessibility_ROLE_UNKNOWN,
+ CORBA_string_dup (""));
notify_listeners (the_app->toolkit_listeners, source, &e);
bonobo_object_unref (BONOBO_OBJECT (source));
return atk_component_grab_focus (component);
}
+static double
+impl_accessibility_component_get_alpha (PortableServer_Servant servant,
+ CORBA_Environment *ev)
+{
+ AtkComponent *component = get_component_from_servant (servant);
+
+ g_return_val_if_fail (component != NULL, FALSE);
+
+ return atk_component_get_alpha (component);
+}
+
static void
spi_component_class_init (SpiComponentClass *klass)
{
epv->getLayer = impl_accessibility_component_get_layer;
epv->getMDIZOrder = impl_accessibility_component_get_mdi_z_order;
epv->grabFocus = impl_accessibility_component_grab_focus;
+ epv->getAlpha = impl_accessibility_component_get_alpha;
}
static void
* spi_action_interface_new(), because of the above convention,
* even though it means we may be violating the func prototype.
* See discussion in bugzilla bug #120659.
+ * !!!
+ * IMPORTANT! The 'AtkObject' typecast, instead of the cast macro,
+ * is used below, because 'object' may NOT really be an AtkObject;
+ * it will be cast back to a G_OBJECT inside spi_action_interface_new
+ * before use, so this is OK though very ropey coding style.
*/
bonobo_object_add_interface (bonobo_object (new_hyperlink),
- BONOBO_OBJECT (spi_action_interface_new (object)));
+ BONOBO_OBJECT (spi_action_interface_new ((AtkObject *) object)));
}
return new_hyperlink;
}
}
}
+static CORBA_string
+impl__get_imageLocale (PortableServer_Servant servant,
+ CORBA_Environment *ev)
+{
+ const char *rv;
+ AtkImage *image = get_image_from_servant (servant);
+
+ g_return_val_if_fail (image != NULL, CORBA_string_dup ("C"));
+
+ rv = atk_image_get_image_locale (image);
+
+ if (rv)
+ {
+ return CORBA_string_dup (rv);
+ }
+ else
+ {
+ return CORBA_string_dup ("C");
+ }
+}
+
static void
spi_image_class_init (SpiImageClass *klass)
{
epv->getImageSize = impl_getImageSize;
epv->getImageExtents = impl_getImageExtents;
epv->_get_imageDescription = impl__get_imageDescription;
+ epv->_get_imageLocale = impl__get_imageLocale;
}
static void
types[ATK_RELATION_EMBEDS] = Accessibility_RELATION_EMBEDS;
types[ATK_RELATION_EMBEDDED_BY] = Accessibility_RELATION_EMBEDDED_BY;
types[ATK_RELATION_POPUP_FOR] = Accessibility_RELATION_POPUP_FOR;
+ types[ATK_RELATION_PARENT_WINDOW_OF] = Accessibility_RELATION_PARENT_WINDOW_OF;
return TRUE;
}
#include <glib/glist.h>
#include <atk/atk.h>
#include <orbit/orbit.h>
+#include <Accessibility.h>
G_BEGIN_DECLS
typedef SpiReEntrantContinue (*SpiReEntrantFn) (GList * const *list,
gpointer user_data);
+Accessibility_Role spi_role_from_atk_role (AtkRole role);
void spi_re_entrant_list_delete_link (GList * const *element_ptr);
void spi_re_entrant_list_foreach (GList **list,
SpiReEntrantFn func,
gpointer user_data);
-void spi_init_any_nil (CORBA_any *any);
-void spi_init_any_string (CORBA_any *any, char **string);
-void spi_init_any_object (CORBA_any *any, CORBA_Object *o);
-void spi_init_any_rect (CORBA_any *any, AtkRectangle *rect);
+void spi_init_any_nil (CORBA_any *any_details,
+ Accessibility_Application app,
+ Accessibility_Role role,
+ CORBA_string name);
+void spi_init_any_string (CORBA_any *any,
+ Accessibility_Application app,
+ Accessibility_Role role,
+ CORBA_string name,
+ char **string);
+void spi_init_any_object (CORBA_any *any,
+ Accessibility_Application app,
+ Accessibility_Role role,
+ CORBA_string name,
+ CORBA_Object *o);
+void spi_init_any_rect (CORBA_any *any,
+ Accessibility_Application app,
+ Accessibility_Role role,
+ CORBA_string name,
+ AtkRectangle *rect);
G_END_DECLS
atk_state_types[Accessibility_STATE_MANAGES_DESCENDANTS] = ATK_STATE_MANAGES_DESCENDANTS;
accessible_state_types[ATK_STATE_INDETERMINATE] = Accessibility_STATE_INDETERMINATE;
atk_state_types[Accessibility_STATE_INDETERMINATE] = ATK_STATE_INDETERMINATE;
+ accessible_state_types[ATK_STATE_TRUNCATED] = Accessibility_STATE_TRUNCATED;
+ atk_state_types[Accessibility_STATE_TRUNCATED] = ATK_STATE_TRUNCATED;
+ accessible_state_types[ATK_STATE_REQUIRED] = Accessibility_STATE_REQUIRED;
+ atk_state_types[Accessibility_STATE_REQUIRED] = ATK_STATE_REQUIRED;
+ accessible_state_types[ATK_STATE_INVALID_ENTRY] = Accessibility_STATE_INVALID_ENTRY;
+ atk_state_types[Accessibility_STATE_INVALID_ENTRY] = ATK_STATE_INVALID_ENTRY;
+ accessible_state_types[ATK_STATE_SUPPORTS_AUTOCOMPLETION] = Accessibility_STATE_SUPPORTS_AUTOCOMPLETION;
+ atk_state_types[Accessibility_STATE_SUPPORTS_AUTOCOMPLETION] = ATK_STATE_SUPPORTS_AUTOCOMPLETION;
+ accessible_state_types[ATK_STATE_SELECTABLE_TEXT] = Accessibility_STATE_SELECTABLE_TEXT;
+ atk_state_types[Accessibility_STATE_SELECTABLE_TEXT] = ATK_STATE_SELECTABLE_TEXT;
return TRUE;
}
}
static CORBA_string
+impl_getAttributeValue (PortableServer_Servant servant,
+ const CORBA_long offset,
+ const CORBA_char *attributename,
+ CORBA_long * startOffset,
+ CORBA_long * endOffset,
+ CORBA_boolean * defined,
+ CORBA_Environment *ev)
+{
+ AtkAttributeSet *set;
+ gint intstart_offset, intend_offset;
+ GSList *cur_attr;
+ CORBA_string rv = NULL;
+ AtkText *text = get_text_from_servant (servant);
+ AtkAttribute *at;
+
+ g_return_val_if_fail (text != NULL, CORBA_string_dup (""));
+
+ set = atk_text_get_run_attributes (text, offset,
+ &intstart_offset, &intend_offset);
+ *startOffset = intstart_offset;
+ *endOffset = intend_offset;
+ *defined = FALSE;
+ cur_attr = (GSList *) set;
+ while (cur_attr)
+ {
+ at = (AtkAttribute *) cur_attr->data;
+ if (!strcmp (at->name, attributename))
+ {
+ rv = CORBA_string_dup (at->value);
+ *defined = TRUE;
+ break;
+ }
+ cur_attr = cur_attr->next;
+ }
+ atk_attribute_set_free (set);
+ return (rv ? rv : CORBA_string_dup (""));
+}
+
+static CORBA_string
impl_getDefaultAttributes (PortableServer_Servant servant,
CORBA_Environment *ev)
{
for (i = 0; i < len; ++i)
{
memcpy (&rangeList->_buffer[i], list->data, sizeof (Accessibility_Text_Range));
- spi_init_any_nil (&rangeList->_buffer[i].data);
+ rangeList->_buffer[i].data._type = TC_null;
+ rangeList->_buffer[i].data._value = NULL;
+ rangeList->_buffer[i].data._release = TRUE;
g_free (list->data);
list = g_slist_next (range_list);
}
epv->setCaretOffset = impl_setCaretOffset;
epv->getRangeExtents = impl_getRangeExtents;
epv->getBoundedRanges = impl_getBoundedRanges;
+ epv->getAttributeValue = impl_getAttributeValue;
}
static void
static char *spi_atk_bridge_null_string = "";
+Accessibility_Role
+spi_role_from_atk_role (AtkRole role)
+{
+ return spi_accessible_role_from_atk_role (role);
+}
+
/*
* deletes an element from the list - in a re-entrant
* safe fashion; advances the element pointer to the next
}
void
-spi_init_any_nil (CORBA_any *any)
+spi_init_any_nil (CORBA_any *any_details,
+ Accessibility_Application app,
+ Accessibility_Role role,
+ CORBA_string name)
{
- any->_type = TC_null;
- any->_value = NULL;
- any->_release = FALSE;
+ Accessibility_EventDetails *details = Accessibility_EventDetails__alloc();
+
+ any_details->_type = TC_Accessibility_EventDetails;
+ any_details->_value = details;
+ any_details->_release = TRUE;
+
+ details->host_application = app;
+ details->source_role = role;
+ details->source_name = CORBA_string_dup (name);
+
+ details->any_data._type = TC_null;
+ details->any_data._value = NULL;
+ details->any_data._release = FALSE;
}
void
-spi_init_any_object (CORBA_any *any, CORBA_Object *o)
+spi_init_any_object (CORBA_any *any_details, Accessibility_Application app,
+ Accessibility_Role role,
+ CORBA_string name,
+ CORBA_Object *o)
{
- CORBA_Environment ev;
- CORBA_exception_init (&ev);
+ Accessibility_EventDetails *details = Accessibility_EventDetails__alloc();
+
+ any_details->_type = TC_Accessibility_EventDetails;
+ any_details->_value = details;
+ any_details->_release = TRUE;
+
+ details->host_application = app;
+ details->source_role = role;
+ details->source_name = CORBA_string_dup (name);
- any->_type = TC_CORBA_Object;
- any->_value = o;
- any->_release = FALSE;
- CORBA_exception_free (&ev);
+ details->any_data._type = TC_CORBA_Object;
+ details->any_data._value = o;
+ details->any_data._release = FALSE;
}
void
-spi_init_any_string (CORBA_any *any, char **string_pointer)
+spi_init_any_string (CORBA_any *any_details, Accessibility_Application app,
+ Accessibility_Role role,
+ CORBA_string name,
+ char **string_pointer)
{
- any->_type = (CORBA_TypeCode) TC_CORBA_string;
+ Accessibility_EventDetails *details = Accessibility_EventDetails__alloc();
+
+ any_details->_type = TC_Accessibility_EventDetails;
+ any_details->_value = details;
+ any_details->_release = TRUE;
+
+ details->host_application = app;
+ details->source_role = role;
+ details->source_name = CORBA_string_dup (name);
+
+ details->any_data._type = (CORBA_TypeCode) TC_CORBA_string;
if (string_pointer && *string_pointer)
- any->_value = string_pointer;
+ details->any_data._value = string_pointer;
else
- any->_value = &spi_atk_bridge_null_string;
- any->_release = FALSE;
+ details->any_data._value = &spi_atk_bridge_null_string;
+ details->any_data._release = FALSE;
}
void
-spi_init_any_rect (CORBA_any *any, AtkRectangle *rect)
+spi_init_any_rect (CORBA_any *any_details,
+ Accessibility_Application app,
+ Accessibility_Role role,
+ CORBA_string name,
+ AtkRectangle *rect)
{
- Accessibility_BoundingBox *box = Accessibility_BoundingBox__alloc ();
- box->x = rect->x;
- box->y = rect->y;
- box->width = rect->width;
- box->height = rect->height;
- any->_type = TC_Accessibility_BoundingBox;
- any->_value = box;
- any->_release = TRUE;
+ Accessibility_EventDetails *details = Accessibility_EventDetails__alloc();
+ Accessibility_BoundingBox *box = Accessibility_BoundingBox__alloc ();
+
+ any_details->_type = TC_Accessibility_EventDetails;
+ any_details->_value = details;
+ any_details->_release = TRUE;
+
+ details->host_application = app;
+ details->source_role = role;
+ details->source_name = CORBA_string_dup (name);
+
+ box->x = rect->x;
+ box->y = rect->y;
+ box->width = rect->width;
+ box->height = rect->height;
+ details->any_data._type = TC_Accessibility_BoundingBox;
+ details->any_data._value = box;
+ details->any_data._release = TRUE;
}
e.source = BONOBO_OBJREF (controller->registry->desktop);
e.detail1 = last_mouse_pos->x;
e.detail2 = last_mouse_pos->y;
- spi_init_any_nil (&e.any_data);
+ spi_init_any_nil (&e.any_data,
+ spi_accessible_new_return (atk_get_root (), FALSE, NULL),
+ Accessibility_ROLE_UNKNOWN,
+ CORBA_string_dup (""));
CORBA_exception_init (&ev);
if (!is_consumed)
{
e.source = BONOBO_OBJREF (controller->registry->desktop);
e.detail1 = *x;
e.detail2 = *y;
- spi_init_any_nil (&e.any_data);
+ spi_init_any_nil (&e.any_data,
+ spi_accessible_new_return (atk_get_root (), FALSE, NULL),
+ Accessibility_ROLE_UNKNOWN,
+ CORBA_string_dup (""));
CORBA_exception_init (&ev);
Accessibility_Registry_notifyEvent (BONOBO_OBJREF (controller->registry),
&e,
e.source = BONOBO_OBJREF (controller->registry->desktop);
e.detail1 = *x - last_mouse_pos->x;
e.detail2 = *y - last_mouse_pos->y;
- spi_init_any_nil (&e.any_data);
+ spi_init_any_nil (&e.any_data,
+ spi_accessible_new_return (atk_get_root (), FALSE, NULL),
+ Accessibility_ROLE_UNKNOWN,
+ CORBA_string_dup (""));
CORBA_exception_init (&ev);
last_mouse_pos->x = *x;
last_mouse_pos->y = *y;
e.source = BONOBO_OBJREF (controller->registry->desktop);
e.detail1 = prev_mask & key_modifier_mask;
e.detail2 = current_mask & key_modifier_mask;
- spi_init_any_nil (&e.any_data);
+ spi_init_any_nil (&e.any_data,
+ spi_accessible_new_return (atk_get_root (), FALSE, NULL),
+ Accessibility_ROLE_UNKNOWN,
+ CORBA_string_dup (""));
CORBA_exception_init (&ev);
Accessibility_Registry_notifyEvent (BONOBO_OBJREF (controller->registry),
&e,
e.source = BONOBO_OBJREF (controller->registry->desktop);
e.detail1 = last_mouse_pos->x;
e.detail2 = last_mouse_pos->y;
- spi_init_any_nil (&e.any_data);
+ spi_init_any_nil (&e.any_data,
+ spi_accessible_new_return (atk_get_root (), FALSE, NULL),
+ Accessibility_ROLE_UNKNOWN,
+ CORBA_string_dup (""));
CORBA_exception_init (&ev);
Accessibility_Registry_notifyEvent (BONOBO_OBJREF (controller->registry),
/* FIXME
spi_init_any_object (&e.any_data, a);
*/
- spi_init_any_nil (&e.any_data);
+ spi_init_any_nil (&e.any_data,
+ e.source,
+ Accessibility_ROLE_DESKTOP_FRAME,
+ CORBA_string_dup (""));
+
Accessibility_Registry_notifyEvent (BONOBO_OBJREF (registry),
&e, &ev);
bonobo_object_release_unref (a, &ev);
/* FIXME
spi_init_any_object (&e.any_data, a);
*/
- spi_init_any_nil (&e.any_data);
+ spi_init_any_nil (&e.any_data,
+ e.source,
+ Accessibility_ROLE_DESKTOP_FRAME,
+ CORBA_string_dup (""));
Accessibility_Accessible_unref (a, &ev);
Accessibility_Registry_notifyEvent (BONOBO_OBJREF (registry),
&e, &ev);
projects / platform / upstream / at-spi2-core.git / commitdiff