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);
unsigned long       AccessibleText_getCharacterAtOffset (AccessibleText *obj,
                                                         long int offset);
char*               AccessibleText_getDefaultAttributes (AccessibleText *obj);
AccessibleAttributeSet* AccessibleText_getAttributeRun  (AccessibleText *obj,
                                                         long int offset,
                                                         long int *startOffset,
                                                         long int *endOffset,
                                                         long int includeDefaults);
AccessibleAttributeSet* AccessibleText_getDefaultAttributeSet
                                                        (AccessibleText *obj);
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.

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.

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

Since: AT-SPI 1.2

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.

Since: AT-SPI 1.2

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.

AccessibleText_getCharacterAtOffset ()

unsigned long       AccessibleText_getCharacterAtOffset (AccessibleText *obj,
                                                         long int offset);

Get the character at a given offset for an AccessibleText object.

obj : a pointer to the AccessibleText object on which to operate.
offset : a long integer indicating the text offset where the desired character is located.
Returns : an unsigned long integer which represents the UCS-4 unicode code point of the given character, or 0xFFFFFFFF if the character in question cannot be represented in the UCS-4 encoding.

AccessibleText_getDefaultAttributes ()

char*               AccessibleText_getDefaultAttributes (AccessibleText *obj);

Get the default attributes applied to an AccessibleText object. 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. The combination of this attribute set and the attributes reported by AccessibleText_getAttributes describes the entire set of text attributes over a range.

Since: AT-SPI 1.4

obj : a pointer to the AccessibleText object to query.
Returns : a text string describing the default attributes applied to a text object, (exclusive of explicitly-set attributes), encoded as UTF-8.

AccessibleText_getAttributeRun ()

AccessibleAttributeSet* AccessibleText_getAttributeRun  (AccessibleText *obj,
                                                         long int offset,
                                                         long int *startOffset,
                                                         long int *endOffset,
                                                         long int includeDefaults);

Since: AT-SPI 1.7

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.
includeDefaults : a bool if False, the call should only return those attributes which are explicitly set on the current attribute run, omitting any attributes which are inherited from the default values.
Returns : the AttributeSet defined at offset, optionally including the 'default' attributes.

AccessibleText_getDefaultAttributeSet ()

AccessibleAttributeSet* AccessibleText_getDefaultAttributeSet
                                                        (AccessibleText *obj);

Since: AT-SPI 1.7

obj : a pointer to the AccessibleText object to query.
Returns : an AttributeSet containing the text attributes which apply to all text in the object by virtue of the default settings of the document, view, or user agent; e.g. those attributes which are implied rather than explicitly applied to the text object. For instance, an object whose entire text content has been explicitly marked as 'bold' will report the 'bold' attribute via getAttributeRun(), whereas an object whose text weight is inspecified may report the default or implied text weight in the default AttributeSet.

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.

Since: AT-SPI 1.2

ranges : a pointer to an array of AccessibleTextRange structs.