From dead958cca32d5754346e78e56f06c9ae2e90e10 Mon Sep 17 00:00:00 2001
From: billh <billh@e2bd861d-eb25-0410-b326-f6ed22b6b98c>
Date: Mon, 27 Mar 2006 18:05:32 +0000
Subject: Strip symbols that should not be exported; add "Since" tag to at-spi
 cspi method docs, and clean up gtk-doc stuff generally. All that's missing
 now are the short and long descriptions in cspi gtk-doc documentation.  Bug
 #313186.

git-svn-id: http://svn.gnome.org/svn/at-spi/trunk@803 e2bd861d-eb25-0410-b326-f6ed22b6b98c
---
 cspi/spi-listener.h | 70 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 63 insertions(+), 7 deletions(-)

(limited to 'cspi/spi-listener.h')

diff --git a/cspi/spi-listener.h b/cspi/spi-listener.h
index aff3762..364d4e3 100644
--- a/cspi/spi-listener.h
+++ b/cspi/spi-listener.h
@@ -30,9 +30,18 @@
 extern "C" {
 #endif
 
-/*
- * Structure used to encapsulate event information
- */
+/**
+ * AccessibleEvent:
+ * @type: a string representing the type of the event, with increasing specificity
+ * from left to right, delimited by colons.  Leftmost token represents event source type,
+ * next token represents event category, and next token represents the subcategory
+ * of the event, for instance the specific property, state, or attribute being notified.
+ * @source: The #Accessible from which the event originated.
+ * @detail1: an event-type-specific integer value.
+ * @detail2: an event-type-specific integer value.
+ *
+ * A structure used to encapsulate event information.
+ **/
 typedef struct {
   const char  *type;
   Accessible  *source;
@@ -42,10 +51,11 @@ typedef struct {
   
 /**
  *AccessibleDeviceEventType:
- *@SPI_KEY_PRESSED:
- *@SPI_KEY_RELEASED:
- *@SPI_BUTTON_PRESSED:
- *@SPI_BUTTON_RELEASED:
+ *@SPI_KEY_PRESSED: A device key has been pressed.
+ *@SPI_KEY_RELEASED: A device key has been released.
+ *@SPI_BUTTON_PRESSED: A device button or switch (other than a keyboard key) 
+ * has been pressed.
+ *@SPI_BUTTON_RELEASED: A device button or switch has been released.
  *
  *The type of an AccessibleDeviceEvent.
  **/
@@ -63,6 +73,21 @@ typedef enum {
  **/
 typedef AccessibleDeviceEventType AccessibleKeyEventType;
 
+/**
+ * AccessibleDeviceEvent:
+ * @keyID: Symbolic representation for the key or switch generating the event, e.g. keysym or button number.
+ * @keystring: A symbolic name for the key or switch, or, if is_text is true, a string approximating the
+ * inserted text characters which would result from this event, if a text entry field has keyboard focus.
+ * @timestamp: A time in ms when this event occurred, relative to some unspecified starting point.  
+ * Timestamp values should therefore be used to compare events but should not be tested against a 
+ * fixed time.
+ * @type: The #AccessibleDeviceEventType identifying the specific type of event.
+ * @is_text: A boolean value indicating whether the event represents 'printable' text (i.e. whether it
+ * changes the current insertion buffer of a focussed text entry component or not).  Whitespace
+ * is considered "printable" in this context, since it typically inserts characters into the buffer.
+ *
+ * A structure encapsulating information relevant to a device event notification.
+ **/
 typedef struct {
   long                   keyID;
   short                  keycode;
@@ -86,10 +111,41 @@ typedef AccessibleDeviceEvent AccessibleKeystroke;
  * Note that AccessibleKeystrokeListeners may consume the event received
  * if one of their callbacks returns TRUE (see SPI_registerAccessibleKeystrokeListener)
  */
+
+/**
+ * AccessibleEventListenerCB:
+ * @event: The event for which notification is sent.
+ * @user_data: User data which is passed to the callback each time a notification takes place.
+ *
+ * A function prototype for callbacks via which clients are notified of AT-SPI events.
+ * 
+ **/
 typedef void       (*AccessibleEventListenerCB)     (const AccessibleEvent     *event,
 						     void                      *user_data);
+/**
+ * AccessibleKeystrokeListenerCB:
+ * @stroke: the #AccessibleKeystroke event for which notification is taking place.
+ * @user_data: data passed to the callback each time it is notified, according to the data
+ * which was passed in when the listener/callback was registered.
+ *
+ * A function prototype for a callback function called when a key event notification takes place.
+ *
+ * Returns: %TRUE if the client wishes to consume the event and prevent its
+ * dispatch to other listeners or the currently focussed application, if
+ * the relevant callback was registered with the #SPI_KEYLISTENER_CANCONSUME flag.
+ **/
 typedef SPIBoolean (*AccessibleKeystrokeListenerCB) (const AccessibleKeystroke *stroke,
 						     void                      *user_data);
+/**
+ * AccessibleDeviceListenerCB:
+ * @stroke: The #AccessibleDeviceEvent for which notification is being received.
+ * @user_data: Data which is passed to the client each time this callback is notified.
+ *
+ * A callback function prototype via which clients receive device event notifications.
+ *
+ * Returns: %TRUE if the client wishes to consume/preempt the event, preventing it from being
+ * relayed to the currently focussed application, %FALSE if the event delivery should proceed as normal.
+ **/
 typedef SPIBoolean (*AccessibleDeviceListenerCB)    (const AccessibleDeviceEvent *stroke,
 						     void                      *user_data);
 
-- 
cgit v1.2.1