1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/other-licenses/ia2/AccessibleText.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,684 @@
1.4 +/*************************************************************************
1.5 + *
1.6 + * File Name (AccessibleText.idl)
1.7 + *
1.8 + * IAccessible2 IDL Specification
1.9 + *
1.10 + * Copyright (c) 2007, 2013 Linux Foundation
1.11 + * Copyright (c) 2006 IBM Corporation
1.12 + * Copyright (c) 2000, 2006 Sun Microsystems, Inc.
1.13 + * All rights reserved.
1.14 + *
1.15 + *
1.16 + * Redistribution and use in source and binary forms, with or without
1.17 + * modification, are permitted provided that the following conditions
1.18 + * are met:
1.19 + *
1.20 + * 1. Redistributions of source code must retain the above copyright
1.21 + * notice, this list of conditions and the following disclaimer.
1.22 + *
1.23 + * 2. Redistributions in binary form must reproduce the above
1.24 + * copyright notice, this list of conditions and the following
1.25 + * disclaimer in the documentation and/or other materials
1.26 + * provided with the distribution.
1.27 + *
1.28 + * 3. Neither the name of the Linux Foundation nor the names of its
1.29 + * contributors may be used to endorse or promote products
1.30 + * derived from this software without specific prior written
1.31 + * permission.
1.32 + *
1.33 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
1.34 + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
1.35 + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.36 + * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1.37 + * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
1.38 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.39 + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
1.40 + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
1.41 + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1.42 + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
1.43 + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1.44 + * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
1.45 + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.46 + *
1.47 + * This BSD License conforms to the Open Source Initiative "Simplified
1.48 + * BSD License" as published at:
1.49 + * http://www.opensource.org/licenses/bsd-license.php
1.50 + *
1.51 + * IAccessible2 is a trademark of the Linux Foundation. The IAccessible2
1.52 + * mark may be used in accordance with the Linux Foundation Trademark
1.53 + * Policy to indicate compliance with the IAccessible2 specification.
1.54 + *
1.55 + ************************************************************************/
1.56 +
1.57 +import "objidl.idl";
1.58 +import "oaidl.idl";
1.59 +import "oleacc.idl";
1.60 +import "IA2CommonTypes.idl";
1.61 +
1.62 +/** A structure containing a substring and the start and end offsets in the enclosing string.
1.63 +
1.64 + IAccessibleText::newText and IAccessibleText::oldText return this struct.
1.65 +*/
1.66 +typedef struct IA2TextSegment {
1.67 + BSTR text; ///< A copy of a segment of text taken from an enclosing paragraph.
1.68 + long start; ///< Index of the first character of the segment in the enclosing text.
1.69 + long end; ///< Index of the character following the last character of the segment in the enclosing text.
1.70 +} IA2TextSegment;
1.71 +
1.72 +/** This enum defines values which specify a text boundary type.
1.73 +
1.74 + IA2_TEXT_BOUNDARY_SENTENCE is optional. When a method doesn't implement this
1.75 + method it must return S_FALSE. Typically this feature would not be implemented
1.76 + by an application. However, if the application developer was not satisfied with
1.77 + how screen readers have handled the reading of sentences this boundary type
1.78 + could be implemented and screen readers could use the application's version of a
1.79 + sentence rather than the screen reader's.
1.80 +
1.81 + The rest of the boundary types must be supported.
1.82 +
1.83 + This enum is used in IAccessibleText::textBeforeOffset, IAccessibleText::textAtOffset,
1.84 + and IAccessibleText::textAfterOffset.
1.85 +*/
1.86 +
1.87 +enum IA2TextBoundaryType {
1.88 + IA2_TEXT_BOUNDARY_CHAR, /**< Typically, a single character is returned. In some cases more than
1.89 + one character is returned, for example, when a document contains field
1.90 + data such as a field containing a date, time, or footnote reference.
1.91 + In this case the caret can move over several characters in one movement
1.92 + of the caret. Note that after the caret moves, the caret offset changes
1.93 + by the number of characters in the field, e.g. by 8 characters in the
1.94 + following date: 03/26/07. */
1.95 + IA2_TEXT_BOUNDARY_WORD, /**< The range provided matches the range observed when the application
1.96 + processes the Ctrl + left arrow and Ctrl + right arrow key sequences.
1.97 + Typically this is from the start of one word to the start of the next, but
1.98 + various applications are inconsistent in the handling of the end of a line. */
1.99 + IA2_TEXT_BOUNDARY_SENTENCE, ///< Range is from start of one sentence to the start of another sentence.
1.100 + IA2_TEXT_BOUNDARY_PARAGRAPH, ///< Range is from start of one paragraph to the start of another paragraph.
1.101 + IA2_TEXT_BOUNDARY_LINE, /**< Range is from start of one line to the start of another line. This
1.102 + often means that an end-of-line character will appear at the end of the
1.103 + range. However in the case of some applications an end-of-line character
1.104 + indicates the end of a paragraph and the lines composing the paragraph,
1.105 + other than the last line, do not contain an end of line character. */
1.106 + IA2_TEXT_BOUNDARY_ALL ///< Using this value will cause all text to be returned.
1.107 +};
1.108 +
1.109 +/** @brief This interface gives read-only access to text.
1.110 +
1.111 + The %IAccessibleText interface should be implemented by all components
1.112 + that present textual information on the display like buttons,
1.113 + text entry fields, or text portions of the document window. The interface
1.114 + provides access to the text's content, attributes, and spatial location.
1.115 + However, text can not be modified with this interface. That is the task
1.116 + of the IAccessibleEditableText interface.
1.117 +
1.118 + The text length, i.e. the number of characters in the text, is
1.119 + returned by IAccessibleText::nCharacters. All methods that operate
1.120 + on particular characters (e.g. IAccessibleText::textAtOffset) use character
1.121 + indices from 0 to length-1. All methods that operate on character positions
1.122 + (e.g. IAccessibleText::text) use indices from 0 to length.
1.123 +
1.124 + Please note that accessible text does not necessarily support selection.
1.125 + In this case it should behave as if there where no selection. An empty
1.126 + selection is used for example to express the current cursor position.
1.127 +
1.128 + Refer to @ref _specialOffsets
1.129 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.130 + for information about special offsets that can be used in %IAccessibleText methods.
1.131 +
1.132 + E_FAIL is returned in the following cases
1.133 + @li endOffset < startOffset
1.134 + @li endoffset > length
1.135 +*/
1.136 +[object, uuid(24FD2FFB-3AAD-4a08-8335-A3AD89C0FB4B)]
1.137 +interface IAccessibleText : IUnknown
1.138 +{
1.139 +
1.140 + /** @brief Adds a text selection
1.141 + @param [in] startOffset
1.142 + Starting offset ( 0 based).
1.143 + @param [in] endOffset
1.144 + Offset of first character after new selection (0 based).
1.145 + @retval S_OK
1.146 + @retval E_INVALIDARG if bad [in] passed
1.147 + @note Refer to @ref _specialOffsets
1.148 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.149 + for information about special offsets that can be used in %IAccessibleText methods.
1.150 + */
1.151 + HRESULT addSelection
1.152 + (
1.153 + [in] long startOffset,
1.154 + [in] long endOffset
1.155 + );
1.156 +
1.157 + /** @brief Returns text attributes.
1.158 + @param [in] offset
1.159 + Text offset (0 based). Refer to @ref _specialOffsets
1.160 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.161 + for information about special offsets that can be used in %IAccessibleText methods.
1.162 + @param [out] startOffset
1.163 + The starting offset of the character range over which all text attributes match
1.164 + those of offset. (0 based)
1.165 + @param [out] endOffset
1.166 + The offset of the first character past the character range over which all text
1.167 + attributes match those of offset. (0 based)
1.168 + @param [out] textAttributes
1.169 + A string of attributes describing the text. The attributes are described in the
1.170 + <a href="http://www.linuxfoundation.org/en/Accessibility/IAccessible2/TextAttributes">
1.171 + text attributes specification</a> on the %IAccessible2 web site.
1.172 + @retval S_OK
1.173 + @retval S_FALSE if there is nothing to return, [out] values are 0s and NULL respectively
1.174 + @retval E_INVALIDARG if bad [in] passed
1.175 + */
1.176 + [propget] HRESULT attributes
1.177 + (
1.178 + [in] long offset,
1.179 + [out] long *startOffset,
1.180 + [out] long *endOffset,
1.181 + [out, retval] BSTR *textAttributes
1.182 + );
1.183 +
1.184 + /** @brief Returns the position of the caret.
1.185 +
1.186 + Returns the 0-based offset of the caret within the text. If the text is
1.187 + implemented as a tree of text objects with embed characters in higher levels
1.188 + representing substrings of child text objects and the caret is in one of the
1.189 + child text objects, then the offset in the higher level text object would be
1.190 + at the embed character representing child text object that contains the caret.
1.191 +
1.192 + For example, if the string "one two three" is implemented as a two text objects,
1.193 + with a top level text object containing an embed character "one ? three" and a
1.194 + child text object containing "two" and if the caret is in the descendant object
1.195 + just before the 'o' in "two", then:
1.196 + <ul>
1.197 + <li>the caretOffset for the "one ? three" object would be 4, matching the embed character</li>
1.198 + <li>the caretOffset for "two" would be 2, matching the "o"</li>
1.199 + </ul>
1.200 + The caret position/offset is that of the character logically following it, e.g.
1.201 + to the right of it in a left to right language, or to the left of it in a right
1.202 + to left language.
1.203 + @param [out] offset
1.204 + The returned offset is relative to the text represented by this object.
1.205 + @retval S_OK
1.206 + @retval S_FALSE if the caret is not currently active on this object, i.e. the
1.207 + caret is located on some other object. The returned offset value will be -1.
1.208 + @note S_FALSE (and an offset of -1) will not be returned if the caret is somewhere
1.209 + in the text object or one of its descendants.
1.210 + */
1.211 + [propget] HRESULT caretOffset
1.212 + (
1.213 + [out, retval] long *offset
1.214 + );
1.215 +
1.216 +
1.217 + /** @brief Returns the bounding box of the specified position.
1.218 +
1.219 + The virtual character after the last character of the represented
1.220 + text, i.e. the one at position length is a special case. It represents the
1.221 + current input position and will therefore typically be queried by AT more
1.222 + often than other positions. Because it does not represent an existing character
1.223 + its bounding box is defined in relation to preceding characters. It should be
1.224 + roughly equivalent to the bounding box of some character when inserted at the
1.225 + end of the text. Its height typically being the maximal height of all the
1.226 + characters in the text or the height of the preceding character, its width being
1.227 + at least one pixel so that the bounding box is not degenerate.
1.228 +
1.229 + Note that the index 'length' is not always valid. Whether it is or not is
1.230 + implementation dependent. It typically is when text is editable or otherwise
1.231 + when on the screen the caret can be placed behind the text. You can be sure
1.232 + that the index is valid after you have received a ::IA2_EVENT_TEXT_CARET_MOVED
1.233 + event for this index.
1.234 + @param [in] offset
1.235 + Index of the character for which to return its bounding box. The valid range
1.236 + is 0..length. Refer to @ref _specialOffsets
1.237 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.238 + for information about special offsets that can be used in %IAccessibleText methods.
1.239 + @param [in] coordType
1.240 + Specifies if the coordinates are relative to the screen or to the parent window.
1.241 + @param [out] x
1.242 + X coordinate of the top left corner of the bounding box of the referenced character.
1.243 + @param [out] y
1.244 + Y coordinate of the top left corner of the bounding box of the referenced character.
1.245 + @param [out] width
1.246 + Width of the bounding box of the referenced character.
1.247 + @param [out] height
1.248 + Height of the bounding box of the referenced character.
1.249 + @retval S_OK
1.250 + @retval E_INVALIDARG if bad [in] passed
1.251 + */
1.252 + [propget] HRESULT characterExtents
1.253 + (
1.254 + [in] long offset,
1.255 + [in] enum IA2CoordinateType coordType,
1.256 + [out] long *x,
1.257 + [out] long *y,
1.258 + [out] long *width,
1.259 + [out, retval] long *height
1.260 + );
1.261 +
1.262 +
1.263 + /** @brief Returns the number of active non-contiguous selections
1.264 + @param [out] nSelections
1.265 + @retval S_OK
1.266 + */
1.267 + [propget] HRESULT nSelections
1.268 + (
1.269 + [out, retval] long *nSelections
1.270 + );
1.271 +
1.272 + /** @brief Returns the text position for the specified screen position.
1.273 +
1.274 + Given a point return the zero-based index of the character under that
1.275 + point. The same functionality could be achieved by using the bounding
1.276 + boxes for each character as returned by IAccessibleText::characterExtents.
1.277 + The method IAccessibleText::offsetAtPoint, however, can be implemented
1.278 + more efficiently.
1.279 +
1.280 + @param [in] x
1.281 + The position's x value for which to look up the index of the character that
1.282 + is rendered on to the display at that point.
1.283 + @param [in] y
1.284 + The position's y value for which to look up the index of the character that
1.285 + is rendered on to the display at that point.
1.286 + @param [in] coordType
1.287 + Screen coordinates or window coordinates.
1.288 + @param [out] offset
1.289 + Index of the character under the given point or -1 if the point
1.290 + is invalid or there is no character under the point.
1.291 + @retval S_OK
1.292 + @retval S_FALSE if nothing to return, [out] value is -1
1.293 +
1.294 + @retval E_INVALIDARG if bad [in] passed
1.295 + */
1.296 + [propget] HRESULT offsetAtPoint
1.297 + (
1.298 + [in] long x,
1.299 + [in] long y,
1.300 + [in] enum IA2CoordinateType coordType,
1.301 + [out, retval] long *offset
1.302 + );
1.303 +
1.304 + /** @brief Returns the character offsets of Nth active text selection
1.305 +
1.306 + Returns the 0-based starting and ending offsets of the Nth selection. If the
1.307 + text is implemented as a tree of text objects with embed characters in higher
1.308 + levels representing substrings of child text objects, consider the following.
1.309 + If the starting selection offset is in one of the child text objects, then the
1.310 + starting offset in the higher level text object would be at the embed character
1.311 + representing the child text object that contains the starting selection offset.
1.312 + If the ending selection offset is in one of the child text objects, then the
1.313 + ending offset in the higher level text object would be just after the embed
1.314 + character representing the child text object that contains the ending selection
1.315 + offset.
1.316 +
1.317 + For example, if the string "one two three" is implemented as a two text objects,
1.318 + with a top level text object containing an embed character "one ? three" and a
1.319 + child text object containing "two" and if the selection is the string "two" then:
1.320 + <ul>
1.321 + <li>the startOffset for the "one ? three" object would be 4, matching the embed character and the endOffset would be 5.</li>
1.322 + <li>the startOffset for the "two" object would be 0, and the endOffset would be 3</li>
1.323 + </ul>
1.324 + Selection offsets are that of the character logically following it, e.g.
1.325 + to the right of it in a left to right language or to the left of it in a right to left language.
1.326 + @param [in] selectionIndex
1.327 + Index of selection (0 based).
1.328 + @param [out] startOffset
1.329 + 0 based offset of first selected character
1.330 + @param [out] endOffset
1.331 + 0 based offset of one past the last selected character.
1.332 + @retval S_OK
1.333 + @retval E_INVALIDARG if bad [in] passed
1.334 + */
1.335 + [propget] HRESULT selection
1.336 + (
1.337 + [in] long selectionIndex,
1.338 + [out] long *startOffset,
1.339 + [out, retval] long *endOffset
1.340 + );
1.341 +
1.342 + /** @brief Returns the substring between the two given indices.
1.343 +
1.344 + The substring starts with the character at startOffset (inclusive) and up to
1.345 + the character at endOffset (exclusive), if startOffset is less or equal
1.346 + endOffset. If endOffset is lower than startOffset, the result is the same
1.347 + as a call with the two arguments being exchanged.
1.348 +
1.349 + The whole text can be requested by passing the indices zero and
1.350 + IAccessibleText::nCharacters. If both indices have the same value, an empty
1.351 + string is returned.
1.352 + @param [in] startOffset
1.353 + Index of the first character to include in the returned string. The valid range
1.354 + is 0..length.
1.355 + @param [in] endOffset
1.356 + Index of the last character to exclude in the returned string. The valid range
1.357 + is 0..length.
1.358 + @param [out] text
1.359 + Returns the substring starting with the character at startOffset (inclusive)
1.360 + and up to the character at endOffset (exclusive), if startOffset is less than
1.361 + or equal to endOffset.
1.362 + @retval S_OK
1.363 + @retval E_INVALIDARG if bad [in] passed
1.364 + @note
1.365 + @li The returned string may be longer than endOffset-startOffset bytes if text
1.366 + contains multi-byte characters.
1.367 + @li Refer to @ref _specialOffsets
1.368 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.369 + for information about special offsets that can be used in %IAccessibleText methods.
1.370 + */
1.371 + [propget] HRESULT text
1.372 + (
1.373 + [in] long startOffset,
1.374 + [in] long endOffset,
1.375 + [out, retval] BSTR *text
1.376 + );
1.377 +
1.378 + /** @brief Returns a text portion before the given position.
1.379 +
1.380 + Returns the substring of the specified text type that is located before the
1.381 + given character and does not include it. The result of this method should be
1.382 + same as a result for IAccessibleText::textAtOffset with a suitably decreased
1.383 + index value.
1.384 +
1.385 + For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete
1.386 + word that is closest to and located before offset is returned.
1.387 +
1.388 + If the index is valid, but no text is found, S_FALSE is returned along with out
1.389 + values of 0, 0, and a NULL pointer. This would happen for boundary types other
1.390 + than character when the text consists entirely of whitespace.
1.391 +
1.392 + @param [in] offset
1.393 + Index of the character for which to return the text part before it. The index
1.394 + character will not be part of the returned string. The valid range is 0..length.
1.395 + Refer to @ref _specialOffsets
1.396 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.397 + for information about special offsets that can be used in %IAccessibleText methods.
1.398 + @param [in] boundaryType
1.399 + The type of the text portion to return. See ::IA2TextBoundaryType for the
1.400 + complete list.
1.401 + @param [out] startOffset
1.402 + 0 based offset of first character.
1.403 + @param [out] endOffset
1.404 + 0 based offset of one past the last character.
1.405 + @param [out] text
1.406 + Returns the requested text portion. This portion may be empty or invalid when
1.407 + no appropriate text portion is found or text type is invalid.
1.408 + @retval S_OK
1.409 + @retval S_FALSE if the requested boundary type is not implemented, such as
1.410 + ::IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return;
1.411 + [out] values are 0s and NULL respectively
1.412 + @retval E_INVALIDARG if bad [in] passed
1.413 + */
1.414 + [propget] HRESULT textBeforeOffset
1.415 + (
1.416 + [in] long offset,
1.417 + [in] enum IA2TextBoundaryType boundaryType,
1.418 + [out] long *startOffset,
1.419 + [out] long *endOffset,
1.420 + [out, retval] BSTR *text
1.421 + );
1.422 +
1.423 + /** @brief Returns a text portion after the given position.
1.424 +
1.425 + Returns the substring of the specified text type that is located after the
1.426 + given character and does not include it. The result of this method should be
1.427 + same as a result for IAccessibleText::textAtOffset with a suitably increased
1.428 + index value.
1.429 +
1.430 + For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete
1.431 + word that is closest to and located after offset is returned.
1.432 +
1.433 + If the index is valid, but no text is found, S_FALSE is returned along with out
1.434 + values of 0, 0, and a NULL pointer. This would happen for boundary types other
1.435 + than character when the text consists entirely of whitespace.
1.436 +
1.437 + @param [in] offset
1.438 + Index of the character for which to return the text part after it. The index
1.439 + character will not be part of the returned string. The valid range is 0..length.
1.440 + Refer to @ref _specialOffsets
1.441 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.442 + for information about special offsets that can be used in %IAccessibleText methods.
1.443 + @param [in] boundaryType
1.444 + The type of the text portion to return. See ::IA2TextBoundaryType for the complete
1.445 + list.
1.446 + @param [out] startOffset
1.447 + 0 based offset of first character.
1.448 + @param [out] endOffset
1.449 + 0 based offset of one past the last character.
1.450 + @param [out] text
1.451 + Returns the requested text portion. This portion may be empty or invalid when
1.452 + no appropriate text portion is found or text type is invalid.
1.453 + @retval S_OK
1.454 + @retval S_FALSE if the requested boundary type is not implemented, such as
1.455 + ::IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return;
1.456 + [out] values are 0s and NULL respectively
1.457 + @retval E_INVALIDARG if bad [in] passed
1.458 + */
1.459 + [propget] HRESULT textAfterOffset
1.460 + (
1.461 + [in] long offset,
1.462 + [in] enum IA2TextBoundaryType boundaryType,
1.463 + [out] long *startOffset,
1.464 + [out] long *endOffset,
1.465 + [out, retval] BSTR *text
1.466 + );
1.467 +
1.468 + /** @brief Returns a text portion that spans the given position.
1.469 +
1.470 + Returns the substring defined by the specified boundary type at the specified
1.471 + offset. Refer to IA2TextBoundaryType for more details.
1.472 +
1.473 + For the word boundary type the returned string will contain the word at the
1.474 + offset if the offset is inside a word and will contain the word before the
1.475 + offset if the offset is not inside a word. All offsets from the first to the
1.476 + last characters of a word are considered inside the word. Boundary types of
1.477 + sentence and paragraph should exhibit similar behavior.
1.478 +
1.479 + If the index is valid, but no text is found, S_FALSE is returned along with out
1.480 + values of 0, 0, and a NULL pointer. This would happen for boundary types other
1.481 + than character when the text consists entirely of whitespace.
1.482 +
1.483 + @param [in] offset
1.484 + Index of the character for which to return the text part it belongs to. The valid
1.485 + range is 0..length.
1.486 + Refer to @ref _specialOffsets
1.487 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.488 + for information about special offsets that can be used in %IAccessibleText methods.
1.489 + @param [in] boundaryType
1.490 + The type of the text portion to return. See ::IA2TextBoundaryType for the complete
1.491 + list.
1.492 + @param [out] startOffset
1.493 + 0 based offset of first character.
1.494 + @param [out] endOffset
1.495 + 0 based offset of one past the last character.
1.496 + @param [out] text
1.497 + Returns the requested text portion. This portion may be empty or invalid when
1.498 + no appropriate text portion is found or text type is invalid.
1.499 + @retval S_OK
1.500 + @retval S_FALSE if the requested boundary type is not implemented, such as
1.501 + ::IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return;
1.502 + [out] values are 0s and NULL respectively
1.503 + @retval E_INVALIDARG if bad [in] passed
1.504 + */
1.505 + [propget] HRESULT textAtOffset
1.506 + (
1.507 + [in] long offset,
1.508 + [in] enum IA2TextBoundaryType boundaryType,
1.509 + [out] long *startOffset,
1.510 + [out] long *endOffset,
1.511 + [out, retval] BSTR *text
1.512 + );
1.513 +
1.514 + /** @brief Unselects a range of text.
1.515 + @param [in] selectionIndex
1.516 + Index of selection to remove (0 based).
1.517 + @retval S_OK
1.518 + @retval E_INVALIDARG if bad [in] passed
1.519 + */
1.520 + HRESULT removeSelection
1.521 + (
1.522 + [in] long selectionIndex
1.523 + );
1.524 +
1.525 + /** @brief Sets the position of the caret.
1.526 +
1.527 + The caret position/offset is that of the character logically following it,
1.528 + e.g. to the right of it in a left to right language.
1.529 +
1.530 + Setting the caret position may or may not alter the current selection. A
1.531 + change of the selection is notified to the accessibility event listeners with
1.532 + an ::IA2_EVENT_TEXT_SELECTION_CHANGED event.
1.533 +
1.534 + When the new caret position differs from the old one (which, of course, is the
1.535 + standard case) this is notified to the accessibility event listeners with an
1.536 + ::IA2_EVENT_TEXT_CARET_MOVED event.
1.537 + @param [in] offset
1.538 + The new index of the caret. This caret is actually placed to the left side of
1.539 + the character with that index. An index of 0 places the caret so that the next
1.540 + insertion goes before the first character. An index of IAccessibleText::nCharacters
1.541 + leads to insertion after the last character. Refer to @ref _specialOffsets
1.542 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.543 + for information about special offsets that can be used in %IAccessibleText methods.
1.544 + @retval S_OK
1.545 + @retval E_FAIL if the caret cannot be set
1.546 + @retval E_INVALIDARG if bad [in] passed
1.547 + */
1.548 + HRESULT setCaretOffset
1.549 + (
1.550 + [in] long offset
1.551 + );
1.552 +
1.553 + /** @brief Changes the bounds of an existing selection.
1.554 + @param [in] selectionIndex
1.555 + Index of selection to change (0 based)
1.556 + @param [in] startOffset
1.557 + New starting offset (0 based)
1.558 + @param [in] endOffset
1.559 + New ending offset (0 based) - the offset of the character just past the last character of the selection.
1.560 + @retval S_OK
1.561 + @retval E_INVALIDARG if bad [in] passed
1.562 + @note Refer to @ref _specialOffsets
1.563 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.564 + for information about special offsets that can be used in %IAccessibleText methods.
1.565 + */
1.566 + HRESULT setSelection
1.567 + (
1.568 + [in] long selectionIndex,
1.569 + [in] long startOffset,
1.570 + [in] long endOffset
1.571 + );
1.572 +
1.573 + /** @brief Returns total number of characters.
1.574 +
1.575 + Note that this may be different than the total number of bytes required to store the
1.576 + text, if the text contains multi-byte characters.
1.577 + @param [out] nCharacters
1.578 + @retval S_OK
1.579 + */
1.580 + [propget] HRESULT nCharacters
1.581 + (
1.582 + [out, retval] long *nCharacters
1.583 + );
1.584 +
1.585 + /** @brief Makes a specific part of string visible on screen.
1.586 + @param [in] startIndex
1.587 + 0 based character offset.
1.588 + @param [in] endIndex
1.589 + 0 based character offset - the offset of the character just past the last character of the string.
1.590 + @param [in] scrollType
1.591 + Defines where the object should be placed on the screen.
1.592 + @retval S_OK
1.593 + @retval E_INVALIDARG if bad [in] passed
1.594 + @note Refer to @ref _specialOffsets
1.595 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.596 + for information about special offsets that can be used in %IAccessibleText methods.
1.597 + */
1.598 + HRESULT scrollSubstringTo
1.599 + (
1.600 + [in] long startIndex,
1.601 + [in] long endIndex,
1.602 + [in] enum IA2ScrollType scrollType
1.603 + );
1.604 +
1.605 + /** @brief Moves the top left of a substring to a specified location.
1.606 +
1.607 + @param [in] startIndex
1.608 + 0 based character offset.
1.609 + @param [in] endIndex
1.610 + 0 based character offset - the offset of the character just past the last character of the string.
1.611 + @param [in] coordinateType
1.612 + Specifies whether the coordinates are relative to the screen or the parent object.
1.613 + @param [in] x
1.614 + Defines the x coordinate.
1.615 + @param [in] y
1.616 + Defines the y coordinate.
1.617 + @retval S_OK
1.618 + @retval S_FALSE if the object is already at the specified location.
1.619 + @retval E_INVALIDARG if bad [in] passed
1.620 + @note Refer to @ref _specialOffsets
1.621 + "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
1.622 + for information about special offsets that can be used in %IAccessibleText methods.
1.623 + */
1.624 + HRESULT scrollSubstringToPoint
1.625 + (
1.626 + [in] long startIndex,
1.627 + [in] long endIndex,
1.628 + [in] enum IA2CoordinateType coordinateType,
1.629 + [in] long x,
1.630 + [in] long y
1.631 + );
1.632 +
1.633 + /** @brief Returns any inserted text.
1.634 +
1.635 + Provided for use by the ::IA2_EVENT_TEXT_INSERTED and ::IA2_EVENT_TEXT_UPDATED
1.636 + event handlers.
1.637 +
1.638 + This data is only guaranteed to be valid while the thread notifying the event
1.639 + continues. Once the handler has returned, the validity of the data depends on
1.640 + how the server manages the life cycle of its objects. Also, note that the server
1.641 + may have different life cycle management strategies for controls depending on
1.642 + whether or not a control manages its children. Lists, trees, and tables can have
1.643 + a large number of children and thus it's possible that the child objects for those
1.644 + controls would only be created as needed. Servers should document their life cycle
1.645 + strategy as this will be of interest to assistive technology or script engines
1.646 + accessing data out of process or from other threads. Servers only need to save the
1.647 + last inserted block of text and a scope of the entire application is adequate.
1.648 +
1.649 + @param [out] newText
1.650 + The text that was just inserted.
1.651 + @retval S_OK
1.652 + @retval S_FALSE If there is nothing to return, the values of IA2TextSegment
1.653 + struct are set as follows: text = NULL, start = 0, end = 0.
1.654 +
1.655 + */
1.656 + [propget] HRESULT newText
1.657 + (
1.658 + [out, retval] IA2TextSegment *newText
1.659 + );
1.660 +
1.661 + /** @brief Returns any removed text.
1.662 +
1.663 + Provided for use by the IA2_EVENT_TEXT_REMOVED/UPDATED event handlers.
1.664 +
1.665 + This data is only guaranteed to be valid while the thread notifying the event
1.666 + continues. Once the handler has returned, the validity of the data depends on
1.667 + how the server manages the life cycle of its objects. Also, note that the server
1.668 + may have different life cycle management strategies for controls depending on
1.669 + whether or not a control manages its children. Lists, trees, and tables can have
1.670 + a large number of children and thus it's possible that the child objects for those
1.671 + controls would only be created as needed. Servers should document their life cycle
1.672 + strategy as this will be of interest to assistive technology or script engines
1.673 + accessing data out of process or from other threads. Servers only need to save the
1.674 + last removed block of text and a scope of the entire application is adequate.
1.675 +
1.676 + @param [out] oldText
1.677 + The text that was just removed.
1.678 + @retval S_OK
1.679 + @retval S_FALSE If there is nothing to return, the values of IA2TextSegment
1.680 + struct are set as follows: text = NULL, start = 0, end = 0.
1.681 + */
1.682 + [propget] HRESULT oldText
1.683 + (
1.684 + [out, retval] IA2TextSegment *oldText
1.685 + );
1.686 +
1.687 +}
