## AccessibleText Interface

AccessibleText Interface —

##

# Synopsis

    enum        AccessibleTextBoundaryType;
    enum        AccessibleTextClipType;
    void        AccessibleText_ref              (AccessibleText *obj);
    void        AccessibleText_unref            (AccessibleText *obj);
    SPIBoolean  AccessibleText_addSelection     (AccessibleText *obj,
                                                 long int startOffset,
                                                 long int endOffset);
    char*       AccessibleText_getAttributes    (AccessibleText *obj,
                                                 long int offset,
                                                 long int *startOffset,
                                                 long int *endOffset);
    AccessibleTextRange** AccessibleText_getBoundedRanges
                                                (AccessibleText *obj,
                                                 long int x,
                                                 long int y,
                                                 long int width,
                                                 long int height,
                                                 AccessibleCoordType type,
                                                 AccessibleTextClipType clipTypeX,
                                                 AccessibleTextClipType clipTypeY);
    long        AccessibleText_getCaretOffset   (AccessibleText *obj);
    long        AccessibleText_getCharacterCount
                                                (AccessibleText *obj);
    void        AccessibleText_getCharacterExtents
                                                (AccessibleText *obj,
                                                 long int offset,
                                                 long int *x,
                                                 long int *y,
                                                 long int *width,
                                                 long int *height,
                                                 AccessibleCoordType type);
    long        AccessibleText_getNSelections   (AccessibleText *obj);
    long        AccessibleText_getOffsetAtPoint (AccessibleText *obj,
                                                 long int x,
                                                 long int y,
                                                 AccessibleCoordType type);
    void        AccessibleText_getRangeExtents  (AccessibleText *obj,
                                                 long int startOffset,
                                                 long int endOffset,
                                                 long int *x,
                                                 long int *y,
                                                 long int *width,
                                                 long int *height,
                                                 AccessibleCoordType type);
    void        AccessibleText_getSelection     (AccessibleText *obj,
                                                 long int selectionNum,
                                                 long int *startOffset,
                                                 long int *endOffset);
    char*       AccessibleText_getText          (AccessibleText *obj,
                                                 long int startOffset,
                                                 long int endOffset);
    char*       AccessibleText_getTextBeforeOffset
                                                (AccessibleText *obj,
                                                 long int offset,
                                                 AccessibleTextBoundaryType type,
                                                 long int *startOffset,
                                                 long int *endOffset);
    char*       AccessibleText_getTextAfterOffset
                                                (AccessibleText *obj,
                                                 long int offset,
                                                 AccessibleTextBoundaryType type,
                                                 long int *startOffset,
                                                 long int *endOffset);
    char*       AccessibleText_getTextAtOffset  (AccessibleText *obj,
                                                 long int offset,
                                                 AccessibleTextBoundaryType type,
                                                 long int *startOffset,
                                                 long int *endOffset);
    SPIBoolean  AccessibleText_removeSelection  (AccessibleText *obj,
                                                 long int selectionNum);
    SPIBoolean  AccessibleText_setCaretOffset   (AccessibleText *obj,
                                                 long int newOffset);
    SPIBoolean  AccessibleText_setSelection     (AccessibleText *obj,
                                                 long int selectionNum,
                                                 long int startOffset,
                                                 long int endOffset);
    void        AccessibleTextRange_freeRanges  (AccessibleTextRange **ranges);

## Description

## Details

### enum AccessibleTextBoundaryType

    typedef enum
    {
      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
    } AccessibleTextBoundaryType;

Text boundary types used for specifying boundaries for regions of text

### enum AccessibleTextClipType

    typedef enum
    {
      SPI_TEXT_CLIP_NONE,
      SPI_TEXT_CLIP_MIN,
      SPI_TEXT_CLIP_MAX,
      SPI_TEXT_CLIP_BOTH
    } AccessibleTextClipType;

Describes the type of clipping required.

`SPI_TEXT_CLIP_NONE` | No clipping to be done
`SPI_TEXT_CLIP_MIN` | Text clipped by min coordinate is omitted
`SPI_TEXT_CLIP_MAX` | Text clipped by max coordinate is omitted
`SPI_TEXT_CLIP_BOTH` | Only text fully within mix/max bound is retained

### AccessibleText_ref ()

    void        AccessibleText_ref              (AccessibleText *obj);

Increment the reference count for an AccessibleText object.

`obj` : | a pointer to the AccessibleText object on which to operate.

### AccessibleText_unref ()

    void        AccessibleText_unref            (AccessibleText *obj);

Decrement the reference count for an AccessibleText object.

`obj` : | a pointer to the Accessible object on which to operate.

### AccessibleText_addSelection ()

    SPIBoolean  AccessibleText_addSelection     (AccessibleText *obj,
                                                 long int startOffset,
                                                 long int endOffset);

Select some text (add a text selection) in an AccessibleText object.

`obj` : | a pointer to the AccessibleText object on which to operate.
`startOffset` : | the starting offset of the desired new selection.
`endOffset` : | the offset of the first character after the new selection.
Returns : | TRUE if successful, FALSE otherwise.

### AccessibleText_getAttributes ()

    char*       AccessibleText_getAttributes    (AccessibleText *obj,
                                                 long int offset,
                                                 long int *startOffset,
                                                 long int *endOffset);

Get the attributes applied to a range of text from an AccessibleText object, and the bounds of the range. The text attributes correspond to CSS attributes where possible, keys and values are delimited from one another via ":", and the delimiter between key/value pairs is ";". Thus "font-size:10;foreground-color:0,0,0" would be a valid return string.

`obj` : | a pointer to the AccessibleText object to query.
`offset` : | a long integer indicating the offset from which the attribute search is based.
`startOffset` : | a long indicating the start of the desired text range.
`endOffset` : | a long indicating the first character past the desired range.
Returns : | a text string describing the attributes occurring within the attribute run containing `offset`, encoded as UTF-8.

### AccessibleText_getBoundedRanges ()

    AccessibleTextRange** AccessibleText_getBoundedRanges
                                                (AccessibleText *obj,
                                                 long int x,
                                                 long int y,
                                                 long int width,
                                                 long int height,
                                                 AccessibleCoordType type,
                                                 AccessibleTextClipType clipTypeX,
                                                 AccessibleTextClipType clipTypeY);

Get the ranges of text from an AccessibleText object which lie within the bounds defined by (`x`, `y`) and (`x`+`width`, `y`+`height`).

`obj` : | a pointer to the AccessibleText object on which to operate.
`x` : | the 'starting' x coordinate of the bounding box.
`y` : | the 'starting' y coordinate of the bounding box.
`width` : | the x extent of the bounding box.
`height` : | the y extent of the bounding box.
`type` : | an AccessibleCoordType indicating the coordinate system to use for the returned values.
`clipTypeX` : | an AccessibleTextClipType indicating how to treat characters that intersect the bounding box's x extents.
`clipTypeY` : | an AccessibleTextClipType indicating how to treat characters that intersect the bounding box's y extents.
Returns : | a null-terminated list of pointers to AccessibleTextRange structs detailing the bounded text.

### AccessibleText_getCaretOffset ()

    long        AccessibleText_getCaretOffset   (AccessibleText *obj);

Get the current offset of the text caret in an AccessibleText object.

`obj` : | a pointer to the AccessibleText object to query.
Returns : | a long integer indicating the current position of the text caret.

### AccessibleText_getCharacterCount ()

    long        AccessibleText_getCharacterCount
                                                (AccessibleText *obj);

Get the character count of an AccessibleText object.

`obj` : | a pointer to the AccessibleText object to query.
Returns : | a long integer indicating the total number of characters in the AccessibleText object.

### AccessibleText_getCharacterExtents ()

    void        AccessibleText_getCharacterExtents
                                                (AccessibleText *obj,
                                                 long int offset,
                                                 long int *x,
                                                 long int *y,
                                                 long int *width,
                                                 long int *height,
                                                 AccessibleCoordType type);

Get the bounding box containing the glyph representing the character at a particular text offset.

`obj` : | a pointer to the AccessibleText object on which to operate.
`offset` : | an integer indicating the offset of the text character for whom boundary information is requested.
`x` : | a pointer to a long integer into which the nominal x coordinate of the corresponding glyph will be returned.
`y` : | a pointer to a long integer into which the nominal y coordinate of the corresponding glyph will be returned.
`width` : | a pointer to a long integer into which the width of the corresponding glyph will be returned.
`height` : | a pointer to a long integer into which the height of the corresponding glyph will be returned.
`type` : | an AccessibleCoordType indicating the coordinate system to use for the returned values.

### AccessibleText_getNSelections ()

    long        AccessibleText_getNSelections   (AccessibleText *obj);

Get the number of active non-contiguous selections for an AccessibleText object.

`obj` : | a pointer to the AccessibleText object on which to operate.
Returns : | a long integer indicating the current number of non-contiguous text selections active within an AccessibleText object.

### AccessibleText_getOffsetAtPoint ()

    long        AccessibleText_getOffsetAtPoint (AccessibleText *obj,
                                                 long int x,
                                                 long int y,
                                                 AccessibleCoordType type);

Get the bounding box for a glyph at a certain AccessibleText offset.

`obj` : | a pointer to the AccessibleText object on which to operate.
`x` : | the x coordinate of the point to be queried.
`y` : | the y coordinate of the point to be queried.
`type` : | an AccessibleCoordType indicating the coordinate system in which the values should be returned.
Returns : | the offset (as a long integer) at the point (`x`, `y`) in the specified coordinate system.

### AccessibleText_getRangeExtents ()

    void        AccessibleText_getRangeExtents  (AccessibleText *obj,
                                                 long int startOffset,
                                                 long int endOffset,
                                                 long int *x,
                                                 long int *y,
                                                 long int *width,
                                                 long int *height,
                                                 AccessibleCoordType type);

Get the bounding box for text within a range in an AccessibleText object.

`obj` : | a pointer to the AccessibleText object on which to operate.
`startOffset` : | an integer indicating the offset of the first text character for whom boundary information is requested.
`endOffset` : | an integer indicating the offset of the text character after the last character for whom boundary information is requested.
`x` : | a pointer to a long integer into which the nominal x coordinate of the corresponding bounding box will be returned.
`y` : | a pointer to a long integer into which the nominal y coordinate of the corresponding bounding box will be returned.
`width` : | a pointer to a long integer into which the width of the corresponding bounding box will be returned.
`height` : | a pointer to a long integer into which the height of the corresponding bounding box will be returned.
`type` : | an AccessibleCoordType indicating the coordinate system to use for the returned values.

### AccessibleText_getSelection ()

    void        AccessibleText_getSelection     (AccessibleText *obj,
                                                 long int selectionNum,
                                                 long int *startOffset,
                                                 long int *endOffset);

Get the bounds of the `selectionNum`-th active text selection for an AccessibleText object.

`obj` : | a pointer to the AccessibleText object on which to operate.
`selectionNum` : | an integer indicating which selection to query.
`startOffset` : | a pointer to a long integer into which the start offset of the selection will be returned.
`endOffset` : | a pointer to a long integer into which the start offset of the selection will be returned.

### AccessibleText_getText ()

    char*       AccessibleText_getText          (AccessibleText *obj,
                                                 long int startOffset,
                                                 long int endOffset);

Get a range of text from an AccessibleText object. The number of bytes in the returned string may exceed endOffset-startOffset, since UTF-8 is a variable-width encoding.

`obj` : | a pointer to the AccessibleText object to query.
`startOffset` : | a long indicating the start of the desired text range.
`endOffset` : | a long indicating the first character past the desired range.
Returns : | a text string containing characters from `startOffset` to `endOffset`-1, inclusive, encoded as UTF-8.

### AccessibleText_getTextBeforeOffset ()

    char*       AccessibleText_getTextBeforeOffset
                                                (AccessibleText *obj,
                                                 long int offset,
                                                 AccessibleTextBoundaryType type,
                                                 long int *startOffset,
                                                 long int *endOffset);

Get delimited text from an AccessibleText object which precedes a given text offset.

`obj` : | a pointer to the AccessibleText object on which to operate.
`offset` : | a long integer indicating the offset from which the delimiter search is based.
`type` : | an AccessibleTextBoundaryType indicating whether the desired text string is a word, sentence, line, or attribute run.
`startOffset` : | a pointer to a long integer which is assigned the starting offset of the returned string, relative to the original AccessibleText.
`endOffset` : | a pointer to a long integer which is assigned the ending offset of the returned string, relative to the original AccessibleText.
Returns : | a UTF-8 string representing the delimited text, both of whose delimiting boundaries are before the current offset, or an empty string if no such text exists.

### AccessibleText_getTextAfterOffset ()

    char*       AccessibleText_getTextAfterOffset
                                                (AccessibleText *obj,
                                                 long int offset,
                                                 AccessibleTextBoundaryType type,
                                                 long int *startOffset,
                                                 long int *endOffset);

Get delimited text from an AccessibleText object which follows a given text offset.

`obj` : | a pointer to the AccessibleText object on which to operate.
`offset` : | a long integer indicating the offset from which the delimiter search is based.
`type` : | an AccessibleTextBoundaryType indicating whether the desired text string is a word, sentence, line, or attribute run.
`startOffset` : | a pointer to a long integer which is assigned the starting offset of the returned string, relative to the original AccessibleText.
`endOffset` : | a pointer to a long integer which is assigned the ending offset of the returned string, relative to the original AccessibleText.
Returns : | a UTF-8 string representing the delimited text, both of whose delimiting boundaries are after or inclusive of the current offset, or an empty string if no such text exists.

### AccessibleText_getTextAtOffset ()

    char*       AccessibleText_getTextAtOffset  (AccessibleText *obj,
                                                 long int offset,
                                                 AccessibleTextBoundaryType type,
                                                 long int *startOffset,
                                                 long int *endOffset);

Get delimited text from an AccessibleText object which includes a given text offset.

`obj` : | a pointer to the AccessibleText object on which to operate.
`offset` : | a long integer indicating the offset from which the delimiter search is based.
`type` : | an AccessibleTextBoundaryType indicating whether the desired text string is a word, sentence, line, or attribute run.
`startOffset` : | a pointer to a long integer which is assigned the starting offset of the returned string, relative to the original AccessibleText.
`endOffset` : | a pointer to a long integer which is assigned the ending offset of the returned string, relative to the original AccessibleText.
Returns : | a UTF-8 string representing the delimited text, whose delimiting boundaries bracket the current offset, or an empty string if no such text exists.

### AccessibleText_removeSelection ()

    SPIBoolean  AccessibleText_removeSelection  (AccessibleText *obj,
                                                 long int selectionNum);

De-select a text selection.

`obj` : | a pointer to the AccessibleText object on which to operate.
`selectionNum` : | an integer indicating which (possibly of several) text selection to remove.
Returns : | TRUE if successful, FALSE otherwise.

### AccessibleText_setCaretOffset ()

    SPIBoolean  AccessibleText_setCaretOffset   (AccessibleText *obj,
                                                 long int newOffset);

Set the text caret position for an AccessibleText object.

`obj` : | a pointer to the AccessibleText object on which to operate.
`newOffset` : | the offset to which the text caret is to be moved.
Returns : | TRUE if successful, FALSE otherwise.

### AccessibleText_setSelection ()

    SPIBoolean  AccessibleText_setSelection     (AccessibleText *obj,
                                                 long int selectionNum,
                                                 long int startOffset,
                                                 long int endOffset);

Change the bounds of an existing AccessibleText text selection.

`obj` : | a pointer to the AccessibleText object on which to operate.
`selectionNum` : | a zero-offset index indicating which text selection to modify.
`startOffset` : | a long int, the new starting offset for the selection.
`endOffset` : | a long int, the desired new offset of the first character after the selection.
Returns : | TRUE if successful, FALSE otherwise.

### AccessibleTextRange_freeRanges ()

    void        AccessibleTextRange_freeRanges  (AccessibleTextRange **ranges);

Free the memory used by a list of AccessibleTextRange structs. The argument passed in should be an array of pointers AccessibleTextRange structs.

`ranges` : | a pointer to an array of AccessibleTextRange structs.