From dead958cca32d5754346e78e56f06c9ae2e90e10 Mon Sep 17 00:00:00 2001 From: billh Date: Mon, 27 Mar 2006 18:05:32 +0000 Subject: [PATCH] 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 --- ChangeLog | 15 +++ configure.in | 5 + cspi/Makefile.am | 2 +- cspi/bonobo/cspi-bonobo.c | 2 +- cspi/spi-impl.h | 8 ++ cspi/spi-listener.h | 70 ++++++++++++-- cspi/spi.h | 132 ++++++++++++++++++++------ cspi/spi_accessible.c | 12 ++- cspi/spi_application.c | 4 + cspi/spi_component.c | 6 +- cspi/spi_event.c | 19 ++-- cspi/spi_image.c | 6 +- cspi/spi_main.c | 66 +++++++++++-- cspi/spi_streamablecontent.c | 26 ++++- cspi/spi_table.c | 16 ++-- cspi/spi_text.c | 7 ++ docs/reference/cspi/at-spi-cspi-sections.txt | 32 +++++++ docs/reference/cspi/tmpl/spi_accessible.sgml | 33 ++++++- docs/reference/cspi/tmpl/spi_application.sgml | 10 ++ docs/reference/cspi/tmpl/spi_component.sgml | 9 ++ docs/reference/cspi/tmpl/spi_event.sgml | 48 ++++++++++ docs/reference/cspi/tmpl/spi_image.sgml | 9 ++ docs/reference/cspi/tmpl/spi_main.sgml | 112 ++++++++++++++++++++++ docs/reference/cspi/tmpl/spi_table.sgml | 40 ++++++++ docs/reference/cspi/tmpl/spi_text.sgml | 19 ++++ 25 files changed, 636 insertions(+), 72 deletions(-) diff --git a/ChangeLog b/ChangeLog index de5ccdb..3f27b6c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,20 @@ 2006-03-27 Bill Haneman + * configure.in: Define $LIBTOOL_EXPORT_OPTIONS + to strip "cspi_*" from the symbol table. + + * cspi/spi_streamablecontent.c: + (get_streams): Make this method static. + + * cspi/spi_main.c: + (_cspi_exception_throw): rename to cspi_exception_throw, + so we can strip it with the rest... + + * cspi/Makefile.am: + Add LIBTOOL_EXPORT_OPTIONS to libcspi_la_LDFLAGS. + +2006-03-27 Bill Haneman + Add doxygen-generated IDL docs to tarball, and enable doxygen during build/install when available. Bug #301345. diff --git a/configure.in b/configure.in index d30f075..5baffe6 100644 --- a/configure.in +++ b/configure.in @@ -199,6 +199,11 @@ AC_TRY_CPP([#include You can download the latest version from ftp://ftp.rpm.org/pub/rpm/dist/rpm-4.0.x/]) ]) +#libtool option to strip symbols starting with cspi +# +LIBTOOL_EXPORT_OPTIONS='-export-symbols-regex "^[[^cspi]].*"' +AC_SUBST(LIBTOOL_EXPORT_OPTIONS) + REBUILD=\# if test "x$enable_rebuilds" = "xyes" && \ test -n "$PERL" && \ diff --git a/cspi/Makefile.am b/cspi/Makefile.am index e34da2b..13fd8ac 100644 --- a/cspi/Makefile.am +++ b/cspi/Makefile.am @@ -9,7 +9,7 @@ INCLUDES = -I $(top_srcdir) \ $(X_CFLAGS) \ $(LIBCSPI_CFLAGS) -libcspi_la_LDFLAGS = @LDFLAGS@ ../libspi/libspi.la $(LIBCSPI_LIBS) @LT_VERSION_INFO@ +libcspi_la_LDFLAGS = @LDFLAGS@ ../libspi/libspi.la $(LIBCSPI_LIBS) @LT_VERSION_INFO@ @LIBTOOL_EXPORT_OPTIONS@ LDADD = \ $(top_srcdir)/libspi/libspi.la \ diff --git a/cspi/bonobo/cspi-bonobo.c b/cspi/bonobo/cspi-bonobo.c index 0ab14a8..8f6bb1e 100644 --- a/cspi/bonobo/cspi-bonobo.c +++ b/cspi/bonobo/cspi-bonobo.c @@ -49,7 +49,7 @@ cspi_check_ev (const char *error_string) err = bonobo_exception_get_text (ev); - if (!_cspi_exception_throw (ev, (char *) error_string)) { + if (!cspi_exception_throw (ev, (char *) error_string)) { fprintf (stderr, "Warning: AT-SPI error: %s: %s\n", error_string, err); } diff --git a/cspi/spi-impl.h b/cspi/spi-impl.h index a81a821..829c6c3 100644 --- a/cspi/spi-impl.h +++ b/cspi/spi-impl.h @@ -49,6 +49,14 @@ typedef Accessible AccessibleText; typedef Accessible AccessibleValue; typedef Accessible AccessibilityRegistry; +/** + * AccessibleStateSet: + * @ref_count: private + * @states: private + * + * An opaque structure representing an accessible object's state, + * which can then be queried via AccessibleStateSet APIs. + **/ typedef void AccessibleStateSet; typedef void AccessibleEventListener; typedef void AccessibleKeystrokeListener; 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); diff --git a/cspi/spi.h b/cspi/spi.h index 6054f2f..994efa2 100644 --- a/cspi/spi.h +++ b/cspi/spi.h @@ -44,17 +44,24 @@ extern "C" { /** *AccessibleTextBoundaryType: - *@SPI_TEXT_BOUNDARY_CHAR: - *@SPI_TEXT_BOUNDARY_CURSOR_POS: - *@SPI_TEXT_BOUNDARY_WORD_START: - *@SPI_TEXT_BOUNDARY_WORD_END: - *@SPI_TEXT_BOUNDARY_SENTENCE_START: - *@SPI_TEXT_BOUNDARY_SENTENCE_END: - *@SPI_TEXT_BOUNDARY_LINE_START: - *@SPI_TEXT_BOUNDARY_LINE_END: - *@SPI_TEXT_BOUNDARY_ATTRIBUTE_RANGE: + *@SPI_TEXT_BOUNDARY_CHAR: Delimiter is the current character's bounds. + *@SPI_TEXT_BOUNDARY_CURSOR_POS: Delimiter is the current text caret position. + *@SPI_TEXT_BOUNDARY_WORD_START: Bounds run from the first character of a word to the first + * character of the following word (i.e. including trailing whitespace, if any) within the text object. + *@SPI_TEXT_BOUNDARY_WORD_END: Bounds run from the last character of a word to the last + * character of the following word (i.e. including leading whitespace) within the text object. + *@SPI_TEXT_BOUNDARY_SENTENCE_START: Bounds run from the first character of a sentence to the first + * character of the next sentence in the text object. + *@SPI_TEXT_BOUNDARY_SENTENCE_END: Bounds run from the last character of a sentence to the last + * character of the next sentence in the text object. + *@SPI_TEXT_BOUNDARY_LINE_START: Bounds span one line of text, with the line delimiter at the end of the + * bounds, if present, within the current text object. + *@SPI_TEXT_BOUNDARY_LINE_END: Bounds span one line of text, including a preceding line delimiter + * if present within the current text object. + *@SPI_TEXT_BOUNDARY_ATTRIBUTE_RANGE: Bounds span the run, relative to the specified offset and + * text accessor API rules, over which the attributes of the text object are invariant. * - *Text boundary types used for specifying boundaries for regions of text + *Text boundary types used for specifying boundaries for regions of text. **/ typedef enum { @@ -88,7 +95,7 @@ typedef enum /** *AccessibleRelationType: - *@SPI_RELATION_NULL: + *@SPI_RELATION_NULL: Not used, this is an invalid value for this enumeration. *@SPI_RELATION_LABEL_FOR: Indicates an object is a label for one or more target objects. *@SPI_RELATION_LABELED_BY: Indicates an object is labelled by one or more target objects. *@SPI_RELATION_CONTROLLED_BY: Indicates an object controlled by one or more target objects. @@ -96,7 +103,8 @@ typedef enum *@SPI_RELATION_MEMBER_OF: Indicates an object is a member of a group of one or more target objects. *@SPI_RELATION_NODE_CHILD_OF: Indicates an object is a cell in a treetable which is displayed because a cell in the same column is expanded and identifies that cell. - *@SPI_RELATION_EXTENDED: + *@SPI_RELATION_EXTENDED: This value indicates that a relation other than those pre-specified by this version of AT-SPI + * is present. *@SPI_RELATION_FLOWS_TO: Indicates that the object has content that flows logically to another * AtkObject in a sequential way, (for instance text-flow). *@SPI_RELATION_FLOWS_FROM: Indicates that the object has content that flows logically from @@ -109,7 +117,8 @@ more target objects. * this object's content is visualy embedded in another object. *@SPI_RELATION_POPUP_FOR: Indicates that an object is a popup for another objec t. - *@SPI_RELATION_LAST_DEFINED: + *@SPI_RELATION_LAST_DEFINED: Do not use, this is an implementation detail used + * to identify the size of this enumeration. * *Describes the type of the relation **/ @@ -150,13 +159,18 @@ typedef enum { /** *AccessibleKeySynthType: - *@SPI_KEY_PRESS: - *@SPI_KEY_RELEASE: - *@SPI_KEY_PRESSRELEASE: - *@SPI_KEY_SYM: - *@SPI_KEY_STRING: + *@SPI_KEY_PRESS: Generates a keypress event (requires a subsequent #SPI_KEY_RELEASE event) + *@SPI_KEY_RELEASE: Generates a key-release event + *@SPI_KEY_PRESSRELEASE: Generates a key press/release event pair. + *@SPI_KEY_SYM: Injects a "keysym" event into the stream, as if a press/release pair occurred; allows + * the user to specify the key via its symbolic name, as opposed to simulating a hardware press of a + * specific key. + *@SPI_KEY_STRING: Injects one or more keysym events into the keyboard buffer, or directly inserts + * a string value into the currently focussed text widget, if the widgets supports this. + * #SPI_KEY_STRING synthesis provides a shortcut for text substring insertion, and also allows the + * insertion of text which is not currently available via the current keyboard's keymap. * - *Specified the type of a generated event. + * Specifies the type of a generated event. **/ typedef enum { SPI_KEY_PRESS, @@ -168,12 +182,28 @@ typedef enum { /** *AccessibleKeyListenerSyncType: - *@SPI_KEYLISTENER_NOSYNC: - *@SPI_KEYLISTENER_SYNCHRONOUS: - *@SPI_KEYLISTENER_CANCONSUME: - *@SPI_KEYLISTENER_ALL_WINDOWS: + *@SPI_KEYLISTENER_NOSYNC: Events may be delivered asynchronously, + * which means in some cases they may already have been delivered to the + * application before the AT client receives the notification. + *@SPI_KEYLISTENER_SYNCHRONOUS: Events are delivered synchronously, before the + * currently focussed application sees them. + *@SPI_KEYLISTENER_CANCONSUME: Events may be consumed by the AT client. Presumes and + * requires #SPI_KEYLISTENER_SYNCHRONOUS, incompatible with #SPI_KEYLISTENER_NOSYNC. + *@SPI_KEYLISTENER_ALL_WINDOWS: Events are received not from the application toolkit layer, but + * from the device driver or windowing system subsystem; such notifications are 'global' in the + * sense that they are not broken or defeated by applications that participate poorly + * in the accessibility APIs, or not at all; however because of the intrusive nature of + * such snooping, it can have side-effects on certain older platforms. If unconditional + * event notifications, even when inaccessible or "broken" applications have focus, are not + * required, it may be best to avoid this enum value/flag. * *Specified the tyupe of a key listener event. + * Certain of the values above can and should be bitwise-'OR'ed + * together, observing the compatibility limitations specified in the description of + * each value. For instance, #SPI_KEYLISTENER_ALL_WINDOWS | #SPI_KEYLISTENER_CANCONSUME is + * a commonly used combination which gives the AT complete control over the delivery of matching + * events. However, such filters should be used sparingly as they may have a negative impact on + * system performance. **/ typedef enum { SPI_KEYLISTENER_NOSYNC = 0, @@ -198,11 +228,33 @@ typedef enum SPI_STREAM_SEEK_END } AccessibleStreamableContentSeekType; +/** + * SPIException: + * @type: private + * @source: private + * @ev: private + * @code: private + * @desc: private + * + * An opaque object encapsulating information about thrown exceptions. + **/ typedef struct _SPIException SPIException; -typedef SPIBoolean -(* SPIExceptionHandler) (SPIException *err, SPIBoolean is_fatal); +typedef SPIBoolean (*SPIExceptionHandler) (SPIException *err, SPIBoolean is_fatal); + +/** + * SPIExceptionCode: + * @SPI_EXCEPTION_UNSPECIFIED: An exception of unknown type, or which doesn't fit the other types. + * @SPI_EXCEPTION_DISCONNECT: Communication with the object or service has been disconnected; + * this usually means that the object or service has died or exited. + * @SPI_EXCEPTION_NO_IMPL: The object or service is missing the implementation for a request. + * @SPI_EXCEPTION_IO: The communications channel has become corrupted, blocked, or is otherwise in a bad state. + * @SPI_EXCEPTION_BAD_DATA: The data received or sent over the interface has been identified as + * improperly formatted or otherwise fails to match the expectations. + * + * Exception codes indicating what's gone wrong in an AT-SPI call. + **/ typedef enum { SPI_EXCEPTION_UNSPECIFIED, SPI_EXCEPTION_DISCONNECT, @@ -211,6 +263,15 @@ typedef enum { SPI_EXCEPTION_BAD_DATA } SPIExceptionCode; +/** + * SPIExceptionType: + * @SPI_EXCEPTION_SOURCE_UNSPECIFIED: Don't know or can't tell where the problem is + * @SPI_EXCEPTION_SOURCE_ACCESSIBLE: The source of an event or query (i.e. an app) has thrown the exception. + * @SPI_EXCEPTION_SOURCE_REGISTRY: The AT-SPI registry has thrown the exception or cannot be reached. + * @SPI_EXCEPTION_SOURCE_DEVICE: The device event subsystem has encountered an error condition. + * + * The general source of the failure, i.e. whether the app, registry, or device system has encountered trouble. + **/ typedef enum { SPI_EXCEPTION_SOURCE_UNSPECIFIED, SPI_EXCEPTION_SOURCE_ACCESSIBLE, @@ -220,7 +281,15 @@ typedef enum { typedef unsigned long AccessibleKeyEventMask; typedef unsigned long AccessibleDeviceEventMask; - +/** + * SPIRect: + * @x: The position of the minimum x value of the rectangle (i.e. left hand corner) + * @y: The position of the minimum y value of the rectangle's bounds. + * @width: Width of the rectangle in pixels. + * @height: Height of the rectangle in pixels. + * + * A structure encapsulating a rectangle. + **/ typedef struct { long x; long y; @@ -746,16 +815,19 @@ void AccessibleStreamableContent_unref (AccessibleStreamableContent *obj); char ** AccessibleStreamableContent_getContentTypes (AccessibleStreamableContent *obj); + void -AccessibleStreamableContent_freeContentTypeList (AccessibleStreamableContent *obj, - char **list); +AccessibleStreamableContent_freeContentTypesList (AccessibleStreamableContent *obj, + char **content_types); +#define AccessibleStreamableContent_freeContentTypeList(a, b) AccessibleStreamableContent_freeContentTypesList(a,b) + SPIBoolean AccessibleStreamableContent_open (AccessibleStreamableContent *obj, const char *content_type); SPIBoolean AccessibleStreamableContent_close (AccessibleStreamableContent *obj); -long int +long AccessibleStreamableContent_seek (AccessibleStreamableContent *obj, long int offset, AccessibleStreamableContentSeekType seek_type); @@ -1048,7 +1120,7 @@ void SPI_freeString (char *s); char* SPI_dupString (char *s); -void SPI_freeRect (SPIRect *rect); +void SPI_freeRect (SPIRect *r); SPIBoolean SPI_exceptionHandlerPush (SPIExceptionHandler *handler); diff --git a/cspi/spi_accessible.c b/cspi/spi_accessible.c index f28485e..fef635d 100644 --- a/cspi/spi_accessible.c +++ b/cspi/spi_accessible.c @@ -525,6 +525,8 @@ Accessible_getRoleName (Accessible *obj) * This method will return useful values for roles that fall outside the * enumeration used in Accessible_getRole (). * + * @Since: AT-SPI 1.4 + * * Returns: a UTF-8 string specifying the role of this #Accessible object. * **/ @@ -547,6 +549,8 @@ Accessible_getLocalizedRoleName (Accessible *obj) * Accessible_getStateSet: * @obj: a pointer to the #Accessible object on which to operate. * + * Gets the current state of an object. + * * Returns: a pointer to an #AccessibleStateSet representing the object's current state. **/ AccessibleStateSet * @@ -577,11 +581,13 @@ Accessible_getStateSet (Accessible *obj) /** * Accessible_getAttributes: + * @obj: The #Accessible being queried. + * * Get the #AttributeSet representing any assigned * name-value pair attributes or annotations for this object. * For typographic, textual, or textually-semantic attributes, see * AccessibleText_getAttributes instead. - * @obj: The #Accessible being queried. + * * Returns: The name-value-pair attributes assigned to this object. */ AccessibleAttributeSet * @@ -604,8 +610,10 @@ Accessible_getAttributes (Accessible *obj) /** * Accessible_getHostApplication: - * Get the containing #AccessibleApplication for an object. * @obj: The #Accessible being queried. + * + * Get the containing #AccessibleApplication for an object. + * * Returns: the containing AccessibleApplication instance for this object. */ AccessibleApplication * diff --git a/cspi/spi_application.c b/cspi/spi_application.c index c54fd51..4be9422 100644 --- a/cspi/spi_application.c +++ b/cspi/spi_application.c @@ -134,10 +134,14 @@ AccessibleApplication_getID (AccessibleApplication *obj) /** * AccessibleApplication_getLocale: * @obj: a pointer to the #AccessibleApplication being queried. + * @lc_category: one of the POSIX LC_TYPE enumeration, for instance + * LC_MESSAGES. * * Get a POSIX-compliant string describing the application's current * locale setting for a particular @lctype category. * + * @Since: AT-SPI 1.4 + * * Returns: a POSIX-compliant locale string, e.g. "C", "pt_BR", "sr@latn", etc. **/ char * diff --git a/cspi/spi_component.c b/cspi/spi_component.c index 1d7dec0..11202b0 100644 --- a/cspi/spi_component.c +++ b/cspi/spi_component.c @@ -331,10 +331,12 @@ AccessibleComponent_grabFocus (AccessibleComponent *obj) /** * AccessibleComponent_getAlpha: - * Return the opacity/alpha value of a component, if alpha blending is in use. * @obj: The #AccessibleComponent to be queried. + * + * Get the opacity/alpha value of a component, if alpha blending is in use. + * * Returns: the opacity value of a component, as a double between 0.0 and 1.0. - */ + **/ double AccessibleComponent_getAlpha (AccessibleComponent *obj) { diff --git a/cspi/spi_event.c b/cspi/spi_event.c index bbed8e3..07feaed 100644 --- a/cspi/spi_event.c +++ b/cspi/spi_event.c @@ -427,9 +427,9 @@ cspi_internal_event_get_rect (const InternalEvent *e) /** * AccessibleEvent_getSourceName: + * @e: an #AccessibleEvent to be queried. * * Get the 'accessible-name' of the object emitting the event. - * @event: an #AccessibleEvent to be queried. * * Returns: The name of the event source, or NULL if the event source cannot be identified * or does not report a name. @@ -451,9 +451,9 @@ char* AccessibleEvent_getSourceName (const AccessibleEvent *e) /** * AccessibleEvent_getSourceRole: + * @e: an #AccessibleEvent to be queried. * * Get the #AccessibleRole of the object emitting the event. - * @event: an #AccessibleEvent to be queried. * * Returns: #AccessibleRole of the event source, or SPI_ROLE_UNKNOWN * if the event source's role is unknown or unspecified. @@ -477,9 +477,9 @@ AccessibleRole AccessibleEvent_getSourceRole (const AccessibleEvent *e) /** * AccessibleEvent_getSourceApplication: + * @e: an #AccessibleEvent to be queried. * * Get the #Application hosting the object which emitted the event. - * @event: an #AccessibleEvent to be queried. * * Returns: A pointer to the host #Application contining the event source * component. @@ -500,13 +500,18 @@ AccessibleApplication* AccessibleEvent_getSourceApplication (const AccessibleEve } /** - * AccessibleEvent_getSourceApplication: + * AccessibleEvent_getSourceDetails: + * @e: an #AccessibleEvent to be queried. + * @name: a pointer to a character string which will point to the name of the event source + * on successful completion of the call. + * @role: a pointer to an #AccessibleRole which will point to the role of the event source + * on successful completion of the call. + * @app: A pointer to an #AccessibleApplication which points to the host application for this event + * on successful completion of the call. * * Get the host #Application, "accessible name", and #AccessibleRole * of the object which emitted the event. * - * @event: an #AccessibleEvent to be queried. - * * Returns: TRUE if the source details were successfully retrieved, * FALSE if they were not, either due to error, incomplete data, * or the fact that the event did not encapsulate the required data. @@ -774,6 +779,8 @@ AccessibleDescriptionChangedEvent_getDescriptionString (const AccessibleEvent *e * The returned structure should be freed with SPI_freeRect when * the caller has finished referencing it. * + * @Since: AT-SPI 1.6 + * * Returns: a pointer to an SPIRect defining the new object bounds. **/ SPIRect * diff --git a/cspi/spi_image.c b/cspi/spi_image.c index 6bee1ab..94d78ad 100644 --- a/cspi/spi_image.c +++ b/cspi/spi_image.c @@ -183,10 +183,12 @@ AccessibleImage_getImageExtents (AccessibleImage *obj, /** * AccessibleImage_getImageLocale: - * Get the locale associated with an image and its textual representation. * @obj: The #AccessibleImage being queried. + * + * Get the locale associated with an image and its textual representation. + * * Returns: A POSIX LC_MESSAGES-style Locale value for image description and text. - */ + **/ char * AccessibleImage_getImageLocale (AccessibleImage *obj) { diff --git a/cspi/spi_main.c b/cspi/spi_main.c index a0acdae..9bb2e32 100644 --- a/cspi/spi_main.c +++ b/cspi/spi_main.c @@ -80,7 +80,7 @@ cspi_object_release (gpointer value) } gboolean -_cspi_exception_throw (CORBA_Environment *ev, char *desc_prefix) +cspi_exception_throw (CORBA_Environment *ev, char *desc_prefix) { SPIExceptionHandler *handler = NULL; SPIException ex; @@ -550,6 +550,8 @@ SPI_freeString (char *s) * A NULL rect @r will be silently ignored. * This API should not be used to free data * from other libraries or allocated by the client. + * + * @Since: AT-SPI 1.6 **/ void SPI_freeRect (SPIRect *r) @@ -563,7 +565,13 @@ SPI_freeRect (SPIRect *r) } /** - * DOCUMENT_ME! + * SPI_dupString: + * @s: a UTF-8 string to be duplicated + * + * @Since: AT-SPI 1.4 + * + * Returns: a duplicate of the string passed as a parameter, which should + * be freed via SPI_freeString after use. **/ char * SPI_dupString (char *s) @@ -577,7 +585,15 @@ SPI_dupString (char *s) } /** - * DOCUMENT_ME! + * SPI_exceptionHandlerPush: + * @handler: an #SPIExceptionHandler to install as the first code to deal with exceptions. + * + * Install a client-side handler for #SPIException instances, which can see and handle any + * exceptions before chaining them to the next exception handler in the stack. + * + * @Since: AT-SPI 1.4 + * + * Returns %TRUE if the result succeeded, %FALSE if @hander could not be registered. **/ SPIBoolean SPI_exceptionHandlerPush (SPIExceptionHandler *handler) { @@ -588,7 +604,13 @@ SPIBoolean SPI_exceptionHandlerPush (SPIExceptionHandler *handler) } /** - * DOCUMENT_ME! + * SPI_exceptionHandlerPop: + * + * Remove/pop an #SPIExceptionHandler off the error handler stack and return the new handler. + * + * @Since: AT-SPI 1.4 + * + * Returns the #SPIExceptionHandler which is now at the top of the error handler stack after the call. **/ SPIExceptionHandler* SPI_exceptionHandlerPop (void) { @@ -596,7 +618,14 @@ SPIExceptionHandler* SPI_exceptionHandlerPop (void) } /** - * DOCUMENT_ME! + * SPIException_getSourceType: + * @err: the exception being queried + * + * Get the #SPIExceptionType of an exception which has been thrown. + * + * @Since: AT-SPI 1.4 + * + * Returns: the #SPIExceptionType corresponding to exception @err. **/ SPIExceptionType SPIException_getSourceType (SPIException *err) { @@ -607,7 +636,14 @@ SPIExceptionType SPIException_getSourceType (SPIException *err) } /** - * DOCUMENT_ME! + * SPIException_getExceptionCode: + * @err: the #SPIException being queried. + * + * Get the #SPIExceptionCode telling what type of exception condition has occurred. + * + * @Since: AT-SPI 1.4 + * + * Returns: the #SPIExceptionCode corresponding to exception @err. **/ SPIExceptionCode SPIException_getExceptionCode (SPIException *err) { @@ -615,7 +651,14 @@ SPIExceptionCode SPIException_getExceptionCode (SPIException *err) } /** - * DOCUMENT_ME! + * SPIAccessibleException_getSource: + * @err: the #SPIException being queried. + * + * Get the identity of the object which threw an exception. + * + * @Since: AT-SPI 1.4 + * + * Returns: a pointer to the #Accessible object which threw the exception. **/ Accessible* SPIAccessibleException_getSource (SPIException *err) { @@ -625,7 +668,14 @@ Accessible* SPIAccessibleException_getSource (SPIException *err) } /** - * DOCUMENT_ME! + * SPIException_getDescription: + * @err: the #SPIException being queried. + * + * Get a text description of the exception that has been thrown. + * Unfortunately these descriptions tend to be terse and limited in + * the detail which they can provide. + * + * Returns: a brief character string describing the exception. **/ char* SPIException_getDescription (SPIException *err) { diff --git a/cspi/spi_streamablecontent.c b/cspi/spi_streamablecontent.c index 76312ac..2e0c080 100644 --- a/cspi/spi_streamablecontent.c +++ b/cspi/spi_streamablecontent.c @@ -52,7 +52,7 @@ stream_cache_item_free (gpointer a) static GHashTable *streams = NULL; -GHashTable * +static GHashTable * get_streams (void) { if (streams == NULL) @@ -104,6 +104,7 @@ cspi_streams_close_all (void) * * Increment the reference count for an #AccessibleStreamableContent object. * + * @Since: AT-SPI 1.4 **/ void AccessibleStreamableContent_ref (AccessibleStreamableContent *obj) @@ -118,6 +119,7 @@ AccessibleStreamableContent_ref (AccessibleStreamableContent *obj) * * Decrement the reference count for an #AccessibleStreamableContent object. * + * @Since: AT-SPI 1.4 **/ void AccessibleStreamableContent_unref (AccessibleStreamableContent *obj) @@ -132,6 +134,8 @@ AccessibleStreamableContent_unref (AccessibleStreamableContent *obj) * Get a list of strings containing the content mimetypes available from an * #AccessibleStreamableContent implementor. * + * @Since: AT-SPI 1.4 + * * Returns: an array of strings, terminated by a NULL string, specifying the * mimetypes for which the streamed content is available. * @@ -156,7 +160,17 @@ AccessibleStreamableContent_getContentTypes (AccessibleStreamableContent *obj) return content_types; } - +/** +* AccessibleStreamableContent_freeContentTypesList: +* @obj: the AccessibleStreamableContent implementor on which to operate. +* @content_types: a list of content types previously returned by +* #AccessibleStreamableContent_getContentTypes. +* +* Free the memory associated with a call to #AccessibleStreamableContent_getContentTypes, once +* the result has been used. +* +* @Since: AT-SPI 1.4 +**/ void AccessibleStreamableContent_freeContentTypesList (AccessibleStreamableContent *obj, char **content_types) @@ -182,6 +196,8 @@ AccessibleStreamableContent_freeContentTypesList (AccessibleStreamableContent *o * Open a streaming connection to an AccessibleStreamableContent implementor, * of a particular content type * + * @Since: AT-SPI 1.4 + * * Returns: #TRUE if successful, #FALSE if unsuccessful. * **/ @@ -213,6 +229,8 @@ AccessibleStreamableContent_open (AccessibleStreamableContent *obj, * Close the current streaming connection to an AccessibleStreamableContent implementor. * This must be called before any subsequent AccessibleStreamableContent_open * calls on the same object. + * + * @Since: AT-SPI 1.4 * * Returns: #TRUE if successful, #FALSE if unsuccessful. * @@ -238,6 +256,8 @@ AccessibleStreamableContent_close (AccessibleStreamableContent *obj) * #AccessibleStreamableContent_open()) to seek to a particular offset in the * stream. * + * @Since: AT-SPI 1.4 + * * Returns: #TRUE if successful, #FALSE if unsuccessful. * **/ @@ -292,6 +312,8 @@ AccessibleStreamableContent_seek (AccessibleStreamableContent *obj, * return until the bytes have been read, or an error condition is * detected. * + * @Since: AT-SPI 1.4 + * * Returns: an integer indicating the number of bytes read, or -1 on error. * **/ diff --git a/cspi/spi_table.c b/cspi/spi_table.c index 00421e8..da083db 100644 --- a/cspi/spi_table.c +++ b/cspi/spi_table.c @@ -559,7 +559,7 @@ AccessibleTable_getSelectedColumns (AccessibleTable *obj, /** * AccessibleTable_isRowSelected: * @obj: a pointer to the #AccessibleTable implementor on which to operate. - * @row: + * @row: the zero-indexed row number of the row being queried. * * Determine whether a table row is selected. Not all tables support row selection. * @@ -585,7 +585,7 @@ AccessibleTable_isRowSelected (AccessibleTable *obj, /** * AccessibleTable_isColumnSelected: * @obj: a pointer to the #AccessibleTable implementor on which to operate. - * @column: + * @column: the zero-indexed column number of the column being queried. * * Determine whether specified table column is selected. * Not all tables support column selection. @@ -612,7 +612,7 @@ AccessibleTable_isColumnSelected (AccessibleTable *obj, /** * AccessibleTable_addRowSelection: * @obj: a pointer to the #AccessibleTable implementor on which to operate. - * @row: + * @row: the zero-indexed row number of the row being selected. * * Select the specified row, adding it to the current row selection. * Not all tables support row selection. @@ -639,7 +639,7 @@ AccessibleTable_addRowSelection (AccessibleTable *obj, /** * AccessibleTable_addColumnSelection: * @obj: a pointer to the #AccessibleTable implementor on which to operate. - * @column: + * @column: the zero-indexed column number of the column being selected. * * Select the specified column, adding it to the current column selection. * Not all tables support column selection. @@ -666,7 +666,7 @@ AccessibleTable_addColumnSelection (AccessibleTable *obj, /** * AccessibleTable_removeRowSelection: * @obj: a pointer to the #AccessibleTable implementor on which to operate. - * @row: + * @row: the zero-indexed number of the row being deselected. * * De-select the specified row, removing it to the current row selection. * Not all tables support row selection. @@ -693,7 +693,7 @@ AccessibleTable_removeRowSelection (AccessibleTable *obj, /** * AccessibleTable_removeColumnSelection: * @obj: a pointer to the #AccessibleTable implementor on which to operate. - * @column: + * @column: the zero-indexed column number of the column being de-selected. * * De-select the specified column, removing it to the current column selection. * Not all tables support column selection. @@ -720,8 +720,8 @@ AccessibleTable_removeColumnSelection (AccessibleTable *obj, /** * AccessibleTable_isSelected: * @obj: a pointer to the #AccessibleTable implementor on which to operate. - * @row: - * @column: + * @row: the zero-indexed row of the cell being queried. + * @column: the zero-indexed column of the cell being queried. * * Determine whether the cell at a specific row and column is selected. * diff --git a/cspi/spi_text.c b/cspi/spi_text.c index 0e804bc..e8ce45d 100644 --- a/cspi/spi_text.c +++ b/cspi/spi_text.c @@ -280,6 +280,8 @@ AccessibleText_getAttributes (AccessibleText *obj, * the attributes reported by #AccessibleText_getAttributes * describes the entire set of text attributes over a range. * + * @Since: AT-SPI 1.4 + * * Returns: a text string describing the default attributes * applied to a text object, (exclusive of explicitly-set * attributes), encoded as UTF-8. @@ -643,6 +645,7 @@ AccessibleText_getOffsetAtPoint (AccessibleText *obj, * * Get the bounding box for text within a range in an #AccessibleText object. * + * @Since: AT-SPI 1.2 **/ void AccessibleText_getRangeExtents (AccessibleText *obj, @@ -703,6 +706,8 @@ AccessibleText_getRangeExtents (AccessibleText *obj, * Get the ranges of text from an #AccessibleText object which lie within the * bounds defined by (@x, @y) and (@x+@width, @y+@height). * + * @Since: AT-SPI 1.2 + * * Returns: a null-terminated list of pointers to AccessibleTextRange structs * detailing the bounded text. **/ @@ -740,6 +745,8 @@ AccessibleText_getBoundedRanges (AccessibleText *obj, * Free the memory used by a list of AccessibleTextRange structs. * The argument passed in should be an array of pointers * AccessibleTextRange structs. + * + * @Since: AT-SPI 1.2 **/ void AccessibleTextRange_freeRanges (AccessibleTextRange **ranges) diff --git a/docs/reference/cspi/at-spi-cspi-sections.txt b/docs/reference/cspi/at-spi-cspi-sections.txt index 6a94ffa..69bbd55 100644 --- a/docs/reference/cspi/at-spi-cspi-sections.txt +++ b/docs/reference/cspi/at-spi-cspi-sections.txt @@ -9,6 +9,19 @@ SPI_nextEvent SPI_exit SPI_freeString +SPIAccessibleException_getSource +SPIException_getDescription +SPIException_getExceptionCode +SPIException_getSourceType +SPIException +SPIExceptionCode +SPIExceptionType +SPIBoolean +SPIRect +SPI_freeRect +SPI_dupString +SPI_exceptionHandlerPush +SPI_exceptionHandlerPop
@@ -16,6 +29,10 @@ SPI_freeString Event Listener Support AccessibleEvent AccessibleEventListenerCB +AccessibleEvent_getSourceApplication +AccessibleEvent_getSourceDetails +AccessibleEvent_getSourceName +AccessibleEvent_getSourceRole AccessibleEvent_ref AccessibleEvent_unref SPI_createAccessibleEventListener @@ -28,6 +45,7 @@ AccessibleChildChangedEvent_getChildAccessible AccessibleDescriptionChangedEvent_getDescriptionString AccessibleNameChangedEvent_getNameString AccessibleParentChangedEvent_getParentAccessible +AccessibleBoundsChangedEvent_getNewBounds AccessibleTableCaptionChangedEvent_getCaptionString AccessibleTableColumnDescriptionChangedEvent_getDescriptionString AccessibleTableHeaderChangedEvent_getHeaderAccessible @@ -97,6 +115,9 @@ Accessible_getRelationSet Accessible_getRole Accessible_getRoleName Accessible_getStateSet +Accessible_getAttributes +Accessible_getHostApplication +Accessible_getLocalizedRoleName Accessible_isAction Accessible_isApplication @@ -190,6 +211,7 @@ AccessibleApplication_unref AccessibleApplication_getToolkitName AccessibleApplication_getVersion AccessibleApplication_getID +AccessibleApplication_getLocale AccessibleApplication_pause AccessibleApplication_resume
@@ -221,6 +243,7 @@ AccessibleComponent_getSize AccessibleComponent_getLayer AccessibleComponent_getMDIZOrder AccessibleComponent_grabFocus +AccessibleComponent_getAlpha
@@ -256,6 +279,7 @@ AccessibleImage_getImageDescription AccessibleImage_getImageSize AccessibleImage_getImagePosition AccessibleImage_getImageExtents +AccessibleImage_getImageLocale
@@ -281,6 +305,8 @@ AccessibleStreamableContent_getContentTypes AccessibleStreamableContent_open AccessibleStreamableContent_seek AccessibleStreamableContent_read +AccessibleStreamableContent_close +AccessibleStreamableContent_freeContentTypeList
@@ -309,6 +335,10 @@ AccessibleTable_getSummary AccessibleTable_isColumnSelected AccessibleTable_isRowSelected AccessibleTable_isSelected +AccessibleTable_addColumnSelection +AccessibleTable_addRowSelection +AccessibleTable_removeColumnSelection +AccessibleTable_removeRowSelection
@@ -335,6 +365,8 @@ AccessibleText_getTextAtOffset AccessibleText_removeSelection AccessibleText_setCaretOffset AccessibleText_setSelection +AccessibleText_getCharacterAtOffset +AccessibleText_getDefaultAttributes AccessibleTextRange_freeRanges
diff --git a/docs/reference/cspi/tmpl/spi_accessible.sgml b/docs/reference/cspi/tmpl/spi_accessible.sgml index d7aaad9..4fdfaf6 100644 --- a/docs/reference/cspi/tmpl/spi_accessible.sgml +++ b/docs/reference/cspi/tmpl/spi_accessible.sgml @@ -23,9 +23,9 @@ An Accessible object is an opaque object used to refer to an accessible object corresponding to an user interface element. -@objref: -@on_loan: -@ref_count: +@objref: private data +@on_loan: private data +@ref_count: private data @@ -134,6 +134,33 @@ object corresponding to an user interface element. @Returns: + + + + + +@obj: +@Returns: + + + + + + + +@obj: +@Returns: + + + + + + + +@obj: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_application.sgml b/docs/reference/cspi/tmpl/spi_application.sgml index b2205be..8e00617 100644 --- a/docs/reference/cspi/tmpl/spi_application.sgml +++ b/docs/reference/cspi/tmpl/spi_application.sgml @@ -60,6 +60,16 @@ AccessibleApplication API @Returns: + + + + + +@obj: +@lc_category: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_component.sgml b/docs/reference/cspi/tmpl/spi_component.sgml index 0160801..2cf0f89 100644 --- a/docs/reference/cspi/tmpl/spi_component.sgml +++ b/docs/reference/cspi/tmpl/spi_component.sgml @@ -141,3 +141,12 @@ AccessibleComponent Interface @Returns: + + + + + +@obj: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_event.sgml b/docs/reference/cspi/tmpl/spi_event.sgml index 1784c1d..8ba9078 100644 --- a/docs/reference/cspi/tmpl/spi_event.sgml +++ b/docs/reference/cspi/tmpl/spi_event.sgml @@ -37,6 +37,45 @@ It is called when an event being listened for occurs. @user_data: + + + + + +@e: +@Returns: + + + + + + + +@e: +@name: +@role: +@app: +@Returns: + + + + + + + +@e: +@Returns: + + + + + + + +@e: +@Returns: + + @@ -138,6 +177,15 @@ It is called when an event being listened for occurs. @Returns: + + + + + +@e: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_image.sgml b/docs/reference/cspi/tmpl/spi_image.sgml index e52f8a7..f5fb808 100644 --- a/docs/reference/cspi/tmpl/spi_image.sgml +++ b/docs/reference/cspi/tmpl/spi_image.sgml @@ -76,3 +76,12 @@ AccessibleImage Interface @ctype: + + + + + +@obj: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_main.sgml b/docs/reference/cspi/tmpl/spi_main.sgml index 5682bb3..3b1b453 100644 --- a/docs/reference/cspi/tmpl/spi_main.sgml +++ b/docs/reference/cspi/tmpl/spi_main.sgml @@ -72,3 +72,115 @@ SPI main loop and initialization @s: + + + + + +@err: +@Returns: + + + + + + + +@err: +@Returns: + + + + + + + +@err: +@Returns: + + + + + + + +@err: +@Returns: + + + + + + + +@type: +@source: +@ev: +@code: +@desc: + + + + + + +@SPI_EXCEPTION_UNSPECIFIED: +@SPI_EXCEPTION_DISCONNECT: +@SPI_EXCEPTION_NO_IMPL: +@SPI_EXCEPTION_IO: +@SPI_EXCEPTION_BAD_DATA: + + + + + + +@SPI_EXCEPTION_SOURCE_UNSPECIFIED: +@SPI_EXCEPTION_SOURCE_ACCESSIBLE: +@SPI_EXCEPTION_SOURCE_REGISTRY: +@SPI_EXCEPTION_SOURCE_DEVICE: + + + + + + +@x: +@y: +@width: +@height: + + + + + + +@r: + + + + + + + +@s: +@Returns: + + + + + + + +@handler: +@Returns: + + + + + + + +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_table.sgml b/docs/reference/cspi/tmpl/spi_table.sgml index 66139ad..b3f5ecf 100644 --- a/docs/reference/cspi/tmpl/spi_table.sgml +++ b/docs/reference/cspi/tmpl/spi_table.sgml @@ -242,3 +242,43 @@ AccessibleTable Interface @Returns: + + + + + +@obj: +@column: +@Returns: + + + + + + + +@obj: +@row: +@Returns: + + + + + + + +@obj: +@column: +@Returns: + + + + + + + +@obj: +@row: +@Returns: + + diff --git a/docs/reference/cspi/tmpl/spi_text.sgml b/docs/reference/cspi/tmpl/spi_text.sgml index 2787eb3..a4fa387 100644 --- a/docs/reference/cspi/tmpl/spi_text.sgml +++ b/docs/reference/cspi/tmpl/spi_text.sgml @@ -258,6 +258,25 @@ AccessibleText Interface @Returns: + + + + + +@obj: +@offset: +@Returns: + + + + + + + +@obj: +@Returns: + + -- 2.7.4