IAccessibleText

This enum defines values which specify a text() boundary type. IA2_TEXT_BOUNDARY_SENTENCE is optional. When a method doesn't implement this method it must return S_FALSE. Typically this feature would not be implemented by an application. However, if the application developer was not satisfied with how screen readers have handled the reading of sentences this boundary type could be implemented and screen readers could use the application's version of a sentence rather than the screen reader's. The rest of the boundary types must be supported. This enum is used in textBeforeOffset(), textAtOffset(), and textAfterOffset().

Method overview

Methods

addSelection()

Adds a text() selection().

HRESULT addSelection(
  [in] long startOffset,
  [in] long endOffset 
);

Parameters

startOffset

Starting offset ( 0 based).

endOffset

Offset of first character after new selection() (0 based).

Return value

E_INVALIDARG if bad [in] passed. S_OK.

attributes()

Returns text() attributes.

[propget] HRESULT attributes(
  [in] long offset,
  [out] long startOffset,
  [out] long endOffset,
  [out] BSTR textAttributes 
);

Parameters

offset

Text() offset (0 based)

startOffset

The starting offset of the character range over which all text() attributes match those of offset. (0 based)

endOffset

The offset of the first character past the character range over which all text() attributes match those of offset. (0 based)

textAttributes

A string of attributes describing the text(). The attributes are described in the; text attributes specification on the IAccessible2 web site.

Return value

E_INVALIDARG if bad [in] passed, [out] values are 0s and null respectively. S_FALSE if there is nothing to return, [out] values are 0s and null respectively. S_OK.

caretOffset()

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</li>
• the caretOffset for "two" would be 2, matching the "o"

The caret position/offset is that of the character logically following it, for example to the right of it in a left to right language.

[propget] HRESULT caretOffset(
  [out] long offset 
);

Parameters

offset

The returned offset is relative to the text() represented by this object.

Return value

S_FALSE if the caret is not currently active on this object, that is the caret is located on some other object. The returned offset value will be -1. S_OK.

characterExtents()

Returns the bounding box of the specified position. The virtual character after the last character of the represented text(), that is 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.

[propget] HRESULT characterExtents(
  [in] long offset,
  [in] enum IA2CoordinateType coordType,
  [out] long x,
  [out] long y,
  [out] long width,
  [out] long height 
);

Parameters

offset

Index of the character for which to return its bounding box. The valid range is 0..length.

coordType

Specifies if the coordinates are relative to the screen or to the parent window.

x

X coordinate of the top left corner of the bounding box of the referenced character.

y

Y coordinate of the top left corner of the bounding box of the referenced character.

width

Width of the bounding box of the referenced character.

height

Height of the bounding box of the referenced character.

Return value

E_INVALIDARG if bad [in] passed, [out] values are 0s. S_OK.

nCharacters()

Returns total number of characters.

[propget] HRESULT nCharacters(
  [out] long nCharacters 
);

Parameters

nCharacters

Missing Description

Return value

S_OK.

newText()

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.

[propget] HRESULT newText(
  [out] IA2TextSegment newText 
);

Parameters

newText

The text() that was just inserted.

Return value

S_FALSE if there is nothing to return, [out] value is null. S_OK.

nSelections()

Returns the number of active non-contiguous selections.

[propget] HRESULT nSelections(
  [out] long nSelections 
);

Parameters

nSelections

Missing Description

Return value

S_OK.

offsetAtPoint()

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 characterExtents(). The method offsetAtPoint, however, can be implemented more efficiently.

[propget] HRESULT offsetAtPoint(
  [in] long x,
  [in] long y,
  [in] enum IA2CoordinateType coordType,
  [out] long offset 
);

Parameters

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.

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.

coordType

Screen coordinates or window coordinates.

offset

Index of the character under the given point or -1 if the point is invalid or there is no character under the point.

Return value

E_INVALIDARG if bad [in] passed, [out] value is 0. S_OK.

oldText()

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.

[propget] HRESULT oldText(
  [out] IA2TextSegment oldText 
);

Parameters

oldText

The text() that was just removed.

Return value

S_FALSE if there is nothing to return, [out] value is null. S_OK.

removeSelection()

Unselects a range of text().

HRESULT removeSelection(
  [in] long selectionIndex 
);

Parameters

selectionIndex

Index of selection() to remove (0 based).

Return value

E_INVALIDARG if bad [in] passed. S_OK.

scrollSubstringTo()

Makes a specific part of string visible on screen.

HRESULT scrollSubstringTo(
  [in] long startIndex,
  [in] long endIndex,
  [in] enum IA2ScrollType scrollType 
);

Parameters

startIndex

0 based character offset.

endIndex

0 based character offset - the offset of the character just past the last character of the string.

scrollType

Defines where the object should be placed on the screen.

Return value

E_INVALIDARG if bad [in] passed. S_OK.

scrollSubstringToPoint()

Moves the top left of a substring to a specified location.

HRESULT scrollSubstringToPoint(
  [in] long startIndex,
  [in] long endIndex,
  [in] enum IA2CoordinateType coordinateType,
  [in] long x,
  [in] long y 
);

Parameters

startIndex

0 based character offset.

endIndex

0 based character offset - the offset of the character just past the last character of the string.

coordinateType

Specifies whether the coordinates are relative to the screen or the parent object.

x

Defines the x coordinate.

y

Defines the y coordinate.

Return value

E_INVALIDARG if bad [in] passed. S_FALSE if the object is already at the specified location. S_OK.

selection()

Returns the character offsets of Nth active text() selection.

[propget] HRESULT selection(
  [in] long selectionIndex,
  [out] long startOffset,
  [out] long endOffset 
);

Parameters

selectionIndex

Index of selection (0 based).

startOffset

0 based offset of first selected character.

endOffset

0 based offset of one past the last selected character.

Return value

E_INVALIDARG if bad [in] passed, [out] values are 0s. S_FALSE if there is nothing to return, [out] values are 0s. S_OK.

setCaretOffset()

Sets the position of the caret. The caret position/offset is that of the character logically following it, for example 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.

HRESULT setCaretOffset(
  [in] long offset 
);

Parameters

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 nCharacters() leads to insertion after the last character.

Return value

E_INVALIDARG if bad [in] passed. E_FAIL if the caret cannot be set. S_OK.

setSelection()

Changes the bounds of an existing selection().

HRESULT setSelection(
  [in] long selectionIndex,
  [in] long startOffset,
  [in] long endOffset 
);

Parameters

selectionIndex

Index of selection() to change (0 based)

startOffset

New starting offset (0 based)

endOffset

New ending offset (0 based) - the offset of the character just past the last character of the selection().

Return value

E_INVALIDARG if bad [in] passed. S_OK.

text()

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 nCharacters(). If both indices have the same value, an empty string is returned.

[propget] HRESULT text(
  [in] long startOffset,
  [in] long endOffset,
  [out] BSTR text 
);

Parameters

startOffset

Index of the first character to include in the returned string. The valid range is 0..length.

endOffset

Index of the last character to exclude in the returned string. The valid range is 0..length.

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.

Return value

E_INVALIDARG if bad [in] passed, [out] value is null. S_OK.

textAfterOffset()

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 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.

[propget] HRESULT textAfterOffset(
  [in] long offset,
  [in] enum IA2TextBoundaryType boundaryType,
  [out] long startOffset,
  [out] long endOffset,
  [out] BSTR text 
);

Parameters

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.

boundaryType

The type of the text() portion to return. See ::IA2TextBoundaryType for the complete list.

startOffset

0 based offset of first character.

endOffset

0 based offset of one past the last character.

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 value

E_INVALIDARG if bad [in] passed, [out] values are 0s and null respectively. 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. S_OK.

textAtOffset()

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.

[propget] HRESULT textAtOffset(
  [in] long offset,
  [in] enum IA2TextBoundaryType boundaryType,
  [out] long startOffset,
  [out] long endOffset,
  [out] BSTR text 
);

Parameters

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.

boundaryType

The type of the text() portion to return. See ::IA2TextBoundaryType for the complete list.

startOffset

0 based offset of first character.

endOffset

0 based offset of one past the last character.

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 value

E_INVALIDARG if bad [in] passed, [out] values are 0s and null respectively. 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. S_OK.

textBeforeOffset()

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 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.

[propget] HRESULT textBeforeOffset(
  [in] long offset,
  [in] enum IA2TextBoundaryType boundaryType,
  [out] long startOffset,
  [out] long endOffset,
  [out] BSTR text 
);

Parameters

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.

boundaryType

The type of the text() portion to return. See ::IA2TextBoundaryType for the complete list.

startOffset

0 based offset of first character.

endOffset

0 based offset of one past the last character.

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 value

E_INVALIDARG if bad [in] passed, [out] values are 0s and null respectively. 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. S_OK.