|
HRESULT | addSelection ([in] long startOffset,[in] long endOffset) |
| Adds a text selection. More...
|
|
HRESULT | attributes ([in] long offset,[out] long *startOffset,[out] long *endOffset,[out, retval] BSTR *textAttributes) |
| Returns text attributes. More...
|
|
HRESULT | caretOffset ([out, retval] long *offset) |
| Returns the position of the caret. More...
|
|
HRESULT | characterExtents ([in] long offset,[in] enum IA2CoordinateType coordType,[out] long *x,[out] long *y,[out] long *width,[out, retval] long *height) |
| Returns the bounding box of the specified position. More...
|
|
HRESULT | nSelections ([out, retval] long *nSelections) |
| Returns the number of active non-contiguous selections. More...
|
|
HRESULT | offsetAtPoint ([in] long x,[in] long y,[in] enum IA2CoordinateType coordType,[out, retval] long *offset) |
| Returns the text position for the specified screen position. More...
|
|
HRESULT | selection ([in] long selectionIndex,[out] long *startOffset,[out, retval] long *endOffset) |
| Returns the character offsets of Nth active text selection. More...
|
|
HRESULT | text ([in] long startOffset,[in] long endOffset,[out, retval] BSTR *text) |
| Returns the substring between the two given indices. More...
|
|
HRESULT | textBeforeOffset ([in] long offset,[in] enum IA2TextBoundaryType boundaryType,[out] long *startOffset,[out] long *endOffset,[out, retval] BSTR *text) |
| Returns a text portion before the given position. More...
|
|
HRESULT | textAfterOffset ([in] long offset,[in] enum IA2TextBoundaryType boundaryType,[out] long *startOffset,[out] long *endOffset,[out, retval] BSTR *text) |
| Returns a text portion after the given position. More...
|
|
HRESULT | textAtOffset ([in] long offset,[in] enum IA2TextBoundaryType boundaryType,[out] long *startOffset,[out] long *endOffset,[out, retval] BSTR *text) |
| Returns a text portion that spans the given position. More...
|
|
HRESULT | removeSelection ([in] long selectionIndex) |
| Unselects a range of text. More...
|
|
HRESULT | setCaretOffset ([in] long offset) |
| Sets the position of the caret. More...
|
|
HRESULT | setSelection ([in] long selectionIndex,[in] long startOffset,[in] long endOffset) |
| Changes the bounds of an existing selection. More...
|
|
HRESULT | nCharacters ([out, retval] long *nCharacters) |
| Returns total number of characters. More...
|
|
HRESULT | scrollSubstringTo ([in] long startIndex,[in] long endIndex,[in] enum IA2ScrollType scrollType) |
| Makes a specific part of string visible on screen. More...
|
|
HRESULT | scrollSubstringToPoint ([in] long startIndex,[in] long endIndex,[in] enum IA2CoordinateType coordinateType,[in] long x,[in] long y) |
| Moves the top left of a substring to a specified location. More...
|
|
HRESULT | newText ([out, retval] IA2TextSegment *newText) |
| Returns any inserted text. More...
|
|
HRESULT | oldText ([out, retval] IA2TextSegment *oldText) |
| Returns any removed text. More...
|
|
This interface gives read-only access to text.
The IAccessibleText interface should be implemented by all 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 IAccessibleEditableText interface.
The text length, i.e. the number of characters in the text, is returned by IAccessibleText::nCharacters. All methods that operate on particular characters (e.g. IAccessibleText::textAtOffset) use character indices from 0 to length-1. All methods that operate on character positions (e.g. IAccessibleText::text) 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.
Refer to Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods for information about special offsets that can be used in IAccessibleText methods.
E_FAIL is returned in the following cases
- endOffset < startOffset
- endoffset > length
HRESULT IAccessibleText::caretOffset |
( |
[out, retval] long * |
offset | ) |
|
|
get |
Returns the position of the caret.
Returns the 0-based offset of the caret within the text. If the text is implemented as a tree of text objects with embed characters in higher levels representing substrings of child text objects and the caret is in one of the child text objects, then the offset in the higher level text object would be at the embed character representing child text object that contains the caret.
For example, if the string "one two three" is implemented as a two text objects, with a top level text object containing an embed character "one ? three" and a child text object containing "two" and if the caret is in the descendant object just before the 'o' in "two", then:
-
the caretOffset for the "one ? three" object would be 4, matching the embed character
-
the caretOffset for "two" would be 2, matching the "o"
The caret position/offset is that of the character logically following it, e.g. to the right of it in a left to right language, or to the left of it in a right to left language.
- Parameters
-
[out] | offset | The returned offset is relative to the text represented by this object. |
- Return values
-
S_OK | |
S_FALSE | if the caret is not currently active on this object, i.e. the caret is located on some other object. The returned offset value will be -1. |
- Note
- S_FALSE (and an offset of -1) will not be returned if the caret is somewhere in the text object or one of its descendants.
HRESULT IAccessibleText::selection |
( |
[in] long |
selectionIndex, |
|
|
[out] long * |
startOffset, |
|
|
[out, retval] long * |
endOffset |
|
) |
| |
|
get |
Returns the character offsets of Nth active text selection.
Returns the 0-based starting and ending offsets of the Nth selection. If the text is implemented as a tree of text objects with embed characters in higher levels representing substrings of child text objects, consider the following. If the starting selection offset is in one of the child text objects, then the starting offset in the higher level text object would be at the embed character representing the child text object that contains the starting selection offset. If the ending selection offset is in one of the child text objects, then the ending offset in the higher level text object would be just after the embed character representing the child text object that contains the ending selection offset.
For example, if the string "one two three" is implemented as a two text objects, with a top level text object containing an embed character "one ? three" and a child text object containing "two" and if the selection is the string "two" then:
-
the startOffset for the "one ? three" object would be 4, matching the embed character and the endOffset would be 5.
-
the startOffset for the "two" object would be 0, and the endOffset would be 3
Selection offsets are that of the character logically following it, e.g. to the right of it in a left to right language or to the left of it in a right to left language.
- Parameters
-
[in] | selectionIndex | Index of selection (0 based). |
[out] | startOffset | 0 based offset of first selected character |
[out] | endOffset | 0 based offset of one past the last selected character. |
- Return values
-
S_OK | |
E_INVALIDARG | if bad [in] passed |
HRESULT IAccessibleText::textAfterOffset |
( |
[in] long |
offset, |
|
|
[in] enum IA2TextBoundaryType |
boundaryType, |
|
|
[out] long * |
startOffset, |
|
|
[out] long * |
endOffset, |
|
|
[out, retval] BSTR * |
text |
|
) |
| |
|
get |
Returns a text portion after the given position.
Returns the substring of the specified text type that is located after the given character and does not include it. The result of this method should be same as a result for IAccessibleText::textAtOffset with a suitably increased index value.
For example, if text type is IA2_TEXT_BOUNDARY_WORD, then the complete word that is closest to and located after offset is returned.
If the index is valid, but no text is found, S_FALSE is returned along with out values of 0, 0, and a NULL pointer. This would happen for boundary types other than character when the text consists entirely of whitespace.
- Parameters
-
[in] | offset | Index of the character for which to return the text part after it. The index character will not be part of the returned string. The valid range is 0..length. Refer to Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods for information about special offsets that can be used in IAccessibleText methods. |
[in] | boundaryType | The type of the text portion to return. See IA2TextBoundaryType for the complete list. |
[out] | startOffset | 0 based offset of first character. |
[out] | endOffset | 0 based offset of one past the last character. |
[out] | text | Returns the requested text portion. This portion may be empty or invalid when no appropriate text portion is found or text type is invalid. |
- Return values
-
S_OK | |
S_FALSE | if the requested boundary type is not implemented, such as IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return; [out] values are 0s and NULL respectively |
E_INVALIDARG | if bad [in] passed |
HRESULT IAccessibleText::textAtOffset |
( |
[in] long |
offset, |
|
|
[in] enum IA2TextBoundaryType |
boundaryType, |
|
|
[out] long * |
startOffset, |
|
|
[out] long * |
endOffset, |
|
|
[out, retval] BSTR * |
text |
|
) |
| |
|
get |
Returns a text portion that spans the given position.
Returns the substring defined by the specified boundary type at the specified offset. Refer to IA2TextBoundaryType for more details.
For the word boundary type the returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word. All offsets from the first to the last characters of a word are considered inside the word. Boundary types of sentence and paragraph should exhibit similar behavior.
If the index is valid, but no text is found, S_FALSE is returned along with out values of 0, 0, and a NULL pointer. This would happen for boundary types other than character when the text consists entirely of whitespace.
- Parameters
-
[in] | offset | Index of the character for which to return the text part it belongs to. The valid range is 0..length. Refer to Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods for information about special offsets that can be used in IAccessibleText methods. |
[in] | boundaryType | The type of the text portion to return. See IA2TextBoundaryType for the complete list. |
[out] | startOffset | 0 based offset of first character. |
[out] | endOffset | 0 based offset of one past the last character. |
[out] | text | Returns the requested text portion. This portion may be empty or invalid when no appropriate text portion is found or text type is invalid. |
- Return values
-
S_OK | |
S_FALSE | if the requested boundary type is not implemented, such as IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return; [out] values are 0s and NULL respectively |
E_INVALIDARG | if bad [in] passed |
HRESULT IAccessibleText::textBeforeOffset |
( |
[in] long |
offset, |
|
|
[in] enum IA2TextBoundaryType |
boundaryType, |
|
|
[out] long * |
startOffset, |
|
|
[out] long * |
endOffset, |
|
|
[out, retval] BSTR * |
text |
|
) |
| |
|
get |
Returns a text portion before the given position.
Returns the substring of the specified text type that is located before the given character and does not include it. The result of this method should be same as a result for IAccessibleText::textAtOffset with a suitably decreased index value.
For example, if text type is IA2_TEXT_BOUNDARY_WORD, then the complete word that is closest to and located before offset is returned.
If the index is valid, but no text is found, S_FALSE is returned along with out values of 0, 0, and a NULL pointer. This would happen for boundary types other than character when the text consists entirely of whitespace.
- Parameters
-
[in] | offset | Index of the character for which to return the text part before it. The index character will not be part of the returned string. The valid range is 0..length. Refer to Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods for information about special offsets that can be used in IAccessibleText methods. |
[in] | boundaryType | The type of the text portion to return. See IA2TextBoundaryType for the complete list. |
[out] | startOffset | 0 based offset of first character. |
[out] | endOffset | 0 based offset of one past the last character. |
[out] | text | Returns the requested text portion. This portion may be empty or invalid when no appropriate text portion is found or text type is invalid. |
- Return values
-
S_OK | |
S_FALSE | if the requested boundary type is not implemented, such as IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return; [out] values are 0s and NULL respectively |
E_INVALIDARG | if bad [in] passed |