cspi/spi_event.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, 2003 Sun Microsystems Inc.,
   6  * Copyright 2001, 2002, 2003 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 #include <cspi/spi-private.h>
  25
  26 static GSList *_cspi_event_queue = NULL;
  27
  28 /**
  29  * SPI_freeAccessibleKeySet:
  30  * @keyset: An AccessibleKeyset to free.
  31  *
  32  * Release the memory used by an AccessibleKeySet.
  33  *
  34  **/
  35 void
  36 SPI_freeAccessibleKeySet (AccessibleKeySet *keyset)
  37 {
  38   int i = 0;
  39   g_free (keyset->keysyms);
  40   g_free (keyset->keycodes);
  41   while (keyset->keystrings [i])
  42     {
  43       g_free (keyset->keystrings [i++]);
  44     }
  45   g_free (keyset->keystrings);
  46   g_free (keyset);
  47 }
  48
  49 /**
  50  * SPI_createAccessibleKeySet:
  51  * @len: the number of key values in the key set.
  52  * @keysyms: a UTF-8 string containing symbolic key values to be matched, or NULL if
  53  *           matching is performed against other key values instead.
  54  * @keycodes: an array of unsigned short values which are the hardware keycodes
  55  *           to be matched, or NULL if the keyset is specified solely by keysyms
  56  *           and/or keystrings.
  57  * @keystrings: an array of null-terminated character strings which specify key
  58  *             name values to match, or NULL if the keyset is specified solely by
  59  *             keycodes and/or keysyms.
  60  *
  61  * Create a new #AccessibleKeySet of a specified length.
  62  * A KeySet is used typically to match key event values, and a matches are made
  63  * using the following criteria: a match exists with a key event if all non-null
  64  * i-th members of the keyset match the key event.
  65  * If both keystring and keysym values are NULL, a keycode value match is
  66  * forced, thus the match for keysym=0, keycode=0, keystring=NULL is
  67  * keycode 0.
  68  *
  69  * Returns: a pointer to a newly-created #AccessibleKeySet.
  70  *
  71  **/
  72 AccessibleKeySet *
  73 SPI_createAccessibleKeySet (int len, const char *keysyms, short *keycodes,
  74                             const char **keystrings)
  75 {
  76   AccessibleKeySet *keyset = g_new0 (AccessibleKeySet, 1);
  77   int i, keysym_len = 0;
  78   const char *keysym_ptr = keysyms;
  79   keyset->len = len;
  80   keyset->keysyms = g_new0 (unsigned long, len);
  81   keyset->keycodes = g_new0 (unsigned short, len);
  82   keyset->keystrings = g_new0 (char *, len);
  83   if (keysyms)
  84     {
  85       keysym_len = g_utf8_strlen (keysyms, -1);
  86     }
  87   for (i = 0; i < len; ++i)
  88     {
  89       if (i < keysym_len)
  90         {
  91           keyset->keysyms [i] = (unsigned long) g_utf8_get_char (keysym_ptr);
  92           keysym_ptr = g_utf8_find_next_char (keysym_ptr, NULL);
  93         }
  94       else
  95         {
  96           keyset->keysyms [i] = 0;
  97         }
  98       if (keycodes)
  99         {
 100           keyset->keycodes [i] = keycodes [i];
 101         }
 102       if (keystrings)
 103         {
 104           keyset->keystrings [i] = g_strdup (keystrings [i]);
 105         }
 106     }
 107   return keyset;
 108 }
 109
 110 /**
 111  * SPI_createAccessibleEventListener:
 112  * @callback : an #AccessibleEventListenerCB callback function, or NULL.
 113  * @user_data: a pointer to data which will be passed to the callback when invoked.
 114  *
 115  * Create a new #AccessibleEventListener with a specified (in-process) callback function.
 116  *
 117  * Returns: a pointer to a newly-created #AccessibleEventListener.
 118  *
 119  **/
 120 AccessibleEventListener *
 121 SPI_createAccessibleEventListener (AccessibleEventListenerCB callback,
 122                                    void                     *user_data)
 123 {
 124   AccessibleEventListener *listener = cspi_event_listener_new ();
 125   if (callback)
 126     {
 127       AccessibleEventListener_addCallback (listener, callback, user_data);
 128     }
 129   return listener;
 130 }
 131
 132 /**
 133  * AccessibleEventListener_addCallback:
 134  * @listener: the #AccessibleEventListener instance to modify.
 135  * @callback: an #AccessibleEventListenerCB function pointer.
 136  * @user_data: a pointer to data which will be passed to the callback when invoked.
 137  *
 138  * Add an in-process callback function to an existing AccessibleEventListener.
 139  * Note that the callback function must live in the same address
 140  * space as the AccessibleEventListener implementation code, thus one should not
 141  * use this function to attach callbacks to a 'remote' event listener
 142  * (that is, one that was not created by a client call to
 143  * createAccessibleEventListener ();
 144  *
 145  * Returns: #TRUE if successful, otherwise #FALSE.
 146  *
 147  **/
 148 SPIBoolean
 149 AccessibleEventListener_addCallback (AccessibleEventListener *listener,
 150                                      AccessibleEventListenerCB callback,
 151                                      void                     *user_data)
 152 {
 153   cspi_event_listener_add_cb (listener, callback, user_data);
 154   return TRUE;
 155 }
 156
 157 /**
 158  * AccessibleEventListener_unref:
 159  * @listener: a pointer to the #AccessibleEventListener being operated on.
 160  *
 161  * Decrements an #AccessibleEventListener's reference count.
 162  **/
 163 void
 164 AccessibleEventListener_unref (AccessibleEventListener *listener)
 165 {
 166   cspi_event_listener_unref (listener);
 167 }
 168
 169 /**
 170  * AccessibleEventListener_removeCallback:
 171  * @listener: the #AccessibleEventListener instance to modify.
 172  * @callback: an #AccessibleEventListenerCB function pointer.
 173  *
 174  * Remove an in-process callback function from an existing AccessibleEventListener.
 175  *
 176  * Returns: #TRUE if successful, otherwise #FALSE.
 177  *
 178  **/
 179 SPIBoolean
 180 AccessibleEventListener_removeCallback (AccessibleEventListener  *listener,
 181                                         AccessibleEventListenerCB callback)
 182 {
 183   cspi_event_listener_remove_cb (listener, callback);
 184   return TRUE;
 185 }
 186
 187 /**
 188  * SPI_createAccessibleKeystrokeListener:
 189  * @callback : an #AccessibleKeystrokeListenerCB callback function, or NULL.
 190  * @user_data: a pointer to data which will be passed to the callback when invoked.
 191  *
 192  * Create a new #AccessibleKeystrokeListener with a specified callback function.
 193  *
 194  * Returns: a pointer to a newly-created #AccessibleKeystrokeListener.
 195  *
 196  **/
 197 AccessibleKeystrokeListener *
 198 SPI_createAccessibleKeystrokeListener (AccessibleKeystrokeListenerCB callback,
 199                                        void                         *user_data)
 200 {
 201   AccessibleDeviceListener *listener = cspi_device_listener_new ();
 202   if (callback)
 203     {
 204       AccessibleDeviceListener_addCallback (listener, callback, user_data);
 205     }
 206   return listener;
 207 }
 208
 209 /**
 210  * AccessibleKeystrokeListener_addCallback:
 211  * @listener: the #AccessibleKeystrokeListener instance to modify.
 212  * @callback: an #AccessibleKeystrokeListenerCB function pointer.
 213  * @user_data: a pointer to data which will be passed to the callback when invoked.
 214  *
 215  * Add an in-process callback function to an existing #AccessibleKeystrokeListener.
 216  *
 217  * Returns: #TRUE if successful, otherwise #FALSE.
 218  *
 219  **/
 220 SPIBoolean
 221 AccessibleKeystrokeListener_addCallback (AccessibleKeystrokeListener *listener,
 222                                          AccessibleKeystrokeListenerCB callback,
 223                                          void                         *user_data)
 224 {
 225   cspi_device_listener_add_cb (listener, callback, user_data);
 226   return TRUE;
 227 }
 228
 229 /**
 230  * AccessibleKeystrokeListener_removeCallback:
 231  * @listener: the #AccessibleKeystrokeListener instance to modify.
 232  * @callback: an #AccessibleKeystrokeListenerCB function pointer.
 233  *
 234  * Remove an in-process callback function from an existing #AccessibleKeystrokeListener.
 235  *
 236  * Returns: #TRUE if successful, otherwise #FALSE.
 237  *
 238  **/
 239 SPIBoolean
 240 AccessibleKeystrokeListener_removeCallback (AccessibleKeystrokeListener *listener,
 241                                             AccessibleKeystrokeListenerCB callback)
 242 {
 243   cspi_device_listener_remove_cb (listener, callback);
 244   return TRUE;
 245 }
 246
 247 /**
 248  * AccessibleKeystrokeListener_unref:
 249  * @listener: a pointer to the #AccessibleKeystrokeListener being operated on.
 250  *
 251  * Decrements an #AccessibleKeystrokeListener's reference count.
 252  **/
 253 void
 254 AccessibleKeystrokeListener_unref (AccessibleKeystrokeListener *listener)
 255 {
 256   cspi_device_listener_unref (listener);
 257 }
 258
 259 /**
 260  * SPI_createAccessibleDeviceListener:
 261  * @callback : an #AccessibleDeviceListenerCB callback function, or NULL.
 262  * @user_data: a pointer to data which will be passed to the callback when invoked.
 263  *
 264  * Create a new #AccessibleDeviceListener with a specified callback function.
 265  *
 266  * Returns: a pointer to a newly-created #AccessibleDeviceListener.
 267  *
 268  **/
 269 AccessibleDeviceListener *
 270 SPI_createAccessibleDeviceListener (AccessibleDeviceListenerCB callback,
 271                                        void                         *user_data)
 272 {
 273   AccessibleDeviceListener *listener = cspi_device_listener_new ();
 274   if (callback)
 275     {
 276       AccessibleDeviceListener_addCallback (listener, callback, user_data);
 277     }
 278   return listener;
 279 }
 280
 281 /**
 282  * AccessibleDeviceListener_addCallback:
 283  * @listener: the #AccessibleDeviceListener instance to modify.
 284  * @callback: an #AccessibleDeviceListenerCB function pointer.
 285  * @user_data: a pointer to data which will be passed to the callback when invoked.
 286  *
 287  * Add an in-process callback function to an existing #AccessibleDeviceListener.
 288  *
 289  * Returns: #TRUE if successful, otherwise #FALSE.
 290  *
 291  **/
 292 SPIBoolean
 293 AccessibleDeviceListener_addCallback (AccessibleDeviceListener *listener,
 294                                          AccessibleDeviceListenerCB callback,
 295                                          void                         *user_data)
 296 {
 297   cspi_device_listener_add_cb (listener, callback, user_data);
 298   return TRUE;
 299 }
 300
 301 /**
 302  * AccessibleDeviceListener_removeCallback:
 303  * @listener: the #AccessibleDeviceListener instance to modify.
 304  * @callback: an #AccessibleDeviceListenerCB function pointer.
 305  *
 306  * Remove an in-process callback function from an existing #AccessibleDeviceListener.
 307  *
 308  * Returns: #TRUE if successful, otherwise #FALSE.
 309  *
 310  **/
 311 SPIBoolean
 312 AccessibleDeviceListener_removeCallback (AccessibleDeviceListener *listener,
 313                                             AccessibleDeviceListenerCB callback)
 314 {
 315   cspi_device_listener_remove_cb (listener, callback);
 316   return TRUE;
 317 }
 318
 319 /**
 320  * AccessibleDeviceListener_unref:
 321  * @listener: a pointer to the #AccessibleDeviceListener being operated on.
 322  *
 323  * Decrements an #AccessibleDeviceListener's reference count.
 324  **/
 325 void
 326 AccessibleDeviceListener_unref (AccessibleDeviceListener *listener)
 327 {
 328   cspi_device_listener_unref (listener);
 329 }
 330
 331 static char *
 332 cspi_internal_event_get_text (const InternalEvent *e)
 333 {
 334   g_return_val_if_fail (e, NULL);
 335   if (e->event.v_type == EVENT_DATA_STRING)
 336     {
 337       return g_strdup (e->event.v.text? e->event.v.text: "");
 338     }
 339   return NULL;
 340 }
 341
 342 static Accessible *
 343 cspi_internal_event_get_object (const InternalEvent *e)
 344 {
 345   g_return_val_if_fail (e, NULL);
 346   if (e->event.v_type == EVENT_DATA_OBJECT)
 347     {
 348       cspi_object_ref (e->event.v.accessible);
 349       return e->event.v.accessible;
 350     }
 351   return NULL;
 352 }
 353
 354 static SPIRect *
 355 cspi_internal_event_get_rect (const InternalEvent *e)
 356 {
 357   g_return_val_if_fail (e, NULL);
 358   if (e->event.v_type == EVENT_DATA_RECT)
 359   {
 360       SPIRect *rect = g_new (SPIRect, 1);
 361       if (rect) memcpy (rect, &e->event.v.rect, sizeof(*rect));
 362       return rect;
 363     }
 364   return NULL;
 365 }
 366
 367 /**
 368  * AccessibleEvent_getSourceName:
 369  * @e: an #AccessibleEvent to be queried.
 370  *
 371  * Get the 'accessible-name' of the object emitting the event.
 372  *
 373  * Returns: The name of the event source, or NULL if the event source cannot be identified
 374  *          or does not report a name.
 375  */
 376 char*        AccessibleEvent_getSourceName (const AccessibleEvent *e)
 377 {
 378   if (e && e->source)
 379     {
 380       return Accessible_getName (e->source);
 381     }
 382   return NULL;
 383 }
 384
 385 /**
 386  * AccessibleEvent_getSourceRole:
 387  * @e: an #AccessibleEvent to be queried.
 388  *
 389  * Get the #AccessibleRole of the object emitting the event.
 390  *
 391  * Returns: #AccessibleRole of the event source, or SPI_ROLE_UNKNOWN
 392  *          if the event source's role is unknown or unspecified.
 393  *          (Some kinds of events, such as 'mouse:' events or
 394  *          toolkit events, don't have associated object roles.)
 395  */
 396 AccessibleRole AccessibleEvent_getSourceRole (const AccessibleEvent *e)
 397 {
 398   if (e && e->source)
 399     {
 400       return Accessible_getRole (e->source);
 401     }
 402         return SPI_ROLE_UNKNOWN;
 403 }
 404
 405 /**
 406  * AccessibleEvent_getSourceApplication:
 407  * @e: an #AccessibleEvent to be queried.
 408  *
 409  * Get the #Application hosting the object which emitted the event.
 410  *
 411  * Returns: A pointer to the host #Application contining the event source
 412  *          component.
 413  */
 414 #if 0
 415 AccessibleApplication* AccessibleEvent_getSourceApplication (const AccessibleEvent *e)
 416 {
 417 xyzzy
 418     InternalEvent *ie = (InternalEvent *)e;
 419     CORBA_any *any = ((ie && ie->data) ? (CORBA_any *)ie->data : NULL);
 420     if (any &&
 421         CORBA_TypeCode_equivalent (any->_type,
 422                                    TC_Accessibility_EventDetails, NULL))
 423       {
 424           Accessibility_EventDetails *details = (Accessibility_EventDetails *) any->_value;
 425           return  cspi_object_take (details->host_application);
 426       }
 427     else
 428         return NULL;
 429 }
 430 #endif
 431
 432 /**
 433  * AccessibleEvent_getSourceDetails:
 434  * @e: an #AccessibleEvent to be queried.
 435  * @name: a pointer to a character string which will point to the name of the event source
 436  * on successful completion of the call.
 437  * @role: a pointer to an #AccessibleRole which will point to the role of the event source
 438  * on successful completion of the call.
 439  * @app: A pointer to an #AccessibleApplication which points to the host application for this event
 440  * on successful completion of the call.
 441  *
 442  * Get the host #Application, "accessible name", and #AccessibleRole
 443  * of the object which emitted the event.
 444  *
 445  * Returns: TRUE if the source details were successfully retrieved,
 446  *          FALSE if they were not, either due to error, incomplete data,
 447  *          or the fact that the event did not encapsulate the required data.
 448  */
 449 #if 0
 450 SPIBoolean   AccessibleEvent_getSourceDetails (const AccessibleEvent *e,
 451                                                char **name, AccessibleRole *role,
 452                                                AccessibleApplication **app)
 453 {
 454     InternalEvent *ie = (InternalEvent *)e;
 455     CORBA_any *any = ((ie && ie->data) ? (CORBA_any *)ie->data : NULL);
 456     if (any &&
 457         CORBA_TypeCode_equivalent (any->_type,
 458                                    TC_Accessibility_EventDetails, NULL))
 459       {
 460           Accessibility_EventDetails *details = (Accessibility_EventDetails *) any->_value;
 461           *name = CORBA_string_dup (details->source_name);
 462           *role = cspi_role_from_spi_role (details->source_role);
 463           *app = cspi_object_take (details->host_application);
 464           return TRUE;
 465       }
 466     else
 467       {
 468         *name = NULL;
 469         *role = SPI_ROLE_UNKNOWN;
 470         *app = NULL;
 471         return FALSE;
 472       }
 473 }
 474 #endif
 475
 476 /**
 477  * AccessibleTextChangedEvent_getChangeString:
 478  * @e: a pointer to the #AccessibleEvent being queried.
 479  *
 480  * Queries an #AccessibleEvent of type "object:text-changed",
 481  *         returning the text inserted or deleted.
 482  *
 483  * Returns: a UTF-8 text string indicating the text inserted,
 484  *          deleted, or substituted by this event.
 485  **/
 486 char *
 487 AccessibleTextChangedEvent_getChangeString (const AccessibleEvent *e)
 488 {
 489   const InternalEvent *foo = (InternalEvent *) e;
 490   /* TODO: check the event type. */
 491   return cspi_internal_event_get_text (foo);
 492 }
 493
 494 /**
 495  * AccessibleTextSelectionChangedEvent_getSelectionString:
 496  * @e: a pointer to the #AccessibleEvent being queried.
 497  *
 498  * Queries an #AccessibleEvent of type "object:text-selection-changed",
 499  *         returning the newly added, removed, or modified selection string.
 500  *
 501  * Returns: a UTF-8 text string indicating the recently changed selection.
 502  **/
 503 char *
 504 AccessibleTextSelectionChangedEvent_getSelectionString (const AccessibleEvent *e)
 505 {
 506   const InternalEvent *foo = (InternalEvent *) e;
 507   /* TODO: check the event type. */
 508   return cspi_internal_event_get_text (foo);
 509 }
 510
 511 /**
 512  * AccessibleWindowEvent_getTitleString:
 513  * @e: a pointer to the #AccessibleEvent being queried.
 514  *
 515  * Queries an #AccessibleEvent of type "window:",
 516  *         returning the window title.
 517  *
 518  * Returns: a UTF-8 text string representing the title of the
 519  *         recently changed window.
 520  **/
 521 char *
 522 AccessibleWindowEvent_getTitleString (const AccessibleEvent *e)
 523 {
 524   const InternalEvent *foo = (InternalEvent *) e;
 525   /* TODO: check the event type. */
 526   return cspi_internal_event_get_text (foo);
 527 }
 528
 529 /**
 530  * AccessibleChildChangedEvent_getChildAccessible:
 531  * @e: a pointer to the #AccessibleEvent being queried.
 532  *
 533  * Queries an #AccessibleEvent of type "object:children_changed"
 534  *         to get a reference to the changed #Accessible.
 535  *         Note that context #Accessibles are not guaranteed to outlive
 536  *         event delivery, in which case this call may return %NULL
 537  *         even if the object existed at the time of dispatch.
 538  *
 539  * Returns: the context #Accessible for the event, or %NULL if
 540  *          there is no longer a valid context #Accessible
 541  *          object for the event.
 542  **/
 543 Accessible *
 544 AccessibleChildChangedEvent_getChildAccessible (const AccessibleEvent *e)
 545 {
 546   const InternalEvent *foo = (InternalEvent *) e;
 547   return (Accessible *) cspi_internal_event_get_object (foo);
 548 }
 549
 550 /**
 551  * AccessibleParentChangedEvent_getParentAccessible:
 552  * @e: a pointer to the #AccessibleEvent being queried.
 553  *
 554  * Queries an #AccessibleEvent of type "object:property-change:accessible-parent"
 555  *         to get a reference to the changed #Accessible.
 556  *         Note that context #Accessibles are not guaranteed to outlive
 557  *         event delivery, in which case this call may return %NULL
 558  *         even if the object existed at the time of dispatch.
 559  *
 560  * Returns: an #Accessible pointer representing the new parent object.
 561  **/
 562 Accessible *
 563 AccessibleParentChangedEvent_getParentAccessible (const AccessibleEvent *e)
 564 {
 565   const InternalEvent *foo = (InternalEvent *) e;
 566   return (Accessible *) cspi_internal_event_get_object (foo);
 567 }
 568
 569 /**
 570  * AccessibleActiveDescendantChangedEvent_getActiveDescendant:
 571  * @e: a pointer to the #AccessibleEvent being queried.
 572  *
 573  * Queries an #AccessibleEvent of type "object:active-descendant-changed"
 574  *         to get a reference to the changed #Accessible.
 575  *         Note that context #Accessibles are not guaranteed to outlive
 576  *         event delivery, in which case this call may return %NULL
 577  *         even if the object existed at the time of dispatch.
 578  *
 579  * Returns: an #Accessible pointer representing the new active descendant.
 580  **/
 581 Accessible *
 582 AccessibleActiveDescendantChangedEvent_getActiveDescendant (const AccessibleEvent *e)
 583 {
 584   const InternalEvent *foo = (InternalEvent *) e;
 585   return (Accessible *) cspi_internal_event_get_object (foo);
 586 }
 587
 588 /**
 589  * AccessibleTableSummaryChangedEvent_getSummaryAccessible:
 590  * @e: a pointer to the #AccessibleEvent being queried.
 591  *
 592  * Queries an #AccessibleEvent of type "object:property-changed:accessible-table-summary"
 593  *         to get a reference to the changed #Accessible.
 594  *         Note that context #Accessibles are not guaranteed to outlive
 595  *         event delivery, in which case this call may return %NULL
 596  *         even if the object existed at the time of dispatch.
 597  *
 598  * Returns: an #Accessible pointer representing the new table summary.
 599  **/
 600 Accessible *
 601 AccessibleTableSummaryChangedEvent_getSummaryAccessible (const AccessibleEvent *e)
 602 {
 603   const InternalEvent *foo = (InternalEvent *) e;
 604   return (Accessible *) cspi_internal_event_get_object (foo);
 605 }
 606
 607 /**
 608  * AccessibleTableHeaderChangedEvent_getHeaderAccessible:
 609  * @e: a pointer to the #AccessibleEvent being queried.
 610  *
 611  * Queries an #AccessibleEvent of type
 612  *         "object:property-changed:accessible-table-row-header" or
 613  *         "object:property-changed:accessible-table-column-header"
 614  *         to get a reference to the changed #Accessible.
 615  *         Note that context #Accessibles are not guaranteed to outlive
 616  *         event delivery, in which case this call may return %NULL
 617  *         even if the object existed at the time of dispatch.
 618  *
 619  * Returns: an #Accessible pointer representing the new table header.
 620  **/
 621 Accessible *
 622 AccessibleTableHeaderChangedEvent_getHeaderAccessible (const AccessibleEvent *e)
 623 {
 624   const InternalEvent *foo = (InternalEvent *) e;
 625   return (Accessible *) cspi_internal_event_get_object (foo);
 626 }
 627
 628
 629 /**
 630  * AccessibleTableCaptionChangedEvent_getCaptionString:
 631  * @e: a pointer to the #AccessibleEvent being queried.
 632  *
 633  * Queries an #AccessibleEvent of type
 634  *         "object:property-changed:accessible-table-caption-object"
 635  *         returning the text in the caption, if present.
 636  *
 637  * Returns: a UTF-8 text string indicating the text in the caption.
 638  **/
 639 char *
 640 AccessibleTableCaptionChangedEvent_getCaptionString (const AccessibleEvent *e)
 641 {
 642   const InternalEvent *foo = (InternalEvent *) e;
 643   /* TODO: check the event type. */
 644   return cspi_internal_event_get_text (foo);
 645 }
 646
 647 /**
 648  * AccessibleTableRowDescriptionChangedEvent_getDescriptionString:
 649  * @e: a pointer to the #AccessibleEvent being queried.
 650  *
 651  * Queries an #AccessibleEvent of type
 652  *         "object:property-changed:accessible-table-row-description"
 653  *         returning the new table row description.
 654  *
 655  * Returns: a UTF-8 text string representing the recently changed
 656  *         table row description
 657  **/
 658 char *
 659 AccessibleTableRowDescriptionChangedEvent_getDescriptionString (const AccessibleEvent *e)
 660 {
 661   const InternalEvent *foo = (InternalEvent *) e;
 662   /* TODO: check the event type. */
 663   return cspi_internal_event_get_text (foo);
 664 }
 665
 666 /**
 667  * AccessibleTableColumnDescriptionChangedEvent_getDescriptionString:
 668  * @e: a pointer to the #AccessibleEvent being queried.
 669  *
 670  * Queries an #AccessibleEvent of type
 671  *         "object:property-changed:accessible-table-column-description"
 672  *         returning the new table column description.
 673  *
 674  * Returns: a UTF-8 text string representing the recently changed
 675  *         table column description
 676  **/
 677 char *
 678 AccessibleTableColumnDescriptionChangedEvent_getDescriptionString (const AccessibleEvent *e)
 679 {
 680   const InternalEvent *foo = (InternalEvent *) e;
 681   /* TODO: check the event type. */
 682   return cspi_internal_event_get_text (foo);
 683 }
 684
 685 /**
 686  * AccessibleDescriptionChangedEvent_getDescriptionString:
 687  * @e: a pointer to the #AccessibleEvent being queried.
 688  *
 689  * Queries an #AccessibleEvent of type
 690  *         "object:property-changed:accessible-description"
 691  *         returning the new description.
 692  *
 693  * Returns: a UTF-8 text string representing the recently changed
 694  *         description
 695  **/
 696 char *
 697 AccessibleDescriptionChangedEvent_getDescriptionString (const AccessibleEvent *e)
 698 {
 699   const InternalEvent *foo = (InternalEvent *) e;
 700   /* TODO: check the event type. */
 701   return cspi_internal_event_get_text (foo);
 702 }
 703
 704 /**
 705  * AccessibleBoundsChangedEvent_getNewBounds:
 706  * @e: a pointer to the #AccessibleEvent being queried.
 707  *
 708  * Queries an #AccessibleEvent of type "object:bounds-changed",
 709  *         returning a pointer to an SPIRect structure containing the
 710  *         new bounds, or NULL on error.
 711  *         The returned structure should be freed with SPI_freeRect when
 712  *         the caller has finished referencing it.
 713  *
 714  * @Since: AT-SPI 1.6
 715  *
 716  * Returns: a pointer to an SPIRect defining the new object bounds.
 717  **/
 718 SPIRect *
 719 AccessibleBoundsChangedEvent_getNewBounds (const AccessibleEvent *e)
 720 {
 721   const InternalEvent *foo = (InternalEvent *) e;
 722   /* TODO: check the event type. */
 723   return cspi_internal_event_get_rect (foo);
 724 }
 725
 726 static gint
 727 cspi_event_compare (gconstpointer p1, gconstpointer p2)
 728 {
 729   const InternalEvent *e1 = p1, *e2 = p2;
 730   return (gint) ((long) e2->id  - (long) e1->id);
 731 }
 732
 733 static InternalEvent *
 734 cspi_internal_event_lookup (const InternalEvent *e)
 735 {
 736   InternalEvent *internal = NULL;
 737   GSList *p =
 738     g_slist_find_custom (_cspi_event_queue, e, cspi_event_compare);
 739   if (p)
 740     internal = p->data;
 741   return internal;
 742 }
 743
 744 static const InternalEvent *
 745 cspi_internal_event_check (const AccessibleEvent *e)
 746 {
 747   InternalEvent *internal = (InternalEvent *) e;
 748   if (internal->magic == SPI_INTERNAL_EVENT_MAGIC)
 749     return internal;
 750   else
 751     return NULL;
 752 }
 753
 754 static InternalEvent *
 755 cspi_internal_event_add (const InternalEvent *e)
 756 {
 757   _cspi_event_queue = g_slist_prepend (_cspi_event_queue, (gpointer) e);
 758   return (InternalEvent *) e;
 759 }
 760
 761 static void
 762 cspi_internal_event_remove (const InternalEvent *e)
 763 {
 764   GSList *link = g_slist_find_custom (_cspi_event_queue, e, cspi_event_compare);
 765   if (link)
 766     _cspi_event_queue = g_slist_remove_link (_cspi_event_queue, link);
 767 }
 768
 769 /**
 770  * AccessibleNameChangedEvent_getNameString:
 771  * @e: a pointer to the #AccessibleEvent being queried.
 772  *
 773  * Queries an #AccessibleEvent of type "object:property-change:accessible_name:",
 774  *         returning the name.
 775  *
 776  * Returns: a UTF-8 text string representing the name of the
 777  *         object which recently changed.
 778  **/
 779 char *
 780 AccessibleNameChangedEvent_getNameString (const AccessibleEvent *e)
 781 {
 782   const InternalEvent *foo = (InternalEvent *) e;
 783   return cspi_internal_event_get_text (foo);
 784 }
 785
 786 /**
 787  * AccessibleEvent_ref:
 788  * @e: a pointer to the #AccessibleEvent being referenced.
 789  *
 790  * Increments by 1 the reference count of the event
 791  *
 792  * Returns: TRUE if the function succeeded; FALSE if the pointer is not a
 793  *         valid event.
 794  **/
 795 SPIBoolean
 796 AccessibleEvent_ref (const AccessibleEvent *e)
 797 {
 798   const InternalEvent *private = cspi_internal_event_check (e);
 799   if (private)
 800     {
 801       InternalEvent *event = cspi_internal_event_lookup (private);
 802       /*
 803        * put event in the cache if it's not there already,
 804        * and increment refcount
 805        */
 806       if (!event)
 807         {
 808           event = cspi_internal_event_add (private);
 809         }
 810       event->ref_count++;
 811       return TRUE;
 812     }
 813   else
 814     return FALSE;
 815 }
 816
 817 /**
 818  * AccessibleEvent_unref:
 819  * @e: a pointer to the #AccessibleEvent being referenced.
 820  *
 821  * Decrements by 1 the reference count of the event. The event is destroyed
 822  * when the reference count recahes zero.
 823  *
 824  **/
 825 void
 826 AccessibleEvent_unref (const AccessibleEvent *e)
 827 {
 828   const InternalEvent *private = cspi_internal_event_check (e);
 829   /* decrement refcount and remove if appropriate */
 830   if (private)
 831     {
 832       InternalEvent *event = cspi_internal_event_lookup (private);
 833       if (event)
 834         {
 835           event->ref_count--;
 836           if (event->ref_count < 1)
 837             {
 838               cspi_internal_event_remove (event);
 839               g_free ((gpointer)e->type);
 840               Accessible_unref (e->source);
 841               if (event->event.v_type == EVENT_DATA_OBJECT)
 842                 {
 843                   Accessible_unref (event->event.v.accessible);
 844                 }
 845               g_free ((gpointer)e);
 846             }
 847         }
 848     }
 849 }
 850
 851 typedef struct
 852 {
 853   CSpiEventListener *listener;
 854   char *event;
 855   char *detail;
 856 } CSpiEventListenerEntry;
 857
 858 static GList *event_listeners = NULL;
 859
 860 static dbus_bool_t
 861 demarshal_rect (DBusMessageIter *iter, SPIRect *rect)
 862 {
 863   dbus_int32_t x, y, width, height;
 864   DBusMessageIter iter_struct;
 865
 866   dbus_message_iter_recurse (iter, &iter_struct);
 867   if (dbus_message_iter_get_arg_type (&iter_struct) != DBUS_TYPE_INT32) return FALSE;
 868   dbus_message_iter_get_basic (&iter_struct, &x);
 869   dbus_message_iter_next (&iter_struct);
 870   if (dbus_message_iter_get_arg_type (&iter_struct) != DBUS_TYPE_INT32) return FALSE;
 871   dbus_message_iter_get_basic (&iter_struct, &y);
 872   dbus_message_iter_next (&iter_struct);
 873   if (dbus_message_iter_get_arg_type (&iter_struct) != DBUS_TYPE_INT32) return FALSE;
 874   dbus_message_iter_get_basic (&iter_struct, &width);
 875   dbus_message_iter_next (&iter_struct);
 876   if (dbus_message_iter_get_arg_type (&iter_struct) != DBUS_TYPE_INT32) return FALSE;
 877   dbus_message_iter_get_basic (&iter_struct, &height);
 878   rect->x = x;
 879   rect->y = y;
 880   rect->width = width;
 881   rect->height = height;
 882   return TRUE;
 883 }
 884
 885 static gboolean
 886 parse_eventType (const char *eventType, char **type, char **detail, char **matchrule)
 887 {
 888   char *p, *q;
 889   char *t, *d;
 890
 891   p = strchr (eventType, ':');
 892   if (p) p = strchr (p + 1, ':');
 893   if (!p) p = eventType + strlen (eventType);
 894   t = g_malloc (p - eventType + 1);
 895   if (t)
 896   {
 897     memcpy (t, eventType, p - eventType);
 898     t[p - eventType] = '\0';
 899     if (!strchr (t, ':'))
 900     {
 901       char *q = g_strconcat (t, ":", NULL);
 902       if (1)
 903       {
 904         g_free (t);
 905         t = q;
 906       }
 907     }
 908   }
 909   else return FALSE;
 910   if (*p == ':')
 911   {
 912     d = g_strdup (p + 1);
 913     if (!d)
 914     {
 915       g_free (t);
 916       return FALSE;
 917     }
 918   }
 919   else d = NULL;
 920   if ((p = strchr (t, ':')))
 921   {
 922     *p = (p[1] == '\0'? '\0': '_');
 923   }
 924   while ((p = strchr (t, '-'))) *p = '_';
 925   if (matchrule)
 926   {
 927     *matchrule = g_strdup_printf ("type='signal',interface='%s',member='%s'", spi_interface_accessible, t);
 928     if (!*matchrule)
 929     {
 930       g_free (t);
 931       if (d) g_free (d);
 932       return FALSE;
 933     }
 934   }
 935   if (type) *type = t;
 936   if (detail) *detail = d;
 937   return TRUE;
 938 }
 939
 940 static void listener_data_free (CSpiEventListenerEntry *e)
 941 {
 942   g_free (e->event);
 943   if (e->detail) g_free (e->detail);
 944   g_free (e);
 945 }
 946
 947 /**
 948  * SPI_registerGlobalEventListener:
 949  * @listener: the #AccessibleEventListener to be registered against an
 950  *            event type.
 951  * @eventType: a character string indicating the type of events for which
 952  *            notification is requested.  Format is
 953  *            EventClass:major_type:minor_type:detail
 954  *            where all subfields other than EventClass are optional.
 955  *            EventClasses include "object", "window", "mouse",
 956  *            and toolkit events (e.g. "Gtk", "AWT").
 957  *            Examples: "focus:", "Gtk:GtkWidget:button_press_event".
 958  *
 959  * Legal object event types:
 960  *
 961  *    (property change events)
 962  *
 963  *            object:property-change
 964  *            object:property-change:accessible-name
 965  *            object:property-change:accessible-description
 966  *            object:property-change:accessible-parent
 967  *            object:property-change:accessible-value
 968  *            object:property-change:accessible-role
 969  *            object:property-change:accessible-table-caption
 970  *            object:property-change:accessible-table-column-description
 971  *            object:property-change:accessible-table-column-header
 972  *            object:property-change:accessible-table-row-description
 973  *            object:property-change:accessible-table-row-header
 974  *            object:property-change:accessible-table-summary
 975  *
 976  *    (other object events)
 977  *
 978  *            object:state-changed
 979  *            object:children-changed
 980  *            object:visible-data-changed
 981  *            object:selection-changed
 982  *            object:text-selection-changed
 983  *            object:text-changed
 984  *            object:text-caret-moved
 985  *            object:row-inserted
 986  *            object:row-reordered
 987  *            object:row-deleted
 988  *            object:column-inserted
 989  *            object:column-reordered
 990  *            object:column-deleted
 991  *            object:model-changed
 992  *            object:active-descendant-changed
 993  *
 994  *  (window events)
 995  *
 996  *            window:minimize
 997  *            window:maximize
 998  *            window:restore
 999  *            window:close
1000  *            window:create
1001  *            window:reparent
1002  *            window:desktop-create
1003  *            window:desktop-destroy
1004  *            window:activate
1005  *            window:deactivate
1006  *            window:raise
1007  *            window:lower
1008  *            window:move
1009  *            window:resize
1010  *            window:shade
1011  *            window:unshade
1012  *            window:restyle
1013  *
1014  *  (other events)
1015  *
1016  *            focus:
1017  *            mouse:abs
1018  *            mouse:rel
1019  *            mouse:b1p
1020  *            mouse:b1r
1021  *            mouse:b2p
1022  *            mouse:b2r
1023  *            mouse:b3p
1024  *            mouse:b3r
1025  *
1026  * NOTE: this string may be UTF-8, but should not contain byte value 56
1027  *            (ascii ':'), except as a delimiter, since non-UTF-8 string
1028  *            delimiting functions are used internally.
1029  *            In general, listening to
1030  *            toolkit-specific events is not recommended.
1031  *
1032  * Add an in-process callback function to an existing AccessibleEventListener.
1033  *
1034  * Returns: #TRUE if successful, otherwise #FALSE.
1035  **/
1036 SPIBoolean
1037 SPI_registerGlobalEventListener (AccessibleEventListener *listener,
1038                                  const char              *eventType)
1039 {
1040   CSpiEventListenerEntry *e;
1041   char *matchrule;
1042   DBusError error;
1043   GList *new_list;
1044
1045   if (!listener)
1046     {
1047       return FALSE;
1048     }
1049
1050   e = g_new (CSpiEventListenerEntry, 1);
1051   if (!e) return FALSE;
1052   e->listener = listener;
1053   if (!parse_eventType (eventType, &e->event, &e->detail, &matchrule))
1054   {
1055     g_free (e);
1056     return FALSE;
1057   }
1058   new_list = g_list_prepend (event_listeners, e);
1059   if (!new_list)
1060   {
1061     listener_data_free (e);
1062     return FALSE;
1063   }
1064   event_listeners = new_list;
1065   dbus_error_init (&error);
1066   dbus_bus_add_match (cspi_bus(), matchrule, &error);
1067   if (error.message)
1068   {
1069     g_warning ("Adding match: %s", error.message);
1070   }
1071   return TRUE;
1072 }
1073
1074 /**
1075  * SPI_deregisterGlobalEventListenerAll:
1076  * @listener: the #AccessibleEventListener to be registered against
1077  *            an event type.
1078  *
1079  * deregisters an AccessibleEventListener from the registry, for all
1080  *            event types it may be listening to. Use
1081  *            AccessibleEventListener_unref to release the
1082  *            listener reference.
1083  *
1084  * Returns: #TRUE if successful, otherwise #FALSE.
1085  **/
1086 SPIBoolean
1087 SPI_deregisterGlobalEventListenerAll (AccessibleEventListener *listener)
1088 {
1089   GList *l;
1090
1091   if (!listener)
1092     {
1093       return FALSE;
1094     }
1095
1096   for (l = event_listeners; l;)
1097   {
1098     CSpiEventListenerEntry *e = l->data;
1099     if (e->listener == listener)
1100     {
1101       listener_data_free (e);
1102       l = g_list_remove (l, e);
1103     }
1104     else l = g_list_next (l);
1105   }
1106   return TRUE;
1107 }
1108
1109 /**
1110  * SPI_deregisterGlobalEventListener:
1111  * @listener: the #AccessibleEventListener registered against an event type.
1112  * @eventType: a string specifying the event type for which this
1113  *             listener is to be deregistered.
1114  *
1115  * deregisters an AccessibleEventListener from the registry, for a specific
1116  *             event type.
1117  *
1118  * Returns: #TRUE if successful, otherwise #FALSE.
1119  **/
1120 SPIBoolean
1121 SPI_deregisterGlobalEventListener (AccessibleEventListener *listener,
1122                                    const char              *eventType)
1123 {
1124   char *type, *detail, *matchrule;
1125   GList *l;
1126
1127   if (!parse_eventType (eventType, &type, &detail, &matchrule))
1128   {
1129     return FALSE;
1130   }
1131   if (!listener)
1132     {
1133       return FALSE;
1134     }
1135
1136   for (l = event_listeners; l;)
1137   {
1138     CSpiEventListenerEntry *e = l->data;
1139     if (e->listener == listener && !strcmp (e->event, type) && (e->detail == detail || !strcmp (e->detail, detail)))
1140     {
1141       DBusError error;
1142       listener_data_free (e);
1143       l = g_list_remove (l, e);
1144       dbus_error_init (&error);
1145       dbus_bus_remove_match (cspi_bus(), matchrule, &error);
1146     }
1147     else l = g_list_next (l);
1148   }
1149   g_free (type);
1150   if (detail) g_free (detail);
1151   g_free (matchrule);
1152   return TRUE;
1153 }
1154
1155 void
1156 cspi_dispatch_event (AccessibleEvent *e)
1157 {
1158   char *event, *detail;
1159   GList *l;
1160
1161   if (!parse_eventType (e->type, &event, &detail, NULL))
1162   {
1163     g_warning ("Couldn't parse event: %s\n", e->type);
1164     return;
1165   }
1166   for (l = event_listeners; l; l = g_list_next (l))
1167   {
1168     CSpiEventListenerEntry *entry = l->data;
1169     if (!strcmp (event, entry->event) &&
1170         (entry->detail == NULL || !strcmp (detail, entry->detail)))
1171     {
1172       CSpiEventListenerClass *klass = CSPI_EVENT_LISTENER_GET_CLASS (entry->listener);
1173       if (klass->event) (*klass->event)(entry->listener, e);
1174     }
1175   }
1176   if (detail) g_free (detail);
1177   g_free (event);
1178 }
1179
1180 DBusHandlerResult
1181 cspi_dbus_handle_event (DBusConnection *bus, DBusMessage *message, void *data)
1182 {
1183   char *detail = NULL;
1184   const char *event = dbus_message_get_member (message);
1185   DBusMessageIter iter, iter_variant;
1186   dbus_message_iter_init (message, &iter);
1187   AccessibleEvent e;
1188   dbus_int32_t detail1, detail2;
1189   char *p;
1190
1191   g_return_if_fail (dbus_message_iter_get_arg_type (&iter) == DBUS_TYPE_STRING);
1192   dbus_message_iter_get_basic (&iter, &detail);
1193   dbus_message_iter_next (&iter);
1194   g_return_if_fail (dbus_message_iter_get_arg_type (&iter) == DBUS_TYPE_INT32);
1195   dbus_message_iter_get_basic (&iter, &detail1);
1196   e.detail1 = detail1;
1197   dbus_message_iter_next (&iter);
1198   g_return_if_fail (dbus_message_iter_get_arg_type (&iter) == DBUS_TYPE_INT32);
1199   dbus_message_iter_get_basic (&iter, &detail2);
1200   e.detail2 = detail2;
1201   dbus_message_iter_next (&iter);
1202   e.type = g_strdup (event);
1203   p = strchr (e.type, '_');
1204   if (p) *p = ':';
1205   if (detail[0] != '\0')
1206   {
1207     p = g_strconcat (e.type, ":", detail, NULL);
1208     if (p)
1209     {
1210       g_free (e.type);
1211       e.type = p;
1212     }
1213   }
1214     while ((p = strchr (e.type, '_'))) *p = '-';
1215   e.source = cspi_ref_accessible (dbus_message_get_sender(message), dbus_message_get_path(message));
1216   dbus_message_iter_recurse (&iter, &iter_variant);
1217   switch (dbus_message_iter_get_arg_type (&iter_variant))
1218   {
1219     case DBUS_TYPE_OBJECT_PATH:
1220     {
1221       dbus_message_iter_get_basic (&iter_variant, &p);
1222       e.v_type = EVENT_DATA_OBJECT;
1223       e.v.accessible = cspi_ref_accessible (dbus_message_get_sender(message), p);
1224       break;
1225     }
1226     case DBUS_TYPE_STRING:
1227     {
1228       dbus_message_iter_get_basic (&iter_variant, &p);
1229       e.v_type = EVENT_DATA_STRING;
1230       e.v.text = g_strdup (p);
1231       break;
1232     }
1233     case DBUS_TYPE_STRUCT:
1234     {
1235       if (demarshal_rect (&iter_variant, &e.v.rect))
1236       {
1237         e.v_type = EVENT_DATA_RECT;
1238       }
1239       break;
1240     }
1241   default:
1242     break;
1243   }
1244   cspi_dispatch_event (&e);
1245   return DBUS_HANDLER_RESULT_HANDLED;
1246 }