Event Listener Support

Event Listener Support —

Synopsis

                    AccessibleEvent;
void                (*AccessibleEventListenerCB)        (const AccessibleEvent *event,
                                                         void *user_data);
AccessibleApplication* AccessibleEvent_getSourceApplication
                                                        (const AccessibleEvent *e);
SPIBoolean          AccessibleEvent_getSourceDetails    (const AccessibleEvent *e,
                                                         char **name,
                                                         AccessibleRole *role,
                                                         AccessibleApplication **app);
char*               AccessibleEvent_getSourceName       (const AccessibleEvent *e);
AccessibleRole      AccessibleEvent_getSourceRole       (const AccessibleEvent *e);
SPIBoolean          AccessibleEvent_ref                 (const AccessibleEvent *e);
void                AccessibleEvent_unref               (const AccessibleEvent *e);
AccessibleEventListener* SPI_createAccessibleEventListener
                                                        (AccessibleEventListenerCB callback,
                                                         void *user_data);
void                AccessibleEventListener_unref       (AccessibleEventListener *listener);
SPIBoolean          AccessibleEventListener_addCallback (AccessibleEventListener *listener,
                                                         AccessibleEventListenerCB callback,
                                                         void *user_data);
SPIBoolean          AccessibleEventListener_removeCallback
                                                        (AccessibleEventListener *listener,
                                                         AccessibleEventListenerCB callback);

Accessible*         AccessibleActiveDescendantChangedEvent_getActiveDescendant
                                                        (const AccessibleEvent *e);
Accessible*         AccessibleChildChangedEvent_getChildAccessible
                                                        (const AccessibleEvent *e);
char*               AccessibleDescriptionChangedEvent_getDescriptionString
                                                        (const AccessibleEvent *e);
char*               AccessibleNameChangedEvent_getNameString
                                                        (const AccessibleEvent *e);
Accessible*         AccessibleParentChangedEvent_getParentAccessible
                                                        (const AccessibleEvent *e);
SPIRect*            AccessibleBoundsChangedEvent_getNewBounds
                                                        (const AccessibleEvent *e);
char*               AccessibleTableCaptionChangedEvent_getCaptionString
                                                        (const AccessibleEvent *e);
char*               AccessibleTableColumnDescriptionChangedEvent_getDescriptionString
                                                        (const AccessibleEvent *e);
Accessible*         AccessibleTableHeaderChangedEvent_getHeaderAccessible
                                                        (const AccessibleEvent *e);
char*               AccessibleTableRowDescriptionChangedEvent_getDescriptionString
                                                        (const AccessibleEvent *e);
Accessible*         AccessibleTableSummaryChangedEvent_getSummaryAccessible
                                                        (const AccessibleEvent *e);
char*               AccessibleTextChangedEvent_getChangeString
                                                        (const AccessibleEvent *e);
char*               AccessibleTextSelectionChangedEvent_getSelectionString
                                                        (const AccessibleEvent *e);
char*               AccessibleWindowEvent_getTitleString
                                                        (const AccessibleEvent *e);

Description

Details

AccessibleEvent

typedef struct {
  const char  *type;
  Accessible  *source;
  long         detail1;
  long         detail2;
} AccessibleEvent;

A structure used to encapsulate event information.

AccessibleEvent is a struct used to encapsulate event information.

const char *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.
Accessible *source; The Accessible from which the event originated.

AccessibleEventListenerCB ()

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

A function prototype for callbacks via which clients are notified of AT-SPI events.

This is a function which is specified when creating a EventListener. It is called when an event being listened for occurs.

event : The event for which notification is sent.
user_data : User data which is passed to the callback each time a notification takes place.

AccessibleEvent_getSourceApplication ()

AccessibleApplication* AccessibleEvent_getSourceApplication
                                                        (const AccessibleEvent *e);

Get the Application hosting the object which emitted the event.

e : an AccessibleEvent to be queried.
Returns : A pointer to the host Application contining the event source component.

AccessibleEvent_getSourceDetails ()

SPIBoolean          AccessibleEvent_getSourceDetails    (const AccessibleEvent *e,
                                                         char **name,
                                                         AccessibleRole *role,
                                                         AccessibleApplication **app);

Get the host Application, "accessible name", and AccessibleRole of the object which emitted the event.

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.
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.

AccessibleEvent_getSourceName ()

char*               AccessibleEvent_getSourceName       (const AccessibleEvent *e);

Get the 'accessible-name' of the object emitting the event.

e : 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.

AccessibleEvent_getSourceRole ()

AccessibleRole      AccessibleEvent_getSourceRole       (const AccessibleEvent *e);

Get the AccessibleRole of the object emitting the event.

e : 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. (Some kinds of events, such as 'mouse:' events or toolkit events, don't have associated object roles.)

AccessibleEvent_ref ()

SPIBoolean          AccessibleEvent_ref                 (const AccessibleEvent *e);

Increments by 1 the reference count of the event

e : a pointer to the AccessibleEvent being referenced.
Returns : TRUE if the function succeeded; FALSE if the pointer is not a valid event.

AccessibleEvent_unref ()

void                AccessibleEvent_unref               (const AccessibleEvent *e);

Decrements by 1 the reference count of the event. The event is destroyed when the reference count recahes zero.

e : a pointer to the AccessibleEvent being referenced.

SPI_createAccessibleEventListener ()

AccessibleEventListener* SPI_createAccessibleEventListener
                                                        (AccessibleEventListenerCB callback,
                                                         void *user_data);

Create a new AccessibleEventListener with a specified (in-process) callback function.

callback : an AccessibleEventListenerCB callback function, or NULL.
user_data : a pointer to data which will be passed to the callback when invoked.
Returns : a pointer to a newly-created AccessibleEventListener.

AccessibleEventListener_unref ()

void                AccessibleEventListener_unref       (AccessibleEventListener *listener);

Decrements an AccessibleEventListener's reference count.

listener : a pointer to the AccessibleEventListener being operated on.

AccessibleEventListener_addCallback ()

SPIBoolean          AccessibleEventListener_addCallback (AccessibleEventListener *listener,
                                                         AccessibleEventListenerCB callback,
                                                         void *user_data);

Add an in-process callback function to an existing AccessibleEventListener. Note that the callback function must live in the same address space as the AccessibleEventListener implementation code, thus one should not use this function to attach callbacks to a 'remote' event listener (that is, one that was not created by a client call to createAccessibleEventListener();

listener : the AccessibleEventListener instance to modify.
callback : an AccessibleEventListenerCB function pointer.
user_data : a pointer to data which will be passed to the callback when invoked.
Returns : TRUE if successful, otherwise FALSE.

AccessibleEventListener_removeCallback ()

SPIBoolean          AccessibleEventListener_removeCallback
                                                        (AccessibleEventListener *listener,
                                                         AccessibleEventListenerCB callback);

Remove an in-process callback function from an existing AccessibleEventListener.

listener : the AccessibleEventListener instance to modify.
callback : an AccessibleEventListenerCB function pointer.
Returns : TRUE if successful, otherwise FALSE.

AccessibleActiveDescendantChangedEvent_getActiveDescendant ()

Accessible*         AccessibleActiveDescendantChangedEvent_getActiveDescendant
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:active-descendant-changed" to get a reference to the changed Accessible. Note that context Accessibles are not guaranteed to outlive event delivery, in which case this call may return NULL even if the object existed at the time of dispatch.

e : a pointer to the AccessibleEvent being queried.
Returns : an Accessible pointer representing the new active descendant.

AccessibleChildChangedEvent_getChildAccessible ()

Accessible*         AccessibleChildChangedEvent_getChildAccessible
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:children_changed" to get a reference to the changed Accessible. Note that context Accessibles are not guaranteed to outlive event delivery, in which case this call may return NULL even if the object existed at the time of dispatch.

e : a pointer to the AccessibleEvent being queried.
Returns : the context Accessible for the event, or NULL if there is no longer a valid context Accessible object for the event.

AccessibleDescriptionChangedEvent_getDescriptionString ()

char*               AccessibleDescriptionChangedEvent_getDescriptionString
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:property-changed:accessible-description" returning the new description.

e : a pointer to the AccessibleEvent being queried.
Returns : a UTF-8 text string representing the recently changed description

AccessibleNameChangedEvent_getNameString ()

char*               AccessibleNameChangedEvent_getNameString
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:property-change:accessible_name:", returning the name.

e : a pointer to the AccessibleEvent being queried.
Returns : a UTF-8 text string representing the name of the object which recently changed.

AccessibleParentChangedEvent_getParentAccessible ()

Accessible*         AccessibleParentChangedEvent_getParentAccessible
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:property-change:accessible-parent" to get a reference to the changed Accessible. Note that context Accessibles are not guaranteed to outlive event delivery, in which case this call may return NULL even if the object existed at the time of dispatch.

e : a pointer to the AccessibleEvent being queried.
Returns : an Accessible pointer representing the new parent object.

AccessibleBoundsChangedEvent_getNewBounds ()

SPIRect*            AccessibleBoundsChangedEvent_getNewBounds
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:bounds-changed", returning a pointer to an SPIRect structure containing the new bounds, or NULL on error. The returned structure should be freed with SPI_freeRect when the caller has finished referencing it.

Since: AT-SPI 1.6

e : a pointer to the AccessibleEvent being queried.
Returns : a pointer to an SPIRect defining the new object bounds.

AccessibleTableCaptionChangedEvent_getCaptionString ()

char*               AccessibleTableCaptionChangedEvent_getCaptionString
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:property-changed:accessible-table-caption-object" returning the text in the caption, if present.

e : a pointer to the AccessibleEvent being queried.
Returns : a UTF-8 text string indicating the text in the caption.

AccessibleTableColumnDescriptionChangedEvent_getDescriptionString ()

char*               AccessibleTableColumnDescriptionChangedEvent_getDescriptionString
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:property-changed:accessible-table-column-description" returning the new table column description.

e : a pointer to the AccessibleEvent being queried.
Returns : a UTF-8 text string representing the recently changed table column description

AccessibleTableHeaderChangedEvent_getHeaderAccessible ()

Accessible*         AccessibleTableHeaderChangedEvent_getHeaderAccessible
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:property-changed:accessible-table-row-header" or "object:property-changed:accessible-table-column-header" to get a reference to the changed Accessible. Note that context Accessibles are not guaranteed to outlive event delivery, in which case this call may return NULL even if the object existed at the time of dispatch.

e : a pointer to the AccessibleEvent being queried.
Returns : an Accessible pointer representing the new table header.

AccessibleTableRowDescriptionChangedEvent_getDescriptionString ()

char*               AccessibleTableRowDescriptionChangedEvent_getDescriptionString
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:property-changed:accessible-table-row-description" returning the new table row description.

e : a pointer to the AccessibleEvent being queried.
Returns : a UTF-8 text string representing the recently changed table row description

AccessibleTableSummaryChangedEvent_getSummaryAccessible ()

Accessible*         AccessibleTableSummaryChangedEvent_getSummaryAccessible
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:property-changed:accessible-table-summary" to get a reference to the changed Accessible. Note that context Accessibles are not guaranteed to outlive event delivery, in which case this call may return NULL even if the object existed at the time of dispatch.

e : a pointer to the AccessibleEvent being queried.
Returns : an Accessible pointer representing the new table summary.

AccessibleTextChangedEvent_getChangeString ()

char*               AccessibleTextChangedEvent_getChangeString
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:text-changed", returning the text inserted or deleted.

e : a pointer to the AccessibleEvent being queried.
Returns : a UTF-8 text string indicating the text inserted, deleted, or substituted by this event.

AccessibleTextSelectionChangedEvent_getSelectionString ()

char*               AccessibleTextSelectionChangedEvent_getSelectionString
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "object:text-selection-changed", returning the newly added, removed, or modified selection string.

e : a pointer to the AccessibleEvent being queried.
Returns : a UTF-8 text string indicating the recently changed selection.

AccessibleWindowEvent_getTitleString ()

char*               AccessibleWindowEvent_getTitleString
                                                        (const AccessibleEvent *e);

Queries an AccessibleEvent of type "window:", returning the window title.

e : a pointer to the AccessibleEvent being queried.
Returns : a UTF-8 text string representing the title of the recently changed window.