AccessibleText Interface

AccessibleText Interface

Functions

Types and Values

Description

Functions

AccessibleText_ref ()

void
AccessibleText_ref (AccessibleText *obj);

Increment the reference count for an AccessibleText object.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

ranges

a pointer to an array of AccessibleTextRange structs.

 

Types and Values

enum AccessibleTextBoundaryType

Text boundary types used for specifying boundaries for regions of text.

Members

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

Describes the type of clipping required.

Members

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