The interface XAccessibleText handles read-only text. It serves three purposes: to obtain certain parts of a text, to obtain the text's size and location on the screen, and to handle the caret position. An accessibility object that implements this interface usually represents only a part of a larger text. Typically, this is a single or a small number of paragraphs. You can use the relation types CONTENT_FLOWS_FROM and CONTENT_FLOWS_TO to explicitly represent the text flow from one text part to another. Without these relations, the text flow has to be determined from the structure of the accessibility tree alone.
Represented text may contain a selected text portion, which is typically displayed highlighted (inverse). There are four functions to access and modify the selection. The selected text, as well as its start and end index, can be accessed with the getSelectedText(), getSelectionStart() and getSelectionEnd() functions respectively. To modify the selection, call setSelection() with the new start and end indices.
The functions getTextAtIndex(), getTextBeforeIndex() and getTextBehindIndex() return parts of the text where the part or length of text returned is specified by the text type. Defined in the com.sun.star.accessibility.AccessibleTextType constants collection, some of these text types further explanation:
- The type LINE indicates all text on a single line as it is displayed on the screen. This may include a hyphen at the line end. The hyphen is not actually part of the text, but is visible on the screen. They are only included in text parts of type LINE.
- Glyph is used in this context to mean that everything between two adjacent cursor positions is considered to be a glyph. In Thai, for example, you can stack up to four (Unicode) characters upon each other. When moving with the cursor keys, those character groups are interpreted as single glyphs, and the cursor can only be set in front or after such glyphs, but not inside.
- The definition of words, sentences and paragraphs are implementation and locale dependent.
- An attribute run is a sequence of characters of maximal length, where all characters have the same attributes. For example the text "This is an example" consists of three attribute runs: "This", "is an" and "example". The first and last one each have only a single attribute, italic respectively bold. The second run has both attributes at the same time. Note that all three spaces belong to one of the attribute runs.
There are other functions to access text. To retrieve the whole text represented by an object, use getText(). Call getTextRange() to get only a part of text between and including two given indices. A single character can be accessed with the getCharacter() function.
To copy a text range to the clipboard, call the copyText() function. See also the related cutText() and pasteText() functions of the com.sun.star.accessibility.XAccessibleEditableText interface.
Caret and Text Indices
The caret is often referred to as the cursor and is typically displayed as a vertical line. On the screen, it is always placed between two adjacent glyphs, or at the beginning or the end of a text line. When specifying its position in terms of character positions, the position of the character to its right is used. Thus, the index 0 says that the caret is at the very beginning of the text. When the caret is located behind the last character, then its position equals the text length, that is, the number of characters of the text as returned by getCharacterCount().
When the caret changes its position, an event must be sent to all listeners so that the old and new position can be indicated.
Other index-related functions are getCharacterAttributes(), which returns the attributes at the specified index, getCharacterBounds(), which returns the bounding box of the character at the specified index, and getIndexAtPoint(), which returns the index of the character at the specified position.
|Content on this page is licensed under the Public Documentation License (PDL).|