## Event Listener Support

Event Listener Support —

##

# Synopsis

    typedef     AccessibleEvent;
    void        (*AccessibleEventListenerCB)    (const AccessibleEvent *event,
                                                 void *user_data);
    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);
    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;

AccessibleEvent is a struct used to encapsulate event information.

### AccessibleEventListenerCB ()

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

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

`event` : |
`user_data` : |

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

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