Added accessor API for events.
[platform/core/uifw/at-spi2-atk.git] / 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 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 #include <cspi/spi-private.h>
25 #include <cspi/bonobo/cspi-bonobo-listener.h>
26
27 /**
28  * SPI_freeAccessibleKeySet:
29  * @keyset: An AccessibleKeyset to free.
30  *
31  * Release the memory used by an AccessibleKeySet.
32  *
33  **/
34 void
35 SPI_freeAccessibleKeySet (AccessibleKeySet *keyset)
36 {
37   int i = 0;    
38   g_free (keyset->keysyms);
39   g_free (keyset->keycodes);
40   while (keyset->keystrings [i])
41     {
42       g_free (keyset->keystrings [i++]);
43     }
44   g_free (keyset->keystrings);
45   g_free (keyset);
46 }
47
48 /**
49  * SPI_createAccessibleKeySet:
50  * @len: the number of key values in the key set.
51  * @keysyms: a UTF-8 string containing symbolic key values to be matched, or NULL if
52  *           matching is performed against other key values instead.
53  * @keycodes: an array of unsigned short values which are the hardware keycodes
54  *           to be matched, or NULL if the keyset is specified solely by keysyms
55  *           and/or keystrings.
56  * @keystrings: an array of null-terminated character strings which specify key
57  *             name values to match, or NULL if the keyset is specified solely by
58  *             keycodes and/or keysyms.
59  *
60  * Create a new #AccessibleKeySet of a specified length.
61  * A KeySet is used typically to match key event values, and a matches are made
62  * using the following criteria: a match exists with a key event if all non-null
63  * i-th members of the keyset match the key event.
64  * If both keystring and keysym values are NULL, a keycode value match is
65  * forced, thus the match for keysym=0, keycode=0, keystring=NULL is
66  * keycode 0.
67  *
68  * Returns: a pointer to a newly-created #AccessibleKeySet.
69  *
70  **/
71 AccessibleKeySet *
72 SPI_createAccessibleKeySet (int len, const char *keysyms, short *keycodes,
73                             const char **keystrings)
74 {
75   AccessibleKeySet *keyset = g_new0 (AccessibleKeySet, 1);
76   int i, keysym_len = 0;
77   const char *keysym_ptr = keysyms;
78   keyset->len = len;
79   keyset->keysyms = g_new0 (unsigned long, len);
80   keyset->keycodes = g_new0 (unsigned short, len);
81   keyset->keystrings = g_new0 (char *, len);
82   if (keysyms)
83     {
84       keysym_len = g_utf8_strlen (keysyms, -1);
85     }
86   for (i = 0; i < len; ++i)
87     {
88       if (i < keysym_len)
89         {
90           keyset->keysyms [i] = (unsigned long) g_utf8_get_char (keysym_ptr);
91           keysym_ptr = g_utf8_find_next_char (keysym_ptr, NULL);
92         }
93       else
94         {
95           keyset->keysyms [i] = 0;
96         }
97       if (keycodes)
98         {
99           keyset->keycodes [i] = keycodes [i];
100         }
101       if (keystrings)
102         {
103           keyset->keystrings [i] = g_strdup (keystrings [i]);
104         }
105     }
106   return keyset;        
107 }
108
109 /**
110  * SPI_createAccessibleEventListener:
111  * @callback : an #AccessibleEventListenerCB callback function, or NULL.
112  * @user_data: a pointer to data which will be passed to the callback when invoked.
113  *
114  * Create a new #AccessibleEventListener with a specified (in-process) callback function.
115  *
116  * Returns: a pointer to a newly-created #AccessibleEventListener.
117  *
118  **/
119 AccessibleEventListener *
120 SPI_createAccessibleEventListener (AccessibleEventListenerCB callback,
121                                    void                     *user_data)
122 {
123   AccessibleEventListener *listener = cspi_event_listener_new ();
124   if (callback)
125     {
126       AccessibleEventListener_addCallback (listener, callback, user_data);
127     }
128   return listener;
129 }
130
131 /**
132  * AccessibleEventListener_addCallback:
133  * @listener: the #AccessibleEventListener instance to modify.
134  * @callback: an #AccessibleEventListenerCB function pointer.
135  * @user_data: a pointer to data which will be passed to the callback when invoked.
136  *
137  * Add an in-process callback function to an existing AccessibleEventListener.
138  * Note that the callback function must live in the same address
139  * space as the AccessibleEventListener implementation code, thus one should not
140  * use this function to attach callbacks to a 'remote' event listener
141  * (that is, one that was not created by a client call to
142  * createAccessibleEventListener ();
143  *
144  * Returns: #TRUE if successful, otherwise #FALSE.
145  *
146  **/
147 SPIBoolean
148 AccessibleEventListener_addCallback (AccessibleEventListener *listener,
149                                      AccessibleEventListenerCB callback,
150                                      void                     *user_data)
151 {
152   cspi_event_listener_add_cb (listener, callback, user_data);
153   return TRUE;
154 }
155
156 /**
157  * AccessibleEventListener_unref:
158  * @listener: a pointer to the #AccessibleEventListener being operated on.
159  *
160  * Decrements an #AccessibleEventListener's reference count.
161  **/
162 void
163 AccessibleEventListener_unref (AccessibleEventListener *listener)
164 {
165   cspi_event_listener_unref (listener);
166 }
167
168 /**
169  * AccessibleEventListener_removeCallback:
170  * @listener: the #AccessibleEventListener instance to modify.
171  * @callback: an #AccessibleEventListenerCB function pointer.
172  *
173  * Remove an in-process callback function from an existing AccessibleEventListener.
174  *
175  * Returns: #TRUE if successful, otherwise #FALSE.
176  *
177  **/
178 SPIBoolean
179 AccessibleEventListener_removeCallback (AccessibleEventListener  *listener,
180                                         AccessibleEventListenerCB callback)
181 {
182   cspi_event_listener_remove_cb (listener, callback);
183   return TRUE;
184 }
185
186 /**
187  * SPI_createAccessibleKeystrokeListener:
188  * @callback : an #AccessibleKeystrokeListenerCB callback function, or NULL.
189  * @user_data: a pointer to data which will be passed to the callback when invoked.
190  *
191  * Create a new #AccessibleKeystrokeListener with a specified callback function.
192  *
193  * Returns: a pointer to a newly-created #AccessibleKeystrokeListener.
194  *
195  **/
196 AccessibleKeystrokeListener *
197 SPI_createAccessibleKeystrokeListener (AccessibleKeystrokeListenerCB callback,
198                                        void                         *user_data)
199 {
200   AccessibleDeviceListener *listener = cspi_device_listener_new ();
201   if (callback)
202     {
203       AccessibleDeviceListener_addCallback (listener, callback, user_data);
204     }
205   return listener;
206 }
207
208 /**
209  * AccessibleKeystrokeListener_addCallback:
210  * @listener: the #AccessibleKeystrokeListener instance to modify.
211  * @callback: an #AccessibleKeystrokeListenerCB function pointer.
212  * @user_data: a pointer to data which will be passed to the callback when invoked.
213  *
214  * Add an in-process callback function to an existing #AccessibleKeystrokeListener.
215  *
216  * Returns: #TRUE if successful, otherwise #FALSE.
217  *
218  **/
219 SPIBoolean
220 AccessibleKeystrokeListener_addCallback (AccessibleKeystrokeListener *listener,
221                                          AccessibleKeystrokeListenerCB callback,
222                                          void                         *user_data)
223 {
224   cspi_device_listener_add_cb (listener, callback, user_data);
225   return TRUE;
226 }
227
228 /**
229  * AccessibleKeystrokeListener_removeCallback:
230  * @listener: the #AccessibleKeystrokeListener instance to modify.
231  * @callback: an #AccessibleKeystrokeListenerCB function pointer.
232  *
233  * Remove an in-process callback function from an existing #AccessibleKeystrokeListener.
234  *
235  * Returns: #TRUE if successful, otherwise #FALSE.
236  *
237  **/
238 SPIBoolean
239 AccessibleKeystrokeListener_removeCallback (AccessibleKeystrokeListener *listener,
240                                             AccessibleKeystrokeListenerCB callback)
241 {
242   cspi_device_listener_remove_cb (listener, callback);
243   return TRUE;
244 }
245
246 /**
247  * AccessibleKeystrokeListener_unref:
248  * @listener: a pointer to the #AccessibleKeystrokeListener being operated on.
249  *
250  * Decrements an #AccessibleKeystrokeListener's reference count.
251  **/
252 void
253 AccessibleKeystrokeListener_unref (AccessibleKeystrokeListener *listener)
254 {
255   cspi_device_listener_unref (listener);
256 }
257
258 /**
259  * SPI_createAccessibleDeviceListener:
260  * @callback : an #AccessibleDeviceListenerCB callback function, or NULL.
261  * @user_data: a pointer to data which will be passed to the callback when invoked.
262  *
263  * Create a new #AccessibleDeviceListener with a specified callback function.
264  *
265  * Returns: a pointer to a newly-created #AccessibleDeviceListener.
266  *
267  **/
268 AccessibleDeviceListener *
269 SPI_createAccessibleDeviceListener (AccessibleDeviceListenerCB callback,
270                                        void                         *user_data)
271 {
272   AccessibleDeviceListener *listener = cspi_device_listener_new ();
273   if (callback)
274     {
275       AccessibleDeviceListener_addCallback (listener, callback, user_data);
276     }
277   return listener;
278 }
279
280 /**
281  * AccessibleDeviceListener_addCallback:
282  * @listener: the #AccessibleDeviceListener instance to modify.
283  * @callback: an #AccessibleDeviceListenerCB function pointer.
284  * @user_data: a pointer to data which will be passed to the callback when invoked.
285  *
286  * Add an in-process callback function to an existing #AccessibleDeviceListener.
287  *
288  * Returns: #TRUE if successful, otherwise #FALSE.
289  *
290  **/
291 SPIBoolean
292 AccessibleDeviceListener_addCallback (AccessibleDeviceListener *listener,
293                                          AccessibleDeviceListenerCB callback,
294                                          void                         *user_data)
295 {
296   cspi_device_listener_add_cb (listener, callback, user_data);
297   return TRUE;
298 }
299
300 /**
301  * AccessibleDeviceListener_removeCallback:
302  * @listener: the #AccessibleDeviceListener instance to modify.
303  * @callback: an #AccessibleDeviceListenerCB function pointer.
304  *
305  * Remove an in-process callback function from an existing #AccessibleDeviceListener.
306  *
307  * Returns: #TRUE if successful, otherwise #FALSE.
308  *
309  **/
310 SPIBoolean
311 AccessibleDeviceListener_removeCallback (AccessibleDeviceListener *listener,
312                                             AccessibleDeviceListenerCB callback)
313 {
314   cspi_device_listener_remove_cb (listener, callback);
315   return TRUE;
316 }
317
318 /**
319  * AccessibleDeviceListener_unref:
320  * @listener: a pointer to the #AccessibleDeviceListener being operated on.
321  *
322  * Decrements an #AccessibleDeviceListener's reference count.
323  **/
324 void
325 AccessibleDeviceListener_unref (AccessibleDeviceListener *listener)
326 {
327   cspi_device_listener_unref (listener);
328 }
329
330 static char *
331 cspi_internal_event_get_text (const InternalEvent *e)
332 {
333   CORBA_any *any;
334   g_return_val_if_fail (e, NULL);
335   g_return_val_if_fail (e->data, NULL);
336   any = (CORBA_any *) e->data;
337   if (CORBA_TypeCode_equivalent (any->_type, TC_CORBA_string, NULL)) 
338     {
339       return * (char **) any->_value;
340     } 
341   else
342     {
343 #ifdef EVENT_CONTEXT_DEBUG
344       fprintf (stderr, "requested string, TC is not TC_CORBA_string! (%u)\n",
345                (unsigned) any->_type);
346 #endif
347       return NULL;
348     }
349 }
350
351 static Accessible *
352 cspi_internal_event_get_object (const InternalEvent *e)
353 {
354   CORBA_any *any;
355   g_return_val_if_fail (e, NULL);
356   g_return_val_if_fail (e->data, NULL);
357   any = (CORBA_any *) e->data;
358   if (any->_type == TC_CORBA_Object) 
359     return cspi_object_add (* (CORBA_Object *) any->_value);
360   else 
361     return NULL;
362 }
363
364 /**
365  * AccessibleTextChangedEvent_getChangeString:
366  * @event: a pointer to the #AccessibleEvent being queried.
367  *
368  * Queries an #AccessibleEvent of type "object:text-changed", 
369  *         returning the text inserted or deleted.
370  *
371  * Returns: a UTF-8 text string indicating the text inserted,
372  *          deleted, or substituted by this event.
373  **/
374 char *
375 AccessibleTextChangedEvent_getChangeString (const AccessibleEvent *e)
376 {
377   const InternalEvent *foo = (InternalEvent *) e;
378   /* TODO: check the event type? expensive... */
379   return cspi_internal_event_get_text (foo);
380 }
381
382 /**
383  * AccessibleTextSelectionChangedEvent_getSelectionString:
384  * @event: a pointer to the #AccessibleEvent being queried.
385  *
386  * Queries an #AccessibleEvent of type "object:text-selection-changed", 
387  *         returning the newly added, removed, or modified selection string.
388  *
389  * Returns: a UTF-8 text string indicating the recently changed selection.
390  **/
391 char *
392 AccessibleTextSelectionChangedEvent_getSelectionString (const AccessibleEvent *e)
393 {
394   const InternalEvent *foo = (InternalEvent *) e;
395   /* TODO: check the event type? expensive... */
396   return cspi_internal_event_get_text (foo);
397 }
398
399 /**
400  * AccessibleWindowEvent_getTitleString:
401  * @event: a pointer to the #AccessibleEvent being queried.
402  *
403  * Queries an #AccessibleEvent of type "window:", 
404  *         returning the window title.
405  *
406  * Returns: a UTF-8 text string representing the title of the 
407  *         recently changed window.
408  **/
409 char *
410 AccessibleWindowEvent_getTitleString (const AccessibleEvent *e)
411 {
412   const InternalEvent *foo = (InternalEvent *) e;
413   /* TODO: check the event type? expensive... */
414   return cspi_internal_event_get_text (foo);
415 }
416
417 /**
418  * AccessibleChildChangedEvent_getChildAccessible:
419  * @event: a pointer to the #AccessibleEvent being queried.
420  *
421  * Queries an #AccessibleEvent of type "object:children_changed"
422  *         to get a reference to the changed #Accessible.
423  *         Note that context #Accessibles are not guaranteed to outlive
424  *         event delivery, in which case this call may return %NULL
425  *         even if the object existed at the time of dispatch.
426  *
427  * Returns: the context #Accessible for the event, or %NULL if
428  *          there is no longer a valid context #Accessible 
429  *          object for the event.
430  **/
431 Accessible *
432 AccessibleChildChangedEvent_getChildAccessible (const AccessibleEvent *e)
433 {
434   const InternalEvent *foo = (InternalEvent *) e;
435   return (Accessible *) cspi_internal_event_get_object (foo);
436 }
437
438 /**
439  * AccessibleParentChangedEvent_getParentAccessible:
440  * @event: a pointer to the #AccessibleEvent being queried.
441  *
442  * Queries an #AccessibleEvent of type "object:parent_changed"
443  *         to get a reference to the changed #Accessible.
444  *         Note that context #Accessibles are not guaranteed to outlive
445  *         event delivery, in which case this call may return %NULL
446  *         even if the object existed at the time of dispatch.
447  *
448  * Returns: an #Accessible pointer representing the new parent object.
449  **/
450 Accessible *
451 AccessibleParentChangedEvent_getParentAccessible (const AccessibleEvent *e)
452 {
453   const InternalEvent *foo = (InternalEvent *) e;
454   return (Accessible *) cspi_internal_event_get_object (foo);
455 }
456
457 /** NEED TO DOCUMENT THESE **/
458
459 Accessible *
460 AccessibleActiveDescendantChangedEvent_getActiveDescendant (const AccessibleEvent *e) 
461 {
462   const InternalEvent *foo = (InternalEvent *) e;
463   return (Accessible *) cspi_internal_event_get_object (foo);
464 }
465
466 Accessible *
467 AccessibleTableSummaryChangedEvent_getSummaryAccessible (const AccessibleEvent *e) 
468 {
469   const InternalEvent *foo = (InternalEvent *) e;
470   return (Accessible *) cspi_internal_event_get_object (foo);
471 }
472
473 Accessible *
474 AccessibleTableHeaderChangedEvent_getHeaderAccessible (const AccessibleEvent *e)
475 {
476   return NULL;
477 }
478
479
480 char *
481 AccessibleTableCaptionChangedEvent_getCaptionString (const AccessibleEvent *e)
482 {
483   return NULL;
484 }
485
486 char *
487 AccessibleTableRowDescriptionChangedEvent_getDescriptionString (const AccessibleEvent *e)
488 {
489   return NULL;
490 }
491
492 char *
493 AccessibleTableColumnDescriptionChangedEvent_getDescriptionString (const AccessibleEvent *e)
494 {
495   return NULL;
496 }
497
498 char *
499 AccessibleDescriptionChangedEvent_getDescriptionString (const AccessibleEvent *e)
500 {
501   return NULL;
502 }
503
504 char *
505 AccessibleNameChangedEvent_getNameString (const AccessibleEvent *e)
506 {
507   return NULL;
508 }
509