atspi/atspi-registry.c

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001, 2002 Sun Microsystems Inc.,
   6  * Copyright 2001, 2002 Ximian, Inc.
   7  *
   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.
  12  *
  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.
  17  *
  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.
  22  */
  23
  24 /* atspi_registry.c: Global functions wrapping the registry */
  25
  26 #include "atspi-private.h"
  27
  28 /**
  29  * atspi_get_desktop_count:
  30  *
  31  * Get the number of virtual desktops.
  32  * NOTE: currently multiple virtual desktops are not implemented, this
  33  *       function always returns '1'.
  34  *
  35  * Returns: an integer indicating the number of active virtual desktops.
  36  **/
  37 gint
  38 atspi_get_desktop_count ()
  39 {
  40   return 1;
  41 }
  42
  43 /**
  44  * atspi_get_desktop:
  45  * @i: an integer indicating which of the accessible desktops is to be returned.
  46  *
  47  * Get the virtual desktop indicated by index @i.
  48  * NOTE: currently multiple virtual desktops are not implemented.
  49  *
  50  * Returns: (transfer full): a pointer to the 'i-th' virtual desktop's
  51  * #AtspiAccessible representation.
  52  **/
  53 AtspiAccessible*
  54 atspi_get_desktop (gint i)
  55 {
  56   if (i != 0) return NULL;
  57   return _atspi_ref_accessible (atspi_bus_registry, atspi_path_root);
  58 }
  59
  60 /**
  61  * atspi_get_desktop_list:
  62  *
  63  * Get the list of virtual desktops.  On return, @list will point
  64  *     to a newly-created, NULL terminated array of virtual desktop
  65  *     pointers.
  66  *     It is the responsibility of the caller to free this array when
  67  *     it is no longer needed.
  68  *
  69  * Not Yet Implemented : this implementation always returns a single
  70  * #Accessible desktop.
  71  *
  72  * Returns: (transfer full): a #GArray of desktops.
  73  **/
  74 GArray *
  75 atspi_get_desktop_list ()
  76 {
  77   GArray *array = g_array_new (TRUE, TRUE, sizeof (AtspiAccessible *));
  78   AtspiAccessible *desktop;
  79
  80   desktop = _atspi_ref_accessible (atspi_bus_registry, atspi_path_root);
  81   if (array)
  82     g_array_index (array, AtspiAccessible *, 0) = desktop;
  83   return array;
  84 }
  85
  86 /**
  87  * atspi_register_keystroke_listener:
  88  * @listener:  a pointer to the #AtspiDeviceListener for which
  89  *             keystroke events are requested.
  90  * @key_set: (element-type AtspiKeyDefinition) (allow-none): a pointer to the
  91  *        #AtspiKeyDefinition array indicating which keystroke events are
  92  *        requested, or %NULL
  93  *        to indicate that all keycodes and keyvals for the specified
  94  *        modifier set are to be included.
  95  * @modmask:   an #AtspiKeyMaskType mask indicating which
  96  *             key event modifiers must be set in combination with @keys,
  97  *             events will only be reported for key events for which all
  98  *             modifiers in @modmask are set.  If you wish to listen for
  99  *             events with multiple modifier combinations you must call
 100  *             register_keystroke_listener() once for each
 101  *             combination.
 102  * @event_types: an #AtspiKeyMaskType mask indicating which
 103  *             types of key events are requested (#ATSPI_KEY_PRESSED, etc.).
 104  * @sync_type: a #AtspiKeyListenerSyncType parameter indicating
 105  *             the behavior of the notification/listener transaction.
 106  *
 107  * Register a listener for keystroke events, either pre-emptively for
 108  *             all windows (ATSPI_KEYLISTENER_ALL_WINDOWS),
 109  *             non-preemptively (ATSPI_KEYLISTENER_NOSYNC), or
 110  *             pre-emptively at the toolkit level (ATSPI_KEYLISTENER_CANCONSUME).
 111  *             If ALL_WINDOWS or CANCONSUME are used, the event is consumed
 112  *             upon receipt if one of @listener's callbacks returns #TRUE.
 113  *             ( Other sync_type values may be available in the future )
 114  *
 115  * Returns: #TRUE if successful, otherwise #FALSE.
 116  **/
 117 gboolean
 118 atspi_register_keystroke_listener (AtspiDeviceListener  *listener,
 119                                          GArray             *key_set,
 120                                          AtspiKeyMaskType         modmask,
 121                                          AtspiKeyEventMask        event_types,
 122                                          AtspiKeyListenerSyncType sync_type,
 123                                          GError **error)
 124 {
 125   GArray *d_key_set;
 126   gchar *path = _atspi_device_listener_get_path (listener);
 127   gint                                i;
 128   dbus_uint32_t d_modmask = modmask;
 129   dbus_uint32_t d_event_types = event_types;
 130   AtspiEventListenerMode     listener_mode;
 131   gboolean                          retval = FALSE;
 132   DBusError d_error;
 133
 134   if (!listener)
 135     {
 136       return retval;
 137     }
 138
 139   /* copy the keyval filter values from the C api into the DBind KeySet */
 140   if (key_set)
 141     {
 142       d_key_set = g_array_sized_new (FALSE, TRUE, sizeof (AtspiKeyDefinition), key_set->len);
 143       d_key_set->len = key_set->len;
 144       for (i = 0; i < key_set->len; ++i)
 145         {
 146           AtspiKeyDefinition *kd =  ((AtspiKeyDefinition *) key_set->data) + i;
 147           AtspiKeyDefinition *d_kd =  ((AtspiKeyDefinition *) d_key_set->data) + i;
 148           d_kd->keycode = kd->keycode;
 149           d_kd->keysym = kd->keysym;
 150           if (kd->keystring)
 151             {
 152               d_kd->keystring = kd->keystring;
 153             }
 154           else
 155             {
 156               d_kd->keystring = "";
 157             }
 158         }
 159     }
 160   else
 161     {
 162       d_key_set = g_array_sized_new (FALSE, TRUE, sizeof (AtspiKeyDefinition), 0);
 163     }
 164
 165   listener_mode.synchronous =
 166           (dbus_bool_t) ((sync_type & ATSPI_KEYLISTENER_SYNCHRONOUS)!=0);
 167   listener_mode.preemptive =
 168           (dbus_bool_t) ((sync_type & ATSPI_KEYLISTENER_CANCONSUME)!=0);
 169   listener_mode.global =
 170           (dbus_bool_t) ((sync_type & ATSPI_KEYLISTENER_ALL_WINDOWS)!=0);
 171
 172     dbus_error_init (&d_error);
 173     dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry, atspi_path_dec, atspi_interface_dec, "RegisterKeystrokeListener", &d_error, "oa(iisi)uu(bbb)=>b", path, d_key_set, d_modmask, d_event_types, &listener_mode, &retval);
 174
 175   g_array_free (d_key_set, TRUE);
 176   g_free (path);
 177
 178   return retval;
 179 }
 180
 181 /**
 182  * atspi_deregister_keystroke_listener:
 183  * @listener: a pointer to the #AtspiDeviceListener for which
 184  *            keystroke events are requested.
 185  * @key_set: (element-type AtspiKeyDefinition) (allow-none): a pointer to the
 186  *        #AtspiKeyDefinition array indicating which keystroke events are
 187  *        requested, or %NULL
 188  *        to indicate that all keycodes and keyvals for the specified
 189  *        modifier set are to be included.
 190  * @modmask:  the key modifier mask for which this listener is to be
 191  *            'deregistered' (of type #AtspiKeyMaskType).
 192  * @event_types: an #AtspiKeyMaskType mask indicating which
 193  *             types of key events were requested (#ATSPI_KEY_PRESSED, etc.).
 194  *
 195  * Removes a keystroke event listener from the registry's listener queue,
 196  *            ceasing notification of events with modifiers matching @modmask.
 197  *
 198  * Returns: #TRUE if successful, otherwise #FALSE.
 199  **/
 200 gboolean
 201 atspi_deregister_keystroke_listener (AtspiDeviceListener *listener,
 202                                      GArray              *key_set,
 203                                      AtspiKeyMaskType     modmask,
 204                                      AtspiKeyEventMask    event_types,
 205                                      GError             **error)
 206 {
 207   gchar *path = _atspi_device_listener_get_path (listener);
 208   dbus_uint32_t d_modmask = modmask;
 209   dbus_uint32_t d_event_types = event_types;
 210   DBusError d_error;
 211
 212   dbus_error_init (&d_error);
 213   if (!listener)
 214     {
 215       return FALSE;
 216     }
 217
 218   dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry,
 219                                atspi_path_dec, atspi_interface_dec,
 220                                "DeregisterKeystrokeListener", &d_error,
 221                                "oa(iisi)uu", path, &key_set, d_modmask,
 222                                d_event_types);
 223   g_free (path);
 224   return TRUE;
 225 }
 226
 227 /**
 228  * atspi_register_device_event_listener:
 229  * @listener:  a pointer to the #AtspiDeviceListener which requests
 230  *             the events.
 231  * @event_types: an #AtspiDeviceEventMask mask indicating which
 232  *             types of key events are requested (#ATSPI_KEY_PRESSED, etc.).
 233  * @filter: Unused parameter.
 234  *
 235  * Register a listener for device events, for instance button events.
 236  *
 237  * Returns: #TRUE if successful, otherwise #FALSE.
 238  **/
 239 gboolean
 240 atspi_register_device_event_listener (AtspiDeviceListener  *listener,
 241                                  AtspiDeviceEventMask  event_types,
 242                                  void                      *filter, GError **error)
 243 {
 244   gboolean                          retval = FALSE;
 245   dbus_uint32_t d_event_types = event_types;
 246   gchar *path = _atspi_device_listener_get_path (listener);
 247   DBusError d_error;
 248
 249   dbus_error_init (&d_error);
 250   if (!listener)
 251     {
 252       return retval;
 253     }
 254
 255     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);
 256   g_free (path);
 257   return retval;
 258 }
 259
 260 /**
 261  * atspi_deregister_device_event_listener:
 262  * @listener: a pointer to the #AtspiDeviceListener for which
 263  *            device events are requested.
 264  * @filter: Unused parameter.
 265  *
 266  * Removes a device event listener from the registry's listener queue,
 267  *            ceasing notification of events of the specified type.
 268  *
 269  * Returns: #TRUE if successful, otherwise #FALSE.
 270  **/
 271 gboolean
 272 atspi_deregister_device_event_listener (AtspiDeviceListener *listener,
 273                                    void                     *filter, GError **error)
 274 {
 275   dbus_uint32_t event_types = 0;
 276   gchar *path = _atspi_device_listener_get_path (listener);
 277   DBusError d_error;
 278
 279   dbus_error_init (&d_error);
 280
 281   if (!listener)
 282     {
 283       return FALSE;
 284     }
 285
 286   event_types |= (1 << ATSPI_BUTTON_PRESSED_EVENT);
 287   event_types |= (1 << ATSPI_BUTTON_RELEASED_EVENT);
 288
 289     dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry, atspi_path_dec, atspi_interface_dec, "DeregisterDeviceEventListener", &d_error, "ou", path, event_types);
 290   g_free (path);
 291   return TRUE;
 292 }
 293
 294 /**
 295  * atspi_generate_keyboard_event:
 296  * @keyval: a long integer indicating the keycode or keysym of the key event
 297  *           being synthesized.
 298  * @keystring: an (optional) UTF-8 string which, if @keyval is NULL,
 299  *           indicates a 'composed' keyboard input string which is
 300  *           being synthesized; this type of keyboard event synthesis does
 301  *           not emulate hardware keypresses but injects the string
 302  *           as though a composing input method (such as XIM) were used.
 303  * @synth_type: a #AtspiKeySynthType flag indicating whether @keyval
 304  *           is to be interpreted as a keysym rather than a keycode
 305  *           (ATSPI_KEYSYM), or whether to synthesize
 306  *           ATSPI_KEY_PRESS, ATSPI_KEY_RELEASE, or both (ATSPI_KEY_PRESSRELEASE).
 307  *
 308  * Synthesize a keyboard event (as if a hardware keyboard event occurred in the
 309  * current UI context).
 310  *
 311  * Returns: #TRUE if successful, otherwise #FALSE.
 312  **/
 313 gboolean
 314 atspi_generate_keyboard_event (glong keyval,
 315                            const gchar *keystring,
 316                            AtspiKeySynthType synth_type, GError **error)
 317 {
 318   dbus_uint32_t d_synth_type = synth_type;
 319   dbus_int32_t d_keyval = keyval;
 320   DBusError d_error;
 321
 322   dbus_error_init (&d_error);
 323   if (!keystring) keystring = "";
 324     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);
 325
 326   return TRUE;
 327 }
 328
 329 /**
 330  * atspi_generate_mouse_event:
 331  * @x: a #long indicating the screen x coordinate of the mouse event.
 332  * @y: a #long indicating the screen y coordinate of the mouse event.
 333  * @name: a string indicating which mouse event to be synthesized
 334  *        (e.g. "b1p", "b1c", "b2r", "rel", "abs").
 335  *
 336  * Synthesize a mouse event at a specific screen coordinate.
 337  * Most AT clients should use the #AccessibleAction interface when
 338  * tempted to generate mouse events, rather than this method.
 339  * Event names: b1p = button 1 press; b2r = button 2 release;
 340  *              b3c = button 3 click; b2d = button 2 double-click;
 341  *              abs = absolute motion; rel = relative motion.
 342  *
 343  * Returns: #TRUE if successful, otherwise #FALSE.
 344  **/
 345 gboolean
 346 atspi_generate_mouse_event (glong x, glong y, const gchar *name, GError **error)
 347 {
 348   dbus_int32_t d_x = x, d_y = y;
 349   DBusError d_error;
 350
 351   dbus_error_init (&d_error);
 352     dbind_method_call_reentrant (_atspi_bus(), atspi_bus_registry,
 353                                  atspi_path_dec, atspi_interface_dec,
 354                                  "GenerateMouseEvent", &d_error, "iis",
 355                                  d_x, d_y, name);
 356   return TRUE;
 357 }
 358
 359 AtspiKeyDefinition *
 360 atspi_key_definition_copy (AtspiKeyDefinition *src)
 361 {
 362   AtspiKeyDefinition *dst;
 363
 364   dst = g_new0 (AtspiKeyDefinition, 1);
 365   dst->keycode = src->keycode;
 366   dst->keysym = src->keysym;
 367   if (src->keystring)
 368     dst->keystring = g_strdup (src->keystring);
 369   dst->unused = src->unused;
 370   return dst;
 371 }
 372
 373 void
 374 atspi_key_definition_free (AtspiKeyDefinition *kd)
 375 {
 376   if (kd->keystring)
 377     g_free (kd->keystring);
 378   g_free (kd);
 379 }
 380
 381 G_DEFINE_BOXED_TYPE (AtspiKeyDefinition, atspi_key_definition, atspi_key_definition_copy, atspi_key_definition_free)