import "AccessibleText.idl";
Public Member Functions | |
HRESULT | addSelection ([in] long startOffset,[in] long endOffset) |
Adds a text selection. | |
HRESULT | attributes ([in] long offset,[out] long *startOffset,[out] long *endOffset,[out, retval] BSTR *textAttributes) |
Returns text attributes. | |
HRESULT | caretOffset ([out, retval] long *offset) |
Returns the position of the caret. | |
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. | |
HRESULT | nSelections ([out, retval] long *nSelections) |
Returns the number of active non-contiguous selections. | |
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. | |
HRESULT | selection ([in] long selectionIndex,[out] long *startOffset,[out, retval] long *endOffset) |
Returns the character offsets of Nth active text selection. | |
HRESULT | text ([in] long startOffset,[in] long endOffset,[out, retval] BSTR *text) |
Returns the substring between the two given indices. | |
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. | |
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. | |
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. | |
HRESULT | removeSelection ([in] long selectionIndex) |
Unselects a range of text. | |
HRESULT | setCaretOffset ([in] long offset) |
Sets the position of the caret. | |
HRESULT | setSelection ([in] long selectionIndex,[in] long startOffset,[in] long endOffset) |
Changes the bounds of an existing selection. | |
HRESULT | nCharacters ([out, retval] long *nCharacters) |
Returns total number of characters. | |
HRESULT | scrollSubstringTo ([in] long startIndex,[in] long endIndex,[in] enum IA2ScrollType scrollType) |
Makes a specific part of string visible on screen. | |
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. | |
HRESULT | newText ([out, retval] IA2TextSegment *newText) |
Returns any inserted text. | |
HRESULT | oldText ([out, retval] IA2TextSegment *oldText) |
Returns any removed 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
HRESULT IAccessibleText::addSelection | ( | [in] long | startOffset, | |
[in] long | endOffset | |||
) |
Adds a text selection.
[in] | startOffset | Starting offset ( 0 based). |
[in] | endOffset | Offset of first character after new selection (0 based). |
S_OK | ||
E_INVALIDARG | if bad [in] passed |
HRESULT IAccessibleText::attributes | ( | [in] long | offset, | |
[out] long * | startOffset, | |||
[out] long * | endOffset, | |||
[out, retval] BSTR * | textAttributes | |||
) | [get] |
Returns text attributes.
[in] | offset | Text offset (0 based) |
[out] | startOffset | The starting offset of the character range over which all text attributes match those of offset. (0 based) |
[out] | endOffset | The offset of the first character past the character range over which all text attributes match those of offset. (0 based) |
[out] | textAttributes | A string of attributes describing the text. |
S_OK | ||
S_FALSE | if there is nothing to return, [out] values are 0s and NULL respectively | |
E_INVALIDARG | if bad [in] passed, [out] values are 0s and NULL respectively |
HRESULT IAccessibleText::caretOffset | ( | [out, retval] long * | offset | ) | [get] |
Returns the position of the caret.
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.
[out] | offset | The returned offset is relative to the text represented by this object. |
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. |
HRESULT IAccessibleText::characterExtents | ( | [in] long | offset, | |
[in] enum IA2CoordinateType | coordType, | |||
[out] long * | x, | |||
[out] long * | y, | |||
[out] long * | width, | |||
[out, retval] long * | height | |||
) | [get] |
Returns the bounding box of the specified position.
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 typically is when text is editable or otherwise when on the screen the caret can be placed behind the text. You can be sure that the index is valid after you have received a IA2_EVENT_TEXT_CARET_MOVED event for this index.
[in] | offset | Index of the character for which to return its bounding box. The valid range is 0..length. |
[in] | coordType | Specifies if the coordinates are relative to the screen or to the parent window. |
[out] | x | X coordinate of the top left corner of the bounding box of the referenced character. |
[out] | y | Y coordinate of the top left corner of the bounding box of the referenced character. |
[out] | width | Width of the bounding box of the referenced character. |
[out] | height | Height of the bounding box of the referenced character. |
S_OK | ||
E_INVALIDARG | if bad [in] passed, [out] values are 0s |
HRESULT IAccessibleText::nCharacters | ( | [out, retval] long * | nCharacters | ) | [get] |
Returns total number of characters.
Note that this may be different than the total number of bytes required to store the text, if the text contains multi-byte characters.
[out] | nCharacters |
S_OK |
HRESULT IAccessibleText::newText | ( | [out, retval] IA2TextSegment * | newText | ) | [get] |
Returns any inserted text.
Provided for use by the IA2_EVENT_TEXT_INSERTED and IA2_EVENT_TEXT_UPDATED event handlers.
This data is only guaranteed to be valid while the thread notifying the event continues. Once the handler has returned, the validity of the data depends on how the server manages the life cycle of its objects. Also, note that the server may have different life cycle management strategies for controls depending on whether or not a control manages its children. Lists, trees, and tables can have a large number of children and thus it's possible that the child objects for those controls would only be created as needed. Servers should document their life cycle strategy as this will be of interest to assistive technology or script engines accessing data out of process or from other threads. Servers only need to save the last inserted block of text and a scope of the entire application is adequate.
[out] | newText | The text that was just inserted. |
S_OK | ||
S_FALSE | if there is nothing to return, [out] value is NULL |
HRESULT IAccessibleText::nSelections | ( | [out, retval] long * | nSelections | ) | [get] |
Returns the number of active non-contiguous selections.
[out] | nSelections |
S_OK |
HRESULT IAccessibleText::offsetAtPoint | ( | [in] long | x, | |
[in] long | y, | |||
[in] enum IA2CoordinateType | coordType, | |||
[out, retval] long * | offset | |||
) | [get] |
Returns the text position for the specified screen position.
Given a point return the zero-based index of the character under that point. The same functionality could be achieved by using the bounding boxes for each character as returned by IAccessibleText::characterExtents. The method IAccessibleText::offsetAtPoint, however, can be implemented more efficiently.
[in] | x | The position's x value for which to look up the index of the character that is rendered on to the display at that point. |
[in] | y | The position's y value for which to look up the index of the character that is rendered on to the display at that point. |
[in] | coordType | Screen coordinates or window coordinates. |
[out] | offset | Index of the character under the given point or -1 if the point is invalid or there is no character under the point. |
S_OK | ||
E_INVALIDARG | if bad [in] passed, [out] value is 0 |
HRESULT IAccessibleText::oldText | ( | [out, retval] IA2TextSegment * | oldText | ) | [get] |
Returns any removed text.
Provided for use by the IA2_EVENT_TEXT_REMOVED/UPDATED event handlers.
This data is only guaranteed to be valid while the thread notifying the event continues. Once the handler has returned, the validity of the data depends on how the server manages the life cycle of its objects. Also, note that the server may have different life cycle management strategies for controls depending on whether or not a control manages its children. Lists, trees, and tables can have a large number of children and thus it's possible that the child objects for those controls would only be created as needed. Servers should document their life cycle strategy as this will be of interest to assistive technology or script engines accessing data out of process or from other threads. Servers only need to save the last removed block of text and a scope of the entire application is adequate.
[out] | oldText | The text that was just removed. |
S_OK | ||
S_FALSE | if there is nothing to return, [out] value is NULL |
HRESULT IAccessibleText::removeSelection | ( | [in] long | selectionIndex | ) |
Unselects a range of text.
[in] | selectionIndex | Index of selection to remove (0 based). |
S_OK | ||
E_INVALIDARG | if bad [in] passed |
HRESULT IAccessibleText::scrollSubstringTo | ( | [in] long | startIndex, | |
[in] long | endIndex, | |||
[in] enum IA2ScrollType | scrollType | |||
) |
Makes a specific part of string visible on screen.
[in] | startIndex | 0 based character offset. |
[in] | endIndex | 0 based character offset - the offset of the character just past the last character of the string. |
[in] | scrollType | Defines where the object should be placed on the screen. |
S_OK | ||
E_INVALIDARG | if bad [in] passed |
HRESULT IAccessibleText::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.
[in] | startIndex | 0 based character offset. |
[in] | endIndex | 0 based character offset - the offset of the character just past the last character of the string. |
[in] | coordinateType | Specifies whether the coordinates are relative to the screen or the parent object. |
[in] | x | Defines the x coordinate. |
[in] | y | Defines the y coordinate. |
S_OK | ||
S_FALSE | if the object is already at the specified location. | |
E_INVALIDARG | if bad [in] passed |
HRESULT IAccessibleText::selection | ( | [in] long | selectionIndex, | |
[out] long * | startOffset, | |||
[out, retval] long * | endOffset | |||
) | [get] |
Returns the character offsets of Nth active text selection.
[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. |
S_OK | ||
S_FALSE | if there is nothing to return, [out] values are 0s | |
E_INVALIDARG | if bad [in] passed, [out] values are 0s |
selectionIndex | index of selection (0 based) |
HRESULT IAccessibleText::setCaretOffset | ( | [in] long | offset | ) |
Sets the position of the caret.
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.
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 IA2_EVENT_TEXT_SELECTION_CHANGED 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 IA2_EVENT_TEXT_CARET_MOVED event.
[in] | offset | 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 IAccessibleText::nCharacters leads to insertion after the last character. |
S_OK | ||
E_FAIL | if the caret cannot be set | |
E_INVALIDARG | if bad [in] passed |
HRESULT IAccessibleText::setSelection | ( | [in] long | selectionIndex, | |
[in] long | startOffset, | |||
[in] long | endOffset | |||
) |
Changes the bounds of an existing selection.
[in] | selectionIndex | Index of selection to change (0 based) |
[in] | startOffset | New starting offset (0 based) |
[in] | endOffset | New ending offset (0 based) - the offset of the character just past the last character of the selection. |
S_OK | ||
E_INVALIDARG | if bad [in] passed |
HRESULT IAccessibleText::text | ( | [in] long | startOffset, | |
[in] long | endOffset, | |||
[out, retval] BSTR * | text | |||
) | [get] |
Returns the substring between the two given indices.
The substring starts with the character at startOffset (inclusive) and up to the character at endOffset (exclusive), if startOffset is less or equal endOffste. If endOffset is lower than startOffset, the result is the same as a call with the two arguments being exchanged.
The whole text can be requested by passing the indices zero and IAccessibleText::nCharacters. If both indices have the same value, an empty string is returned.
[in] | startOffset | Index of the first character to include in the returned string. The valid range is 0..length. |
[in] | endOffset | Index of the last character to exclude in the returned string. The valid range is 0..length. |
[out] | text | Returns the substring starting with the character at startOffset (inclusive) and up to the character at endOffset (exclusive), if startOffset is less than or equal to endOffset. |
S_OK | ||
E_INVALIDARG | if bad [in] passed, [out] value is NULL |
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 suitable word (or other text type) is found, a NULL pointer is returned.
[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. |
[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. |
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, [out] values are 0s and NULL respectively |
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 of the specified text type at the specified offset.
If the index is valid, but no suitable word (or other text type) is found, a NULL pointer is returned.
[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. |
[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. |
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, [out] values are 0s and NULL respectively |
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 suitable word (or other boundary type) is found, a NULL pointer is returned.
[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. |
[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. |
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, [out] values are 0s and NULL respectively |
http://bugs.linuxfoundation.org/
.
When using Bugzilla please be sure to select
IAccessible2 from the list of components.
Bugzilla is the preferred method for receiving feedback because it
automatically logs one's feedback in the IAccessible2 tracking system
without additional human intervention. One may also, however, send email to accessibility-rfc@a11y.org, a publicly archived emailing list. Please address any technical
problems you encounter with this document or the resources to which it
links, to the Open A11y Webmaster <webmaster@a11y.org>
A stable online reference version of the documentation for IAccessible2 API Version 1.0.2,
is available at: http://a11y.org/ia2-spec. A list
of known and reported
errors in the documentation for IAccessible2 API Version 1.0.2 can be found at:
http://a11y.org/ia2-errata