Small documentation improvements for key listener API.

git-svn-id: http://svn.gnome.org/svn/at-spi/trunk@542 e2bd861d-eb25-0410-b326-f6ed22b6b98c

diff --git a/ChangeLog b/ChangeLog
index 1241a6c..c2470b3 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2003-09-04  Bill Haneman <billh@gnome.org>
+
+       * cspi/spi_event.c: Documentation improvements for
+       (SPI_registerAccessibleKeylistener).
+
+       * docs/reference/tmpl/spi_registry.sgml:
+       Documentation improvements for SpiAccessibleKeylistenerCB.
+

 2003-09-02  Mugurel Tudor  <mugurelu@go.ro>
 
        * configure.in: Added "ro" to ALL_LINGUAS.
 2003-09-02  Mugurel Tudor  <mugurelu@go.ro>
 
        * configure.in: Added "ro" to ALL_LINGUAS.

diff --git a/cspi/spi-listener.h b/cspi/spi-listener.h
index f692788..aff3762 100644 (file)
--- a/cspi/spi-listener.h
+++ b/cspi/spi-listener.h
@@ -83,6 +83,8 @@ typedef AccessibleDeviceEvent AccessibleKeystroke;
  * void (*AccessibleEventListenerCB) (AccessibleEvent *event);
  *
  * SPIBoolean (*AccessibleKeystrokeListenerCB) (AccessibleKeystrokeEvent *Event);
  * void (*AccessibleEventListenerCB) (AccessibleEvent *event);
  *
  * SPIBoolean (*AccessibleKeystrokeListenerCB) (AccessibleKeystrokeEvent *Event);

+ * Note that AccessibleKeystrokeListeners may consume the event received
+ * if one of their callbacks returns TRUE (see SPI_registerAccessibleKeystrokeListener)

  */
 typedef void       (*AccessibleEventListenerCB)     (const AccessibleEvent     *event,
                                                     void                      *user_data);
  */
 typedef void       (*AccessibleEventListenerCB)     (const AccessibleEvent     *event,
                                                     void                      *user_data);

diff --git a/cspi/spi_registry.c b/cspi/spi_registry.c
index 102140d..77341a9 100644 (file)
--- a/cspi/spi_registry.c
+++ b/cspi/spi_registry.c
@@ -321,9 +321,12 @@ SPI_freeDesktopList (Accessible **desktop_list)
  *             the behavior of the notification/listener transaction.
  *             
  * Register a listener for keystroke events, either pre-emptively for
  *             the behavior of the notification/listener transaction.
  *             
  * Register a listener for keystroke events, either pre-emptively for

- *             all windows (SPI_KEYLISTENER_ALL_WINDOWS), or
- *             non-preemptively (SPI_KEYLISTENER_NOSYNC).
- *             ( Other sync_type values may be available in the future.)
+ *             all windows (SPI_KEYLISTENER_ALL_WINDOWS),
+ *             non-preemptively (SPI_KEYLISTENER_NOSYNC), or
+ *             pre-emptively at the toolkit level (SPI_KEYLISTENER_CANCONSUME).
+ *             If ALL_WINDOWS or CANCONSUME are used, the event is consumed
+ *             upon receipt if one of @listener's callbacks returns #TRUE.
+ *             ( Other sync_type values may be available in the future )

  *
  * Returns: #TRUE if successful, otherwise #FALSE.
  **/
  *
  * Returns: #TRUE if successful, otherwise #FALSE.
  **/

diff --git a/docs/reference/cspi/tmpl/spi_registry.sgml b/docs/reference/cspi/tmpl/spi_registry.sgml
index c84a259..5fcd339 100644 (file)
--- a/docs/reference/cspi/tmpl/spi_registry.sgml
+++ b/docs/reference/cspi/tmpl/spi_registry.sgml
@@ -65,6 +65,10 @@ Registry queries
 <para>
 This is a function which is specified when creating a KeystrokeListener.
 It is called when an event being listened for occurs. 
 <para>
 This is a function which is specified when creating a KeystrokeListener.
 It is called when an event being listened for occurs. 

+If it returns TRUE, this indicates that the event should be consumed 
+rather than passed through; only callbacks whose listeners are
+registered with the SPI_KEYLISTENER_ALL_WINDOWS or 
+SPI_KEYLISTENER_CANCONSUME flags can be consumed.

 </para>
 
 @stroke: 
 </para>
 
 @stroke: