2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2008 Novell, Inc.
6 * Copyright 2008, 2009 Codethink Ltd.
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 * Boston, MA 02111-1307, USA.
29 #include "accessible-register.h"
31 #define ATK_BRIDGE_OBJECT_PATH_PREFIX "/org/freedesktop/atspi/accessible"
32 #define ATK_BRIDGE_OBJECT_REFERENCE_TEMPLATE ATK_BRIDGE_OBJECT_PATH_PREFIX "/%d"
33 #define ATK_BRIDGE_PATH_PREFIX_LENGTH 33
36 * This module is responsible for keeping track of all the AtkObjects in
37 * the application, so that they can be accessed remotely and placed in
38 * a client side cache.
40 * To access an AtkObject remotely we need to provide a D-Bus object
41 * path for it. The D-Bus object paths used have a standard prefix
42 * (ATK_BRIDGE_OBJECT_PATH_PREFIX). Appended to this prefix is a string
43 * representation of an integer reference. So to access an AtkObject
44 * remotely we keep a Hashtable that maps the given reference to
45 * the AtkObject pointer. An object in this hash table is said to be 'registered'.
47 * The architecture of AT-SPI dbus is such that AtkObjects are not
48 * remotely reference counted. This means that we need to keep track of
49 * object destruction. When an object is destroyed it must be 'deregistered'
50 * To do this lookup we keep a dbus-id attribute on each AtkObject.
52 * In addition to accessing the objects remotely we must be able to update
53 * the client side cache. This is done using the 'update' signal of the
54 * org.freedesktop.atspi.Tree interface. The update signal should send out
55 * all of the cacheable data for an Accessible object.
58 GHashTable *ref2ptr = NULL; /* Used for converting a D-Bus path (Reference) to the object pointer */
60 static guint counter = 1;
62 /*---------------------------------------------------------------------------*/
65 * Each AtkObject must be asssigned a D-Bus path (Reference)
67 * This function provides an integer reference for a new
71 assign_reference(void)
74 /* Reference of 0 not allowed as used as direct key in hash table */
80 * Returns the reference of the object, or 0 if it is not registered.
83 object_to_ref (AtkObject *accessible)
85 return GPOINTER_TO_INT(g_object_get_data (G_OBJECT (accessible), "dbus-id"));
89 * Converts the Accessible object reference to its D-Bus object path
92 ref_to_path (guint ref)
94 return g_strdup_printf(ATK_BRIDGE_OBJECT_REFERENCE_TEMPLATE, ref);
97 /*---------------------------------------------------------------------------*/
100 * Removes the AtkObject from the reference lookup tables, meaning
101 * it is no longer exposed over D-Bus.
104 deregister_accessible (guint ref)
106 g_hash_table_remove(ref2ptr, ref);
110 * Callback for when a registered AtkObject is destroyed.
113 deregister_callback (gpointer data, GObject *accessible)
116 g_assert (ATK_IS_OBJECT (accessible));
118 ref = atk_dbus_object_to_ref (ATK_OBJECT(accessible));
121 deregister_accessible (ref);
126 * Called to register an AtkObject with AT-SPI and expose it over D-Bus.
129 register_accessible (AtkObject *accessible)
132 g_assert(ATK_IS_OBJECT(accessible));
134 ref = assign_reference();
136 g_hash_table_insert (ref2ptr, GINT_TO_POINTER(ref), accessible);
137 g_object_set_data (G_OBJECT(accessible), "dbus-id", GINT_TO_POINTER(ref));
138 g_object_weak_ref(G_OBJECT(accessible), deregister_callback, NULL);
140 *registered = g_list_prepend (*registered, current);
143 /*---------------------------------------------------------------------------*/
145 typedef void (*ActionFunc) (GList **, AtkObject *);
147 /* Return true if action should be performed */
148 typedef gboolean (*FilterFunc) (AtkObject *);
151 * This function performs a depth first traversal of a tree of AtkObjects.
153 * It uses a FilterFunc to determine if a node needs to have an action
156 * Nodes that are filtered out become leaves and no recursion is performed on
160 traverse_atk_tree (AtkObject *accessible,
165 AtkObject *current, *tmp;
167 GList *uplist = NULL;
171 if (!filter (accessible))
174 stack = g_queue_new ();
175 current = g_object_ref (accessible);
176 action (visited, current)
177 g_queue_push_head (stack, GINT_TO_POINTER (0));
180 * The index held on the stack is the next child node
181 * that needs processing at the corresponding level in the tree.
183 while (!g_queue_is_empty (stack))
185 /* Find the next child node that needs processing */
186 i = GPOINTER_TO_INT(g_queue_peek_head (stack));
188 while (i < atk_object_get_n_accessible_children (current) &&
191 tmp = atk_object_ref_accessible_child (current, i);
192 /* If filter function */
200 g_object_unref (G_OBJECT (tmp));
206 /* Push onto stack */
208 action (visited, current);
209 g_queue_peek_head_link (stack)->data = GINT_TO_POINTER (i+1);
210 g_queue_push_head (stack, GINT_TO_POINTER (0));
216 current = atk_object_get_parent (current);
217 g_object_unref (G_OBJECT (tmp));
218 g_queue_pop_head (stack);
225 /*---------------------------------------------------------------------------*/
228 * Called when an already registered object is updated in such a
229 * way that client side cache needs to be updated.
232 update_accessible (AtkObject *accessible)
235 g_assert(ATK_IS_OBJECT(accessible));
237 ref = atk_dbus_object_to_ref (accessible);
240 spi_emit_cache_update (accessible, atk_adaptor_app_data->bus);
244 /*---------------------------------------------------------------------------*/
247 register_filter (AtkObject *accessible)
249 if (object_to_ref (accessible))
256 register_action (GList **registered, AtkObject *accessible)
258 register_accessible (accessible)
259 *registered = g_list_prepend (*registered, accessible);
263 register_foreach (gpointer data, gpointer user_data)
265 spi_emit_cache_update (ATK_OBJECT (data), atk_adaptor_app_data->bus);
269 register_subtree (AtkObject *accessible)
271 GList *registered = NULL;
273 traverse_atk_tree (accessible,
275 (ActionFunc) register_accessible,
276 (FilterFunc) register_filter);
278 g_list_foreach (registered, register_foreach);
281 /*---------------------------------------------------------------------------*/
284 deregister_filter (AtkObject *accessible)
286 if (!object_to_ref (accessible))
293 deregister_action (GList **deregistered, AtkObject *accessible)
296 g_assert (ATK_IS_OBJECT (accessible));
298 ref = atk_dbus_object_to_ref (accessible);
301 deregister_accessible (ref);
302 *deregistered = g_list_prepend (*deregistered, GINT_TO_POINTER(ref));
307 deregister_foreach (gpointer data, gpointer user_data)
309 spi_emit_cache_update (GPOINTER_TO_INT (data), atk_adaptor_app_data->bus);
313 deregister_subtree (AtkObject *accessible)
315 GList *deregistered = NULL;
317 traverse_atk_tree (accessible,
319 (ActionFunc) deregister_accessible,
320 (FilterFunc) deregister_filter);
322 g_list_foreach (deregistered, deregister_foreach);
325 /*---------------------------------------------------------------------------*/
328 atk_dbus_foreach_registered(GHFunc func, gpointer data)
330 g_hash_table_foreach(ref2ptr, func, data);
334 * Used to lookup an AtkObject from its D-Bus path.
337 atk_dbus_path_to_object (const char *path)
344 if (strncmp(path, ATK_BRIDGE_OBJECT_PATH_PREFIX, ATK_BRIDGE_PATH_PREFIX_LENGTH) != 0)
347 path += ATK_BRIDGE_PATH_PREFIX_LENGTH; /* Skip over the prefix */
350 return atk_get_root();
356 data = g_hash_table_lookup (ref2ptr, GINT_TO_POINTER(index));
358 return ATK_OBJECT (data);
364 * Used to lookup a D-Bus path from the AtkObject.
367 atk_dbus_object_to_path (AtkObject *accessible)
370 g_assert(ATK_IS_OBJECT(accessible));
372 ref = atk_dbus_object_to_ref (accessible);
376 return atk_dbus_ref_to_path (ref);
379 /*---------------------------------------------------------------------------*/
382 * Events are not evaluated for non-registered accessibles.
384 * When a property change is made on a registered accessible
385 * the client side cache should be updated.
387 * When a parent is changed the subtree is de-registered
388 * if the parent is not attached to the root accessible.
391 tree_update_listener (GSignalInvocationHint *signal_hint,
392 guint n_param_values,
393 const GValue *param_values,
396 AtkObject *accessible;
397 AtkPropertyValues *values;
398 const gchar *pname = NULL;
400 accessible = g_value_get_object (¶m_values[0]);
401 values = (AtkPropertyValues*) g_value_get_pointer (¶m_values[1]);
403 pname = values[0].property_name;
405 if (!atk_dbus_object_to_ref (accessible))
408 if (strcmp (pname, "accessible-name") == 0 ||
409 strcmp (pname, "accessible-description"))
411 atk_dbus_update_accessible (accessible);
413 else if (strcmp (pname, "accessible-parent"))
417 ref = atk_dbus_object_to_ref;
424 * Events are not evaluated for non registered accessibles.
426 * When the children of a registered accessible are changed
427 * the subtree, rooted at the child is registered.
430 tree_update_children_listener (GSignalInvocationHint *signal_hint,
431 guint n_param_values,
432 const GValue *param_values,
435 AtkObject *accessible;
436 const gchar *detail = NULL;
438 gboolean child_needs_unref = FALSE;
440 if (signal_hint->detail)
441 detail = g_quark_to_string (signal_hint->detail);
443 accessible = g_value_get_object (¶m_values[0]);
444 if (!strcmp (detail, "add"))
447 int index = g_value_get_uint (param_values + 1);
448 child = g_value_get_pointer (param_values + 2);
450 if (ATK_IS_OBJECT (child))
451 g_object_ref (child);
453 child = atk_object_ref_accessible_child (accessible, index);
455 atk_dbus_register_subtree (child);
456 g_object_unref (child);
462 * Initializes required global data. The update and removal lists
463 * and the reference lookup tables.
465 * Initializes all of the required D-Bus interfaces.
468 atk_dbus_initialize (AtkObject *root)
471 ref2ptr = g_hash_table_new(g_direct_hash, g_direct_equal);
473 atk_dbus_register_accessible (root);
475 atk_add_global_event_listener (tree_update_listener, "Gtk:AtkObject:property-change");
476 atk_add_global_event_listener (tree_update_children_listener, "Gtk:AtkObject:children-changed");
479 /*END------------------------------------------------------------------------*/