3 * AT-SPI - Assistive Technology Service Provider Interface
4 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
6 * Copyright 2001, 2002 Sun Microsystems Inc.,
7 * Copyright 2001, 2002 Ximian, Inc.
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Library General Public
11 * License as published by the Free Software Foundation; either
12 * version 2 of the License, or (at your option) any later version.
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Library General Public License for more details.
19 * You should have received a copy of the GNU Library General Public
20 * License along with this library; if not, write to the
21 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22 * Boston, MA 02111-1307, USA.
25 /* atspi_registry.c: Global functions wrapping the registry */
27 #include "atspi-private.h"
31 AtspiDeviceListener *listener;
33 AtspiKeyMaskType modmask;
34 AtspiKeyEventMask event_types;
36 } DeviceListenerEntry;
38 static GList *device_listeners;
41 * atspi_get_desktop_count:
43 * Gets the number of virtual desktops.
44 * NOTE: multiple virtual desktops are not implemented yet; as a
45 * consequence, this function always returns 1.
47 * Returns: a #gint indicating the number of active virtual desktops.
50 atspi_get_desktop_count ()
57 * @i: a #gint indicating which of the accessible desktops is to be returned.
59 * Gets the virtual desktop indicated by index @i.
60 * NOTE: currently multiple virtual desktops are not implemented;
61 * as a consequence, any @i value different from 0 will not return a
62 * virtual desktop - instead it will return NULL.
64 * Returns: (transfer full): a pointer to the @i-th virtual desktop's
65 * #AtspiAccessible representation.
68 atspi_get_desktop (gint i)
70 if (i != 0) return NULL;
71 return _atspi_ref_accessible (atspi_bus_registry, atspi_path_root);
75 * atspi_get_desktop_list:
77 * Gets the list of virtual desktops. On return, @list will point
78 * to a newly-created, NULL terminated array of virtual desktop
80 * It is the responsibility of the caller to free this array when
81 * it is no longer needed.
82 * NOTE: currently multiple virtual desktops are not implemented;
83 * this implementation always returns a #Garray with a single
84 * #AtspiAccessible desktop.
86 * Returns: (transfer full): a #GArray of desktops.
89 atspi_get_desktop_list ()
91 GArray *array = g_array_new (TRUE, TRUE, sizeof (AtspiAccessible *));
92 AtspiAccessible *desktop;
94 desktop = _atspi_ref_accessible (atspi_bus_registry, atspi_path_root);
96 g_array_index (array, AtspiAccessible *, 0) = desktop;
101 notify_keystroke_listener (DeviceListenerEntry *e)
103 gchar *path = _atspi_device_listener_get_path (e->listener);
104 dbus_uint32_t d_modmask = e->modmask;
105 dbus_uint32_t d_event_types = e->event_types;
106 AtspiEventListenerMode listener_mode;
107 gboolean retval = FALSE;
110 listener_mode.synchronous =
111 (dbus_bool_t) ((e->sync_type & ATSPI_KEYLISTENER_SYNCHRONOUS)!=0);
112 listener_mode.preemptive =
113 (dbus_bool_t) ((e->sync_type & ATSPI_KEYLISTENER_CANCONSUME)!=0);
114 listener_mode.global =
115 (dbus_bool_t) ((e->sync_type & ATSPI_KEYLISTENER_ALL_WINDOWS)!=0);
117 dbus_error_init (&d_error);
118 dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry,
119 atspi_path_dec, atspi_interface_dec,
120 "RegisterKeystrokeListener", &d_error,
121 "oa(iisi)uu(bbb)=>b", path, e->key_set,
122 d_modmask, d_event_types, &listener_mode,
124 if (dbus_error_is_set (&d_error))
126 g_warning ("RegisterKeystrokeListener failed: %s", d_error.message);
127 dbus_error_free (&d_error);
136 device_listener_entry_free (DeviceListenerEntry *e)
138 g_array_free (e->key_set, TRUE);
143 unregister_listener (gpointer data, GObject *object)
146 AtspiDeviceListener *listener = ATSPI_DEVICE_LISTENER (object);
148 for (l = device_listeners; l;)
150 DeviceListenerEntry *e = l->data;
151 if (e->listener == listener)
153 GList *next = l->next;
154 device_listener_entry_free (e);
155 device_listeners = g_list_delete_link (device_listeners, l);
164 * atspi_register_keystroke_listener:
165 * @listener: a pointer to the #AtspiDeviceListener for which
166 * keystroke events are requested.
167 * @key_set: (element-type AtspiKeyDefinition) (allow-none): a pointer to the
168 * #AtspiKeyDefinition array indicating which keystroke events are
170 * to indicate that all keycodes and keyvals for the specified
171 * modifier set are to be included.
172 * @modmask: an #AtspiKeyMaskType mask indicating which
173 * key event modifiers must be set in combination with @keys,
174 * events will only be reported for key events for which all
175 * modifiers in @modmask are set. If you wish to listen for
176 * events with multiple modifier combinations, you must call
177 * #atspi_register_keystroke_listener once for each
179 * @event_types: an #AtspiKeyMaskType mask indicating which
180 * types of key events are requested (%ATSPI_KEY_PRESSED etc.).
181 * @sync_type: an #AtspiKeyListenerSyncType parameter indicating
182 * the behavior of the notification/listener transaction.
183 * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
185 * Registers a listener for keystroke events, either pre-emptively for
186 * all windows (%ATSPI_KEYLISTENER_ALL_WINDOWS),
187 * non-preemptively (%ATSPI_KEYLISTENER_NOSYNC), or
188 * pre-emptively at the toolkit level (%ATSPI_KEYLISTENER_CANCONSUME).
189 * If ALL_WINDOWS or CANCONSUME are used, the event is consumed
190 * upon receipt if one of @listener's callbacks returns %TRUE
191 * (other sync_type values may be available in the future).
193 * Returns: %TRUE if successful, otherwise %FALSE.
196 atspi_register_keystroke_listener (AtspiDeviceListener *listener,
198 AtspiKeyMaskType modmask,
199 AtspiKeyEventMask event_types,
200 gint sync_type, GError **error)
202 DeviceListenerEntry *e;
204 g_return_val_if_fail (listener != NULL, FALSE);
206 e = g_new0 (DeviceListenerEntry, 1);
207 e->listener = listener;
208 e->modmask = modmask;
209 e->event_types = event_types;
210 e->sync_type = sync_type;
214 e->key_set = g_array_sized_new (FALSE, TRUE, sizeof (AtspiKeyDefinition),
216 e->key_set->len = key_set->len;
217 for (i = 0; i < key_set->len; i++)
219 AtspiKeyDefinition *kd = ((AtspiKeyDefinition *) key_set->data) + i;
220 AtspiKeyDefinition *d_kd = ((AtspiKeyDefinition *) e->key_set->data) + i;
221 d_kd->keycode = kd->keycode;
222 d_kd->keysym = kd->keysym;
225 d_kd->keystring = kd->keystring;
229 d_kd->keystring = "";
235 e->key_set = g_array_sized_new (FALSE, TRUE, sizeof (AtspiKeyDefinition), 0);
238 g_object_weak_ref (G_OBJECT (listener), unregister_listener, NULL);
239 device_listeners = g_list_prepend (device_listeners, e);
240 return notify_keystroke_listener (e);
244 * atspi_deregister_keystroke_listener:
245 * @listener: a pointer to the #AtspiDeviceListener for which
246 * keystroke events are requested.
247 * @key_set: (element-type AtspiKeyDefinition) (allow-none): a pointer to the
248 * #AtspiKeyDefinition array indicating which keystroke events are
249 * requested, or %NULL
250 * to indicate that all keycodes and keyvals for the specified
251 * modifier set are to be included.
252 * @modmask: the key modifier mask for which this listener is to be
253 * 'deregistered' (of type #AtspiKeyMaskType).
254 * @event_types: an #AtspiKeyMaskType mask indicating which
255 * types of key events were requested (%ATSPI_KEY_PRESSED, etc.).
256 * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
258 * Removes a keystroke event listener from the registry's listener queue,
259 * ceasing notification of events with modifiers matching @modmask.
261 * Returns: %TRUE if successful, otherwise %FALSE.
264 atspi_deregister_keystroke_listener (AtspiDeviceListener *listener,
266 AtspiKeyMaskType modmask,
267 AtspiKeyEventMask event_types,
271 gchar *path = _atspi_device_listener_get_path (listener);
273 dbus_uint32_t d_modmask = modmask;
274 dbus_uint32_t d_event_types = event_types;
278 dbus_error_init (&d_error);
284 /* copy the keyval filter values from the C api into the DBind KeySet */
287 d_key_set = g_array_sized_new (FALSE, TRUE, sizeof (AtspiKeyDefinition), key_set->len);
288 d_key_set->len = key_set->len;
289 for (i = 0; i < key_set->len; ++i)
291 AtspiKeyDefinition *kd = ((AtspiKeyDefinition *) key_set->data) + i;
292 AtspiKeyDefinition *d_kd = ((AtspiKeyDefinition *) d_key_set->data) + i;
293 d_kd->keycode = kd->keycode;
294 d_kd->keysym = kd->keysym;
297 d_kd->keystring = kd->keystring;
301 d_kd->keystring = "";
307 d_key_set = g_array_sized_new (FALSE, TRUE, sizeof (AtspiKeyDefinition), 0);
310 dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry,
311 atspi_path_dec, atspi_interface_dec,
312 "DeregisterKeystrokeListener", &d_error,
313 "oa(iisi)uu", path, d_key_set, d_modmask,
315 if (dbus_error_is_set (&d_error))
317 g_warning ("DeregisterKeystrokeListener failed: %s", d_error.message);
318 dbus_error_free (&d_error);
321 unregister_listener (listener, NULL);
322 for (l = device_listeners; l;)
324 /* TODO: This code is all wrong / doesn't match what is in
325 * deviceeventcontroller.c. It would be nice to deprecate these methods
326 * in favor of methods that return an ID for the registration that can
327 * be passed to a deregister function, for instance. */
328 DeviceListenerEntry *e = l->data;
329 if (e->modmask == modmask && e->event_types == event_types)
331 GList *next = l->next;
332 device_listener_entry_free (e);
333 device_listeners = g_list_delete_link (device_listeners, l);
339 g_array_free (d_key_set, TRUE);
345 * atspi_register_device_event_listener:
346 * @listener: a pointer to the #AtspiDeviceListener which requests
348 * @event_types: an #AtspiDeviceEventMask mask indicating which
349 * types of key events are requested (%ATSPI_KEY_PRESSED, etc.).
350 * @filter: Unused parameter.
351 * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
353 * Registers a listener for device events, for instance button events.
355 * Returns: %TRUE if successful, otherwise %FALSE.
358 atspi_register_device_event_listener (AtspiDeviceListener *listener,
359 AtspiDeviceEventMask event_types,
360 void *filter, GError **error)
362 gboolean retval = FALSE;
363 dbus_uint32_t d_event_types = event_types;
364 gchar *path = _atspi_device_listener_get_path (listener);
367 dbus_error_init (&d_error);
373 dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry, atspi_path_dec, atspi_interface_dec, "RegisterDeviceEventListener", &d_error, "ou=>b", path, d_event_types, &retval);
374 if (dbus_error_is_set (&d_error))
376 g_warning ("RegisterDeviceEventListener failed: %s", d_error.message);
377 dbus_error_free (&d_error);
385 * atspi_deregister_device_event_listener:
386 * @listener: a pointer to the #AtspiDeviceListener for which
387 * device events are requested.
388 * @filter: Unused parameter.
389 * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
391 * Removes a device event listener from the registry's listener queue,
392 * ceasing notification of events of the specified type.
394 * Returns: %TRUE if successful, otherwise %FALSE.
397 atspi_deregister_device_event_listener (AtspiDeviceListener *listener,
398 void *filter, GError **error)
400 dbus_uint32_t event_types = 0;
401 gchar *path = _atspi_device_listener_get_path (listener);
404 dbus_error_init (&d_error);
411 event_types |= (1 << ATSPI_BUTTON_PRESSED_EVENT);
412 event_types |= (1 << ATSPI_BUTTON_RELEASED_EVENT);
414 dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry, atspi_path_dec, atspi_interface_dec, "DeregisterDeviceEventListener", &d_error, "ou", path, event_types);
415 if (dbus_error_is_set (&d_error))
417 g_warning ("DeregisterDeviceEventListener failed: %s", d_error.message);
418 dbus_error_free (&d_error);
426 * atspi_generate_keyboard_event:
427 * @keyval: a #gint indicating the keycode or keysym of the key event
429 * @keystring: (allow-none): an (optional) UTF-8 string which, if
430 * @synth_type is %ATSPI_KEY_STRING, indicates a 'composed'
431 * keyboard input string being synthesized; this type of
432 * keyboard event synthesis does not emulate hardware
433 * keypresses but injects the string as though a composing
434 * input method (such as XIM) were used.
435 * @synth_type: an #AtspiKeySynthType flag indicating whether @keyval
436 * is to be interpreted as a keysym rather than a keycode
437 * (%ATSPI_KEY_SYM) or a string (%ATSPI_KEY_STRING), or
438 * whether to synthesize %ATSPI_KEY_PRESS,
439 * %ATSPI_KEY_RELEASE, or both (%ATSPI_KEY_PRESSRELEASE).
440 * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
442 * Synthesizes a keyboard event (as if a hardware keyboard event occurred in the
443 * current UI context).
445 * Returns: %TRUE if successful, otherwise %FALSE.
448 atspi_generate_keyboard_event (glong keyval,
449 const gchar *keystring,
450 AtspiKeySynthType synth_type, GError **error)
452 dbus_uint32_t d_synth_type = synth_type;
453 dbus_int32_t d_keyval = keyval;
456 dbus_error_init (&d_error);
459 dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry, atspi_path_dec, atspi_interface_dec, "GenerateKeyboardEvent", &d_error, "isu", d_keyval, keystring, d_synth_type);
460 if (dbus_error_is_set (&d_error))
462 g_warning ("GenerateKeyboardEvent failed: %s", d_error.message);
463 dbus_error_free (&d_error);
470 * atspi_generate_mouse_event:
471 * @x: a #glong indicating the screen x coordinate of the mouse event.
472 * @y: a #glong indicating the screen y coordinate of the mouse event.
473 * @name: a string indicating which mouse event to be synthesized
474 * (e.g. "b1p", "b1c", "b2r", "rel", "abs").
475 * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
477 * Synthesizes a mouse event at a specific screen coordinate.
478 * Most AT clients should use the #AccessibleAction interface when
479 * tempted to generate mouse events, rather than this method.
480 * Event names: b1p = button 1 press; b2r = button 2 release;
481 * b3c = button 3 click; b2d = button 2 double-click;
482 * abs = absolute motion; rel = relative motion.
484 * Returns: %TRUE if successful, otherwise %FALSE.
487 atspi_generate_mouse_event (glong x, glong y, const gchar *name, GError **error)
489 dbus_int32_t d_x = x, d_y = y;
492 dbus_error_init (&d_error);
493 dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry,
494 atspi_path_dec, atspi_interface_dec,
495 "GenerateMouseEvent", &d_error, "iis",
497 if (dbus_error_is_set (&d_error))
499 g_warning ("GenerateMouseEvent failed: %s", d_error.message);
500 dbus_error_free (&d_error);
507 atspi_key_definition_copy (AtspiKeyDefinition *src)
509 AtspiKeyDefinition *dst;
511 dst = g_new0 (AtspiKeyDefinition, 1);
512 dst->keycode = src->keycode;
513 dst->keysym = src->keysym;
515 dst->keystring = g_strdup (src->keystring);
516 dst->unused = src->unused;
521 atspi_key_definition_free (AtspiKeyDefinition *kd)
524 g_free (kd->keystring);
529 _atspi_reregister_device_listeners ()
532 DeviceListenerEntry *e;
534 for (l = device_listeners; l; l = l->next)
537 notify_keystroke_listener (e);
540 G_DEFINE_BOXED_TYPE (AtspiKeyDefinition, atspi_key_definition, atspi_key_definition_copy, atspi_key_definition_free)