michael@0: /************************************************************************* michael@0: * michael@0: * File Name (AccessibleText.idl) michael@0: * michael@0: * IAccessible2 IDL Specification michael@0: * michael@0: * Copyright (c) 2007, 2013 Linux Foundation michael@0: * Copyright (c) 2006 IBM Corporation michael@0: * Copyright (c) 2000, 2006 Sun Microsystems, Inc. michael@0: * All rights reserved. michael@0: * michael@0: * michael@0: * Redistribution and use in source and binary forms, with or without michael@0: * modification, are permitted provided that the following conditions michael@0: * are met: michael@0: * michael@0: * 1. Redistributions of source code must retain the above copyright michael@0: * notice, this list of conditions and the following disclaimer. michael@0: * michael@0: * 2. Redistributions in binary form must reproduce the above michael@0: * copyright notice, this list of conditions and the following michael@0: * disclaimer in the documentation and/or other materials michael@0: * provided with the distribution. michael@0: * michael@0: * 3. Neither the name of the Linux Foundation nor the names of its michael@0: * contributors may be used to endorse or promote products michael@0: * derived from this software without specific prior written michael@0: * permission. michael@0: * michael@0: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND michael@0: * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, michael@0: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF michael@0: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE michael@0: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR michael@0: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, michael@0: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT michael@0: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; michael@0: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) michael@0: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN michael@0: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR michael@0: * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, michael@0: * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. michael@0: * michael@0: * This BSD License conforms to the Open Source Initiative "Simplified michael@0: * BSD License" as published at: michael@0: * http://www.opensource.org/licenses/bsd-license.php michael@0: * michael@0: * IAccessible2 is a trademark of the Linux Foundation. The IAccessible2 michael@0: * mark may be used in accordance with the Linux Foundation Trademark michael@0: * Policy to indicate compliance with the IAccessible2 specification. michael@0: * michael@0: ************************************************************************/ michael@0: michael@0: import "objidl.idl"; michael@0: import "oaidl.idl"; michael@0: import "oleacc.idl"; michael@0: import "IA2CommonTypes.idl"; michael@0: michael@0: /** A structure containing a substring and the start and end offsets in the enclosing string. michael@0: michael@0: IAccessibleText::newText and IAccessibleText::oldText return this struct. michael@0: */ michael@0: typedef struct IA2TextSegment { michael@0: BSTR text; ///< A copy of a segment of text taken from an enclosing paragraph. michael@0: long start; ///< Index of the first character of the segment in the enclosing text. michael@0: long end; ///< Index of the character following the last character of the segment in the enclosing text. michael@0: } IA2TextSegment; michael@0: michael@0: /** This enum defines values which specify a text boundary type. michael@0: michael@0: IA2_TEXT_BOUNDARY_SENTENCE is optional. When a method doesn't implement this michael@0: method it must return S_FALSE. Typically this feature would not be implemented michael@0: by an application. However, if the application developer was not satisfied with michael@0: how screen readers have handled the reading of sentences this boundary type michael@0: could be implemented and screen readers could use the application's version of a michael@0: sentence rather than the screen reader's. michael@0: michael@0: The rest of the boundary types must be supported. michael@0: michael@0: This enum is used in IAccessibleText::textBeforeOffset, IAccessibleText::textAtOffset, michael@0: and IAccessibleText::textAfterOffset. michael@0: */ michael@0: michael@0: enum IA2TextBoundaryType { michael@0: IA2_TEXT_BOUNDARY_CHAR, /**< Typically, a single character is returned. In some cases more than michael@0: one character is returned, for example, when a document contains field michael@0: data such as a field containing a date, time, or footnote reference. michael@0: In this case the caret can move over several characters in one movement michael@0: of the caret. Note that after the caret moves, the caret offset changes michael@0: by the number of characters in the field, e.g. by 8 characters in the michael@0: following date: 03/26/07. */ michael@0: IA2_TEXT_BOUNDARY_WORD, /**< The range provided matches the range observed when the application michael@0: processes the Ctrl + left arrow and Ctrl + right arrow key sequences. michael@0: Typically this is from the start of one word to the start of the next, but michael@0: various applications are inconsistent in the handling of the end of a line. */ michael@0: IA2_TEXT_BOUNDARY_SENTENCE, ///< Range is from start of one sentence to the start of another sentence. michael@0: IA2_TEXT_BOUNDARY_PARAGRAPH, ///< Range is from start of one paragraph to the start of another paragraph. michael@0: IA2_TEXT_BOUNDARY_LINE, /**< Range is from start of one line to the start of another line. This michael@0: often means that an end-of-line character will appear at the end of the michael@0: range. However in the case of some applications an end-of-line character michael@0: indicates the end of a paragraph and the lines composing the paragraph, michael@0: other than the last line, do not contain an end of line character. */ michael@0: IA2_TEXT_BOUNDARY_ALL ///< Using this value will cause all text to be returned. michael@0: }; michael@0: michael@0: /** @brief This interface gives read-only access to text. michael@0: michael@0: The %IAccessibleText interface should be implemented by all components michael@0: that present textual information on the display like buttons, michael@0: text entry fields, or text portions of the document window. The interface michael@0: provides access to the text's content, attributes, and spatial location. michael@0: However, text can not be modified with this interface. That is the task michael@0: of the IAccessibleEditableText interface. michael@0: michael@0: The text length, i.e. the number of characters in the text, is michael@0: returned by IAccessibleText::nCharacters. All methods that operate michael@0: on particular characters (e.g. IAccessibleText::textAtOffset) use character michael@0: indices from 0 to length-1. All methods that operate on character positions michael@0: (e.g. IAccessibleText::text) use indices from 0 to length. michael@0: michael@0: Please note that accessible text does not necessarily support selection. michael@0: In this case it should behave as if there where no selection. An empty michael@0: selection is used for example to express the current cursor position. michael@0: michael@0: Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: michael@0: E_FAIL is returned in the following cases michael@0: @li endOffset < startOffset michael@0: @li endoffset > length michael@0: */ michael@0: [object, uuid(24FD2FFB-3AAD-4a08-8335-A3AD89C0FB4B)] michael@0: interface IAccessibleText : IUnknown michael@0: { michael@0: michael@0: /** @brief Adds a text selection michael@0: @param [in] startOffset michael@0: Starting offset ( 0 based). michael@0: @param [in] endOffset michael@0: Offset of first character after new selection (0 based). michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: @note Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: */ michael@0: HRESULT addSelection michael@0: ( michael@0: [in] long startOffset, michael@0: [in] long endOffset michael@0: ); michael@0: michael@0: /** @brief Returns text attributes. michael@0: @param [in] offset michael@0: Text offset (0 based). Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: @param [out] startOffset michael@0: The starting offset of the character range over which all text attributes match michael@0: those of offset. (0 based) michael@0: @param [out] endOffset michael@0: The offset of the first character past the character range over which all text michael@0: attributes match those of offset. (0 based) michael@0: @param [out] textAttributes michael@0: A string of attributes describing the text. The attributes are described in the michael@0: michael@0: text attributes specification on the %IAccessible2 web site. michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] values are 0s and NULL respectively michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT attributes michael@0: ( michael@0: [in] long offset, michael@0: [out] long *startOffset, michael@0: [out] long *endOffset, michael@0: [out, retval] BSTR *textAttributes michael@0: ); michael@0: michael@0: /** @brief Returns the position of the caret. michael@0: michael@0: Returns the 0-based offset of the caret within the text. If the text is michael@0: implemented as a tree of text objects with embed characters in higher levels michael@0: representing substrings of child text objects and the caret is in one of the michael@0: child text objects, then the offset in the higher level text object would be michael@0: at the embed character representing child text object that contains the caret. michael@0: michael@0: For example, if the string "one two three" is implemented as a two text objects, michael@0: with a top level text object containing an embed character "one ? three" and a michael@0: child text object containing "two" and if the caret is in the descendant object michael@0: just before the 'o' in "two", then: michael@0: michael@0: The caret position/offset is that of the character logically following it, e.g. michael@0: to the right of it in a left to right language, or to the left of it in a right michael@0: to left language. michael@0: @param [out] offset michael@0: The returned offset is relative to the text represented by this object. michael@0: @retval S_OK michael@0: @retval S_FALSE if the caret is not currently active on this object, i.e. the michael@0: caret is located on some other object. The returned offset value will be -1. michael@0: @note S_FALSE (and an offset of -1) will not be returned if the caret is somewhere michael@0: in the text object or one of its descendants. michael@0: */ michael@0: [propget] HRESULT caretOffset michael@0: ( michael@0: [out, retval] long *offset michael@0: ); michael@0: michael@0: michael@0: /** @brief Returns the bounding box of the specified position. michael@0: michael@0: The virtual character after the last character of the represented michael@0: text, i.e. the one at position length is a special case. It represents the michael@0: current input position and will therefore typically be queried by AT more michael@0: often than other positions. Because it does not represent an existing character michael@0: its bounding box is defined in relation to preceding characters. It should be michael@0: roughly equivalent to the bounding box of some character when inserted at the michael@0: end of the text. Its height typically being the maximal height of all the michael@0: characters in the text or the height of the preceding character, its width being michael@0: at least one pixel so that the bounding box is not degenerate. michael@0: michael@0: Note that the index 'length' is not always valid. Whether it is or not is michael@0: implementation dependent. It typically is when text is editable or otherwise michael@0: when on the screen the caret can be placed behind the text. You can be sure michael@0: that the index is valid after you have received a ::IA2_EVENT_TEXT_CARET_MOVED michael@0: event for this index. michael@0: @param [in] offset michael@0: Index of the character for which to return its bounding box. The valid range michael@0: is 0..length. Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: @param [in] coordType michael@0: Specifies if the coordinates are relative to the screen or to the parent window. michael@0: @param [out] x michael@0: X coordinate of the top left corner of the bounding box of the referenced character. michael@0: @param [out] y michael@0: Y coordinate of the top left corner of the bounding box of the referenced character. michael@0: @param [out] width michael@0: Width of the bounding box of the referenced character. michael@0: @param [out] height michael@0: Height of the bounding box of the referenced character. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT characterExtents michael@0: ( michael@0: [in] long offset, michael@0: [in] enum IA2CoordinateType coordType, michael@0: [out] long *x, michael@0: [out] long *y, michael@0: [out] long *width, michael@0: [out, retval] long *height michael@0: ); michael@0: michael@0: michael@0: /** @brief Returns the number of active non-contiguous selections michael@0: @param [out] nSelections michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT nSelections michael@0: ( michael@0: [out, retval] long *nSelections michael@0: ); michael@0: michael@0: /** @brief Returns the text position for the specified screen position. michael@0: michael@0: Given a point return the zero-based index of the character under that michael@0: point. The same functionality could be achieved by using the bounding michael@0: boxes for each character as returned by IAccessibleText::characterExtents. michael@0: The method IAccessibleText::offsetAtPoint, however, can be implemented michael@0: more efficiently. michael@0: michael@0: @param [in] x michael@0: The position's x value for which to look up the index of the character that michael@0: is rendered on to the display at that point. michael@0: @param [in] y michael@0: The position's y value for which to look up the index of the character that michael@0: is rendered on to the display at that point. michael@0: @param [in] coordType michael@0: Screen coordinates or window coordinates. michael@0: @param [out] offset michael@0: Index of the character under the given point or -1 if the point michael@0: is invalid or there is no character under the point. michael@0: @retval S_OK michael@0: @retval S_FALSE if nothing to return, [out] value is -1 michael@0: michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT offsetAtPoint michael@0: ( michael@0: [in] long x, michael@0: [in] long y, michael@0: [in] enum IA2CoordinateType coordType, michael@0: [out, retval] long *offset michael@0: ); michael@0: michael@0: /** @brief Returns the character offsets of Nth active text selection michael@0: michael@0: Returns the 0-based starting and ending offsets of the Nth selection. If the michael@0: text is implemented as a tree of text objects with embed characters in higher michael@0: levels representing substrings of child text objects, consider the following. michael@0: If the starting selection offset is in one of the child text objects, then the michael@0: starting offset in the higher level text object would be at the embed character michael@0: representing the child text object that contains the starting selection offset. michael@0: If the ending selection offset is in one of the child text objects, then the michael@0: ending offset in the higher level text object would be just after the embed michael@0: character representing the child text object that contains the ending selection michael@0: offset. michael@0: michael@0: For example, if the string "one two three" is implemented as a two text objects, michael@0: with a top level text object containing an embed character "one ? three" and a michael@0: child text object containing "two" and if the selection is the string "two" then: michael@0: michael@0: Selection offsets are that of the character logically following it, e.g. michael@0: to the right of it in a left to right language or to the left of it in a right to left language. michael@0: @param [in] selectionIndex michael@0: Index of selection (0 based). michael@0: @param [out] startOffset michael@0: 0 based offset of first selected character michael@0: @param [out] endOffset michael@0: 0 based offset of one past the last selected character. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT selection michael@0: ( michael@0: [in] long selectionIndex, michael@0: [out] long *startOffset, michael@0: [out, retval] long *endOffset michael@0: ); michael@0: michael@0: /** @brief Returns the substring between the two given indices. michael@0: michael@0: The substring starts with the character at startOffset (inclusive) and up to michael@0: the character at endOffset (exclusive), if startOffset is less or equal michael@0: endOffset. If endOffset is lower than startOffset, the result is the same michael@0: as a call with the two arguments being exchanged. michael@0: michael@0: The whole text can be requested by passing the indices zero and michael@0: IAccessibleText::nCharacters. If both indices have the same value, an empty michael@0: string is returned. michael@0: @param [in] startOffset michael@0: Index of the first character to include in the returned string. The valid range michael@0: is 0..length. michael@0: @param [in] endOffset michael@0: Index of the last character to exclude in the returned string. The valid range michael@0: is 0..length. michael@0: @param [out] text michael@0: Returns the substring starting with the character at startOffset (inclusive) michael@0: and up to the character at endOffset (exclusive), if startOffset is less than michael@0: or equal to endOffset. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: @note michael@0: @li The returned string may be longer than endOffset-startOffset bytes if text michael@0: contains multi-byte characters. michael@0: @li Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: */ michael@0: [propget] HRESULT text michael@0: ( michael@0: [in] long startOffset, michael@0: [in] long endOffset, michael@0: [out, retval] BSTR *text michael@0: ); michael@0: michael@0: /** @brief Returns a text portion before the given position. michael@0: michael@0: Returns the substring of the specified text type that is located before the michael@0: given character and does not include it. The result of this method should be michael@0: same as a result for IAccessibleText::textAtOffset with a suitably decreased michael@0: index value. michael@0: michael@0: For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete michael@0: word that is closest to and located before offset is returned. michael@0: michael@0: If the index is valid, but no text is found, S_FALSE is returned along with out michael@0: values of 0, 0, and a NULL pointer. This would happen for boundary types other michael@0: than character when the text consists entirely of whitespace. michael@0: michael@0: @param [in] offset michael@0: Index of the character for which to return the text part before it. The index michael@0: character will not be part of the returned string. The valid range is 0..length. michael@0: Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: @param [in] boundaryType michael@0: The type of the text portion to return. See ::IA2TextBoundaryType for the michael@0: complete list. michael@0: @param [out] startOffset michael@0: 0 based offset of first character. michael@0: @param [out] endOffset michael@0: 0 based offset of one past the last character. michael@0: @param [out] text michael@0: Returns the requested text portion. This portion may be empty or invalid when michael@0: no appropriate text portion is found or text type is invalid. michael@0: @retval S_OK michael@0: @retval S_FALSE if the requested boundary type is not implemented, such as michael@0: ::IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return; michael@0: [out] values are 0s and NULL respectively michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT textBeforeOffset michael@0: ( michael@0: [in] long offset, michael@0: [in] enum IA2TextBoundaryType boundaryType, michael@0: [out] long *startOffset, michael@0: [out] long *endOffset, michael@0: [out, retval] BSTR *text michael@0: ); michael@0: michael@0: /** @brief Returns a text portion after the given position. michael@0: michael@0: Returns the substring of the specified text type that is located after the michael@0: given character and does not include it. The result of this method should be michael@0: same as a result for IAccessibleText::textAtOffset with a suitably increased michael@0: index value. michael@0: michael@0: For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete michael@0: word that is closest to and located after offset is returned. michael@0: michael@0: If the index is valid, but no text is found, S_FALSE is returned along with out michael@0: values of 0, 0, and a NULL pointer. This would happen for boundary types other michael@0: than character when the text consists entirely of whitespace. michael@0: michael@0: @param [in] offset michael@0: Index of the character for which to return the text part after it. The index michael@0: character will not be part of the returned string. The valid range is 0..length. michael@0: Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: @param [in] boundaryType michael@0: The type of the text portion to return. See ::IA2TextBoundaryType for the complete michael@0: list. michael@0: @param [out] startOffset michael@0: 0 based offset of first character. michael@0: @param [out] endOffset michael@0: 0 based offset of one past the last character. michael@0: @param [out] text michael@0: Returns the requested text portion. This portion may be empty or invalid when michael@0: no appropriate text portion is found or text type is invalid. michael@0: @retval S_OK michael@0: @retval S_FALSE if the requested boundary type is not implemented, such as michael@0: ::IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return; michael@0: [out] values are 0s and NULL respectively michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT textAfterOffset michael@0: ( michael@0: [in] long offset, michael@0: [in] enum IA2TextBoundaryType boundaryType, michael@0: [out] long *startOffset, michael@0: [out] long *endOffset, michael@0: [out, retval] BSTR *text michael@0: ); michael@0: michael@0: /** @brief Returns a text portion that spans the given position. michael@0: michael@0: Returns the substring defined by the specified boundary type at the specified michael@0: offset. Refer to IA2TextBoundaryType for more details. michael@0: michael@0: For the word boundary type the returned string will contain the word at the michael@0: offset if the offset is inside a word and will contain the word before the michael@0: offset if the offset is not inside a word. All offsets from the first to the michael@0: last characters of a word are considered inside the word. Boundary types of michael@0: sentence and paragraph should exhibit similar behavior. michael@0: michael@0: If the index is valid, but no text is found, S_FALSE is returned along with out michael@0: values of 0, 0, and a NULL pointer. This would happen for boundary types other michael@0: than character when the text consists entirely of whitespace. michael@0: michael@0: @param [in] offset michael@0: Index of the character for which to return the text part it belongs to. The valid michael@0: range is 0..length. michael@0: Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: @param [in] boundaryType michael@0: The type of the text portion to return. See ::IA2TextBoundaryType for the complete michael@0: list. michael@0: @param [out] startOffset michael@0: 0 based offset of first character. michael@0: @param [out] endOffset michael@0: 0 based offset of one past the last character. michael@0: @param [out] text michael@0: Returns the requested text portion. This portion may be empty or invalid when michael@0: no appropriate text portion is found or text type is invalid. michael@0: @retval S_OK michael@0: @retval S_FALSE if the requested boundary type is not implemented, such as michael@0: ::IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return; michael@0: [out] values are 0s and NULL respectively michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT textAtOffset michael@0: ( michael@0: [in] long offset, michael@0: [in] enum IA2TextBoundaryType boundaryType, michael@0: [out] long *startOffset, michael@0: [out] long *endOffset, michael@0: [out, retval] BSTR *text michael@0: ); michael@0: michael@0: /** @brief Unselects a range of text. michael@0: @param [in] selectionIndex michael@0: Index of selection to remove (0 based). michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: HRESULT removeSelection michael@0: ( michael@0: [in] long selectionIndex michael@0: ); michael@0: michael@0: /** @brief Sets the position of the caret. michael@0: michael@0: The caret position/offset is that of the character logically following it, michael@0: e.g. to the right of it in a left to right language. michael@0: michael@0: Setting the caret position may or may not alter the current selection. A michael@0: change of the selection is notified to the accessibility event listeners with michael@0: an ::IA2_EVENT_TEXT_SELECTION_CHANGED event. michael@0: michael@0: When the new caret position differs from the old one (which, of course, is the michael@0: standard case) this is notified to the accessibility event listeners with an michael@0: ::IA2_EVENT_TEXT_CARET_MOVED event. michael@0: @param [in] offset michael@0: The new index of the caret. This caret is actually placed to the left side of michael@0: the character with that index. An index of 0 places the caret so that the next michael@0: insertion goes before the first character. An index of IAccessibleText::nCharacters michael@0: leads to insertion after the last character. Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: @retval S_OK michael@0: @retval E_FAIL if the caret cannot be set michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: HRESULT setCaretOffset michael@0: ( michael@0: [in] long offset michael@0: ); michael@0: michael@0: /** @brief Changes the bounds of an existing selection. michael@0: @param [in] selectionIndex michael@0: Index of selection to change (0 based) michael@0: @param [in] startOffset michael@0: New starting offset (0 based) michael@0: @param [in] endOffset michael@0: New ending offset (0 based) - the offset of the character just past the last character of the selection. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: @note Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: */ michael@0: HRESULT setSelection michael@0: ( michael@0: [in] long selectionIndex, michael@0: [in] long startOffset, michael@0: [in] long endOffset michael@0: ); michael@0: michael@0: /** @brief Returns total number of characters. michael@0: michael@0: Note that this may be different than the total number of bytes required to store the michael@0: text, if the text contains multi-byte characters. michael@0: @param [out] nCharacters michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT nCharacters michael@0: ( michael@0: [out, retval] long *nCharacters michael@0: ); michael@0: michael@0: /** @brief Makes a specific part of string visible on screen. michael@0: @param [in] startIndex michael@0: 0 based character offset. michael@0: @param [in] endIndex michael@0: 0 based character offset - the offset of the character just past the last character of the string. michael@0: @param [in] scrollType michael@0: Defines where the object should be placed on the screen. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: @note Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: */ michael@0: HRESULT scrollSubstringTo michael@0: ( michael@0: [in] long startIndex, michael@0: [in] long endIndex, michael@0: [in] enum IA2ScrollType scrollType michael@0: ); michael@0: michael@0: /** @brief Moves the top left of a substring to a specified location. michael@0: michael@0: @param [in] startIndex michael@0: 0 based character offset. michael@0: @param [in] endIndex michael@0: 0 based character offset - the offset of the character just past the last character of the string. michael@0: @param [in] coordinateType michael@0: Specifies whether the coordinates are relative to the screen or the parent object. michael@0: @param [in] x michael@0: Defines the x coordinate. michael@0: @param [in] y michael@0: Defines the y coordinate. michael@0: @retval S_OK michael@0: @retval S_FALSE if the object is already at the specified location. michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: @note Refer to @ref _specialOffsets michael@0: "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" michael@0: for information about special offsets that can be used in %IAccessibleText methods. michael@0: */ michael@0: HRESULT scrollSubstringToPoint michael@0: ( michael@0: [in] long startIndex, michael@0: [in] long endIndex, michael@0: [in] enum IA2CoordinateType coordinateType, michael@0: [in] long x, michael@0: [in] long y michael@0: ); michael@0: michael@0: /** @brief Returns any inserted text. michael@0: michael@0: Provided for use by the ::IA2_EVENT_TEXT_INSERTED and ::IA2_EVENT_TEXT_UPDATED michael@0: event handlers. michael@0: michael@0: This data is only guaranteed to be valid while the thread notifying the event michael@0: continues. Once the handler has returned, the validity of the data depends on michael@0: how the server manages the life cycle of its objects. Also, note that the server michael@0: may have different life cycle management strategies for controls depending on michael@0: whether or not a control manages its children. Lists, trees, and tables can have michael@0: a large number of children and thus it's possible that the child objects for those michael@0: controls would only be created as needed. Servers should document their life cycle michael@0: strategy as this will be of interest to assistive technology or script engines michael@0: accessing data out of process or from other threads. Servers only need to save the michael@0: last inserted block of text and a scope of the entire application is adequate. michael@0: michael@0: @param [out] newText michael@0: The text that was just inserted. michael@0: @retval S_OK michael@0: @retval S_FALSE If there is nothing to return, the values of IA2TextSegment michael@0: struct are set as follows: text = NULL, start = 0, end = 0. michael@0: michael@0: */ michael@0: [propget] HRESULT newText michael@0: ( michael@0: [out, retval] IA2TextSegment *newText michael@0: ); michael@0: michael@0: /** @brief Returns any removed text. michael@0: michael@0: Provided for use by the IA2_EVENT_TEXT_REMOVED/UPDATED event handlers. michael@0: michael@0: This data is only guaranteed to be valid while the thread notifying the event michael@0: continues. Once the handler has returned, the validity of the data depends on michael@0: how the server manages the life cycle of its objects. Also, note that the server michael@0: may have different life cycle management strategies for controls depending on michael@0: whether or not a control manages its children. Lists, trees, and tables can have michael@0: a large number of children and thus it's possible that the child objects for those michael@0: controls would only be created as needed. Servers should document their life cycle michael@0: strategy as this will be of interest to assistive technology or script engines michael@0: accessing data out of process or from other threads. Servers only need to save the michael@0: last removed block of text and a scope of the entire application is adequate. michael@0: michael@0: @param [out] oldText michael@0: The text that was just removed. michael@0: @retval S_OK michael@0: @retval S_FALSE If there is nothing to return, the values of IA2TextSegment michael@0: struct are set as follows: text = NULL, start = 0, end = 0. michael@0: */ michael@0: [propget] HRESULT oldText michael@0: ( michael@0: [out, retval] IA2TextSegment *oldText michael@0: ); michael@0: michael@0: }