Main Page   Namespace List   Class Hierarchy   Data Structures   File List   Namespace Members   Data Fields  

Accessibility::Text Interface Reference

import "Accessibility_Text.idl";

Inheritance diagram for Accessibility::Text:

Accessibility::EditableText

Public Types

typedef sequence< RangeRangeList

Public Methods

string getText (in long startOffset, in long endOffset)
boolean setCaretOffset (in long offset)
string getTextBeforeOffset (in long offset, in TEXT_BOUNDARY_TYPE type, out long startOffset, out long endOffset)
string getTextAtOffset (in long offset, in TEXT_BOUNDARY_TYPE type, out long startOffset, out long endOffset)
string getTextAfterOffset (in long offset, in TEXT_BOUNDARY_TYPE type, out long startOffset, out long endOffset)
unsigned long getCharacterAtOffset (in long offset)
string getAttributeValue (in long offset, in string attributeName, out long startOffset, out long endOffset, out boolean defined)
string getAttributes (in long offset, out long startOffset, out long endOffset)
string getDefaultAttributes ()
void getCharacterExtents (in long offset, out long x, out long y, out long width, out long height, in short coordType)
long getOffsetAtPoint (in long x, in long y, in short coordType)
long getNSelections ()
void getSelection (in long selectionNum, out long startOffset, out long endOffset)
boolean addSelection (in long startOffset, in long endOffset)
boolean removeSelection (in long selectionNum)
boolean setSelection (in long selectionNum, in long startOffset, in long endOffset)
void getRangeExtents (in long startOffset, in long endOffset, out long x, out long y, out long width, out long height, in short coordType)
RangeList getBoundedRanges (in long x, in long y, in long width, in long height, in short coordType, in TEXT_CLIP_TYPE xClipType, in TEXT_CLIP_TYPE yClipType)
void unImplemented ()
void unImplemented2 ()
void unImplemented3 ()
void unImplemented4 ()

Data Fields

readonly attribute long characterCount
readonly attribute long caretOffset

Detailed Description

The text interface should be implemented by objects which place textual information onscreen as character strings or glyphs. The text interface allows access to textual content, including display attributes and semantic hints associated with runs of text, and access to bounding box information for glyphs and substrings. It also allows portions of textual content to be selected, if the object's StateSet includes STATE_SELECTABLE_TEXT.

In some cases a Text object may have, as its content, an empty string. In particular this can occur in the case of Hypertext objects which do not display explicitly textual information onscreen, as Hypertext is derived from the Text interface.

See also:
Hypertext.
Typographic and semantic attributes of onscreen textual content, for instance typeface, weight, language, and such qualities as 'emphasis' or 'blockquote', are represented as text attributes. Contiguous sequences of characters over which these attributes are unchanged are referred to as "attribute runs", and are available via Text::getAttributeRun. Where possible, implementing clients will report textual attributes which are the same over the entire text object, for instance those inherited from a default or document-scope style, via getDefaultAttributes instead of reporting them explicitly for each character. Therefore, for any span of text, the attributes in effect are the union of the set returned by Text::getDefaultAttributes, and the set returned at a particular character offset via Text::getAttributeRun.

Note:
Events that may be emitted by instances of Text include:
Note:
In some cases, objects which are not onscreen may implement Text, but if such objects implement Component, their potential visibility should be examined (via comparison with STATE_VISIBLE and STATE_SHOWING) before exposing them to the user. Objects which implement Text but not Component may be encountered in special-purpose interfaces or as special ¨accessibility¨ extensions to visual interfaces to allow non-graphical access to application features. These instances should be considered the exception, rather than the rule.


Member Typedef Documentation

typedef sequence<Range> Accessibility::Text::RangeList
 


Member Function Documentation

boolean Accessibility::Text::addSelection in long    startOffset,
in long    endOffset
 

The result of calling addSelection on objects which already have one selection present, and which do not include STATE_MULTISELECTABLE, is undefined, other than the return value.

Returns :
True of the selection was successfully added, False otherwise. Selection may fail if the object does not support selection of text (see STATE_SELECTABLE_TEXT), if the object does not support multiple selections and a selection is already defined, or for other reasons (for instance if the user does not have permission to copy the text into the relevant selection buffer).

string Accessibility::Text::getAttributes in long    offset,
out long    startOffset,
out long    endOffset
 

getAttributes is deprecated in favor of getAttributeRun.

Returns :
the attributes at offset, as a semicolon-delimited set of colon-delimited name-value pairs.
See also:
getAttributeRun

string Accessibility::Text::getAttributeValue in long    offset,
in string    attributeName,
out long    startOffset,
out long    endOffset,
out boolean    defined
 

Get the string value of a named attribute at a given offset, if defined.

Parameters:
offset  the offset of the character for which the attribute run is to be obtained.
attributeName  the name of the attribute for which the value is to be returned, if defined.
startOffset  back-filled with the offset of the first character in the attribute run containing the character at offset.
endOffset  back-filled with the offset of the first character past the end of the attribute run containing the character at offset.
defined  back-filled with True if the attributeName has a defined value at offset, False otherwise.
Returns :
the value of attribute (name-value pair) corresponding to "name", if defined.

RangeList Accessibility::Text::getBoundedRanges in long    x,
in long    y,
in long    width,
in long    height,
in short    coordType,
in TEXT_CLIP_TYPE    xClipType,
in TEXT_CLIP_TYPE    yClipType
 

Return the text content within a bounding box, as a list of Range structures. Depending on the TEXT_CLIP_TYPE parameters, glyphs which are clipped by the bounding box (i.e. which lie partially inside and partially outside it) may or may not be included in the ranges returned.

Note:
This method may be of particular interest to screen review algorithms.
See also:
TEXT_CLIP_TYPE.
Parameters:
x  the minimum x ( i.e. leftmost) coordinate of the bounding box.
y  the minimum y coordinate of the bounding box.
width  the horizontal size of the bounding box. The rightmost bound of the bounding box is (x + width);
height  the vertical size of the bounding box. The maximum y value of the bounding box is (y + height);
coordType  If 0, the above coordinates are interpreted as pixels relative to corner of the screen; if 1, the coordinates are interpreted as pixels relative to the corner of the containing toplevel window.
xClipType  determines whether text which intersects the bounding box in the x direction is included.
yClipType  determines whether text which intersects the bounding box in the y direction is included.

unsigned long Accessibility::Text::getCharacterAtOffset in long    offset
 

Returns :
an unsigned long integer whose value corresponds to the UCS-4 representation of the character at the specified text offset, or 0 if offset is out of range.

void Accessibility::Text::getCharacterExtents in long    offset,
out long    x,
out long    y,
out long    width,
out long    height,
in short    coordType
 

Obtain a the bounding box, as x, y, width, and height, of the character or glyph at a particular character offset in this object's text content. The coordinate system in which the results are reported is specified by coordType. If an onscreen glyph corresponds to multiple character offsets, for instance if the glyph is a ligature, the bounding box reported will include the entire glyph and therefore may apply to more than one character offset.

Parameters:
offset  the character offset of the character or glyph being queried.
x  the minimum horizontal coordinate of the bounding box of the glyph representing the character at offset.
y  the minimum vertical coordinate of the bounding box of the glyph representing the character at offset.
width  the horizontal extent of the bounding box of the glyph representing the character at offset.
height  the vertical extent of the bounding box of the glyph representing the character at offset.
coordType  If 0, the results will be reported in screen coordinates, i.e. in pixels relative to the upper-left corner of the screen, with the x axis pointing right and the y axis pointing down. If 1, the results will be reported relative to the containing toplevel window, with the x axis pointing right and the y axis pointing down.

string Accessibility::Text::getDefaultAttributes  
 

Deprecated in favor of getDefaultAttributeSet.

Returns :
the attributes which apply to the entire text content, but which were not explicitly specified by the content creator.
See also:
getDefaultAttributeSet

long Accessibility::Text::getNSelections  
 

Obtain the number of separate, contiguous selections in the current Text object. Text objects which do not implement selection of discontiguous text regions will always return '0' or '1'. Note that "contiguous" is defined by continuity of the offsets, i.e. a text 'selection' is defined by a start/end offset pair. In the case of bidirectional text, this means that a continguous selection may appear visually discontiguous, and vice-versa.

Returns :
the number of contiguous selections in the current Text object.

long Accessibility::Text::getOffsetAtPoint in long    x,
in long    y,
in short    coordType
 

Get the offset of the character at a given onscreen coordinate. The coordinate system used to interpret x and y is determined by parameter coordType.

Parameters:
x 
y 
coordType  if 0, the input coordinates are interpreted relative to the entire screen, if 1, they are relative to the toplevel window containing this Text object.
Returns :
the text offset (as an offset into the character array) of the glyph whose onscreen bounds contain the point x,y, or -1 if the point is outside the bounds of any glyph.

void Accessibility::Text::getRangeExtents in long    startOffset,
in long    endOffset,
out long    x,
out long    y,
out long    width,
out long    height,
in short    coordType
 

Obtain the bounding box which entirely contains a given text range. Negative values may be returned for the bounding box parameters in the event that all or part of the text range is offscreen or not mapped to the screen.

Parameters:
startOffset  the offset of the first character in the specified range.
endOffset  the offset of the character immediately after the last character in the specified range.
x  an integer parameter which is back-filled with the minimum horizontal coordinate of the resulting bounding box.
y  an integer parameter which is back-filled with the minimum vertical coordinate of the resulting bounding box.
width  an integer parameter which is back-filled with the horizontal extent of the bounding box.
height  an integer parameter which is back-filled with the vertical extent of the bounding box.
coordType  If 0, the above coordinates are reported in pixels relative to corner of the screen; if 1, the coordinates are reported relative to the corner of the containing toplevel window.

void Accessibility::Text::getSelection in long    selectionNum,
out long    startOffset,
out long    endOffset
 

The result of calling getSelection with an out-of-range selectionNum (i.e. for a selection which does not exist) is not strictly defined, but should set endOffset equal to startOffset.

string Accessibility::Text::getText in long    startOffset,
in long    endOffset
 

Obtain all or part of the onscreen textual content of a Text object. If endOffset is specified as "-1", then this method will return the entire onscreen textual contents of the Text object.

Note:
'onscreen' in this context means "potentially onscreen", this method does not perform any sort of coordinate visibility clipping or window-stack-ordering clipping. The text thus reported corresponds to the text which would be presented onscreen if the object implementing the Text interface were entirely unobscured.
Returns :
the textual content of the current Text object beginning startOffset (inclusive) up to but not including the character at endOffset.

string Accessibility::Text::getTextAfterOffset in long    offset,
in TEXT_BOUNDARY_TYPE    type,
out long    startOffset,
out long    endOffset
 

Obtain a subset of the text content of an object which entirely follows offset, delimited by character, word, line, or sentence boundaries as specified by type. The starting and ending offsets of the resulting substring are returned in startOffset and endOffset. By definition, if such a substring exists, startOffset must be greater than offset.

Parameters:
offset  the offset from which the substring search begins, and which must lie before the returned substring.
type  the text-boundary delimiter which determines whether the returned text constitures a character, word, line, or sentence (and possibly attendant whitespace), and whether the start or ending of such a substring forms the boundary condition.
startOffset  back-filled with the starting offset of the resulting substring, if one exists.
endOffset  back-filled with the offset of the character immediately following the resulting substring, if one exists.
See also:
TEXT_BOUNDARY_TYPE
Returns :
a string which is a substring of the text content of the object, delimited by the specified boundary condition.

string Accessibility::Text::getTextAtOffset in long    offset,
in TEXT_BOUNDARY_TYPE    type,
out long    startOffset,
out long    endOffset
 

Obtain a subset of the text content of an object which includes the specified offset, delimited by character, word, line, or sentence boundaries as specified by type. The starting and ending offsets of the resulting substring are returned in startOffset and endOffset.

Parameters:
offset  the offset from which the substring search begins, and which must lie within the returned substring.
type  the text-boundary delimiter which determines whether the returned text constitures a character, word, line, or sentence (and possibly attendant whitespace), and whether the start or ending of such a substring forms the boundary condition.
startOffset  back-filled with the starting offset of the resulting substring, if one exists.
endOffset  back-filled with the offset of the character immediately following the resulting substring, if one exists.
See also:
TEXT_BOUNDARY_TYPE
Returns :
a string which is a substring of the text content of the object, delimited by the specified boundary condition.

string Accessibility::Text::getTextBeforeOffset in long    offset,
in TEXT_BOUNDARY_TYPE    type,
out long    startOffset,
out long    endOffset
 

Obtain a subset of the text content of an object which entirely precedes offset, delimited by character, word, line, or sentence boundaries as specified by type. The starting and ending offsets of the resulting substring are returned in startOffset and endOffset. By definition, if such a substring exists, endOffset is less than or equal to offset.

Parameters:
offset  the offset from which the substring search begins.
type  the text-boundary delimiter which determines whether the returned text constitures a character, word, line, or sentence (and possibly attendant whitespace), and whether the start or ending of such a substring forms the boundary condition.
startOffset  back-filled with the starting offset of the resulting substring, if one exists.
endOffset  back-filled with the offset of the character immediately following the resulting substring, if one exists.
See also:
TEXT_BOUNDARY_TYPE
Returns :
a string which is a substring of the text content of the object, delimited by the specified boundary condition.

boolean Accessibility::Text::removeSelection in long    selectionNum
 

Deselect the text contained in the specified selectionNum, if such a selection exists, otherwise do nothing. Removal of a non-existant selectionNum has no effect.

Returns :
True if the selection was successfully removed, False otherwise.

boolean Accessibility::Text::setCaretOffset in long    offset
 

Programmatically move the text caret (visible or virtual, as above) to a given position.

Parameters:
offset  a long int indicating the desired character offset. Not all implementations of Text will honor setCaretOffset requests, so the return value below should be checked by the client.
Returns :
TRUE if the request was carried out, or FALSE if the caret could not be moved to the requested position.

boolean Accessibility::Text::setSelection in long    selectionNum,
in long    startOffset,
in long    endOffset
 

Modify an existing selection's start or ending offset.

Calling setSelection for a selectionNum that is not already defined has no effect. The result of calling setSelection with a selectionNum greater than 0 for objects that do not include STATE_MULTISELECTABLE is undefined.

Parameters:
selectionNum  indicates which of a set of non-contiguous selections to modify.
startOffset  the new starting offset for the selection
endOffset  the new ending offset for the selection
Returns :
True if the selection corresponding to selectionNum is successfully modified, False otherwise.

void Accessibility::Text::unImplemented  
 

\cond unImplemented:

placeholders for future expansion.

void Accessibility::Text::unImplemented2  
 

void Accessibility::Text::unImplemented3  
 

void Accessibility::Text::unImplemented4  
 


Field Documentation

readonly attribute long Accessibility::Text::caretOffset
 

The current offset of the text caret in the Text object. This caret may be virtual, e.g. non-visual and notional-only, but if an onscreen representation of the caret position is visible, it will correspond to this offset. The caret offset is given as a character offset, as opposed to a byte offset into a text buffer or a column offset.

readonly attribute long Accessibility::Text::characterCount
 

The total current number of characters in the Text object, including whitespace and non-spacing characters.


The documentation for this interface was generated from the following file:
Generated on Thu Mar 23 17:40:30 2006 for at-spi-idl by doxygen1.2.17