Interface XAccessibleText

Attributes' Summary

Attributes' Details

:: com :: sun :: star :: accessibility ::

interface XAccessibleText

Description

Implement this interface to give read-only access to a text.

The XAccessibleText interface should be implemented by all UNO components that present textual information on the display like buttons, text entry fields, or text portions of the document window. The interface provides access to the text's content, attributes, and spatial location. However, text can not be modified with this interface. That is the task of the XAccessibleEditableText interface.

The text length, i.e. the number of characters in the text, is returned by getCharacterCount. All methods that operate on particular characters (e.g. getCharacterAt) use character indices from 0 to length-1. All methods that operate on character positions (e.g. getTextRange) use indices from 0 to length.

Please note that accessible text does not necessarily support selection. In this case it should behave as if there where no selection. An empty selection is used for example to express the current cursor position.

Since

OOo 1.1.2

Developers Guide: Accessibility - XAccessibleText

Methods' Summary
getCaretPosition	Return the position of the caret.
setCaretPosition	Set the position of the caret.
getCharacter	Return the character at the specified position.
getCharacterAttributes	Get the attribute set for the specified position.
getCharacterBounds	Return the bounding box of the specified position.
getCharacterCount	Return the number of characters in the represented text.
getIndexAtPoint	Return the text position for the specified screen position.
getSelectedText	Return the selected text.
getSelectionStart	Return the position of the start of the selection.
getSelectionEnd	Return the position of the end of the selection.
setSelection	Set a new selection.
getText	Return the whole text.
getTextRange	Return the specified text range.
getTextAtIndex	Get a text portion around the given position.
getTextBeforeIndex	Get a text portion before the given position.
getTextBehindIndex	Get a text portion behind the given position.
copyText	Copy the specified text into the clipboard.

Methods' Details

getCaretPosition

long
getCaretPosition();

Description: Return the position of the caret.; Returns the offset of the caret. The caret is often called text cursor. The caret is actually the position between two characters. Its position/offset is that of the character to the right of it.
Returns: The returned offset is relative to the text represented by this object.

setCaretPosition

boolean
setCaretPosition(	[in] long	nIndex )
raises(	::com::sun::star::lang::IndexOutOfBoundsException );

Description

Set the position of the caret.

The caret is often called text cursor. The caret is actually the position between two characters. Its position/offset is that of the character to the right of it.

Setting the caret position may or may not alter the current selection. A change of the selection is notified to the accessibility event listeners with an AccessibleEventId::ACCESSIBLE_SELECTION_EVENT.

When the new caret position differs from the old one (which, of course, is the standard case) this is notified to the accessibility event listeners with an AccessibleEventId::ACCESSIBLE_CARET_EVENT.

Parameter nIndex

The new index of the caret. This caret is actually placed to the left side of the character with that index. An index of 0 places the caret so that the next insertion goes before the first character. An index of getCharacterCount leads to insertion after the last character.

Returns

Returns true if the caret has been moved and false otherwise. A true value does not necessarily mean that the caret has been positioned exactly at the required position. If that position lies inside a read-only area the caret is positioned before or behind it. Listen to the caret event to determine the new position.

Throws

::com::sun::star::lang::IndexOutOfBoundsException if the index is not valid.

getCharacter

char
getCharacter(	[in] long	nIndex )
raises(	::com::sun::star::lang::IndexOutOfBoundsException );

Description: Return the character at the specified position.; Returns the character at the given index.
Parameter nIndex: The index of the character to return. The valid range is 0..length-1.
Returns: the character at the index nIndex.
Throws: ::com::sun::star::lang::IndexOutOfBoundsException if the index is invalid

getCharacterAttributes

sequence< ::com::sun::star::beans::PropertyValue >
getCharacterAttributes(	[in] long	nIndex,
	[in] sequence< string >	aRequestedAttributes )
raises(	::com::sun::star::lang::IndexOutOfBoundsException );

Description: Get the attribute set for the specified position.; Returns a set of attributes that are associated for the character at the given index. To prevent the method from returning possibly large sets of attributes that the caller is not interested in the caller has to provide a list of attributes that he wants to be returned.
Parameter nIndex: The index of the character for which to return its attributes. The valid range is 0..length-1.
Parameter aRequestedAttributes: This string sequence defines the set of attributes that the caller is interested in. When there are attributes defined that are not listed in the sequence then they are not returned. When there are requested attributes that are not defined for the character then they are ignored, too.
An empty sequence signals the callers interest in all the attributes. This is useful in two cases: a) Simply as a way to avoid passing a potentially large array to the called object or b) when the caller does not know what attributes the called objects supports but is interested in all of them nevertheless.
Returns: Returns the explicitly or implicitly (empty aRequestedAttributes argument) requested attributes of the specified character. Each attribute is represented by a ::com::sun::star::beans::PropertyValue object. The returned list of attribute descriptions contains all attributes that are both members of the sequence of requested attributes and are defined for the character at the specified index.
Throws: ::com::sun::star::lang::IndexOutOfBoundsException if the index is invalid

getCharacterBounds

::com::sun::star::awt::Rectangle
getCharacterBounds(	[in] long	nIndex )
raises(	::com::sun::star::lang::IndexOutOfBoundsException );

Description

Return the bounding box of the specified position.

Returns the bounding box of the indexed character.

The virtual character after the last character of the represented text, i.e. the one at position length is a special case. It represents the current input position and will therefore typically be queried by AT more often than other positions. Because it does not represent an existing character its bounding box is defined in relation to preceding characters. It should be roughly equivalent to the bounding box of some character when inserted at the end of the text. Its height typically being the maximal height of all the characters in the text or the height of the preceding character, its width being at least one pixel so that the bounding box is not degenerate.
Note that the index "length" is not always valid. Whether it is or not is implementation dependent. It typicall