The Tor Browser / file comparison
comparison: other-licenses/ia2/AccessibleText.idl
other-licenses/ia2/AccessibleText.idl
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
equal
deleted
inserted
replaced
| -1:000000000000 | 0:415ef33eff97 |
|---|---|
| 1 /************************************************************************* | |
| 2 * | |
| 3 * File Name (AccessibleText.idl) | |
| 4 * | |
| 5 * IAccessible2 IDL Specification | |
| 6 * | |
| 7 * Copyright (c) 2007, 2013 Linux Foundation | |
| 8 * Copyright (c) 2006 IBM Corporation | |
| 9 * Copyright (c) 2000, 2006 Sun Microsystems, Inc. | |
| 10 * All rights reserved. | |
| 11 * | |
| 12 * | |
| 13 * Redistribution and use in source and binary forms, with or without | |
| 14 * modification, are permitted provided that the following conditions | |
| 15 * are met: | |
| 16 * | |
| 17 * 1. Redistributions of source code must retain the above copyright | |
| 18 * notice, this list of conditions and the following disclaimer. | |
| 19 * | |
| 20 * 2. Redistributions in binary form must reproduce the above | |
| 21 * copyright notice, this list of conditions and the following | |
| 22 * disclaimer in the documentation and/or other materials | |
| 23 * provided with the distribution. | |
| 24 * | |
| 25 * 3. Neither the name of the Linux Foundation nor the names of its | |
| 26 * contributors may be used to endorse or promote products | |
| 27 * derived from this software without specific prior written | |
| 28 * permission. | |
| 29 * | |
| 30 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND | |
| 31 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, | |
| 32 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
| 33 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | |
| 34 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR | |
| 35 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
| 36 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT | |
| 37 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | |
| 38 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
| 39 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
| 40 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR | |
| 41 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, | |
| 42 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
| 43 * | |
| 44 * This BSD License conforms to the Open Source Initiative "Simplified | |
| 45 * BSD License" as published at: | |
| 46 * http://www.opensource.org/licenses/bsd-license.php | |
| 47 * | |
| 48 * IAccessible2 is a trademark of the Linux Foundation. The IAccessible2 | |
| 49 * mark may be used in accordance with the Linux Foundation Trademark | |
| 50 * Policy to indicate compliance with the IAccessible2 specification. | |
| 51 * | |
| 52 ************************************************************************/ | |
| 53 | |
| 54 import "objidl.idl"; | |
| 55 import "oaidl.idl"; | |
| 56 import "oleacc.idl"; | |
| 57 import "IA2CommonTypes.idl"; | |
| 58 | |
| 59 /** A structure containing a substring and the start and end offsets in the enclosing string. | |
| 60 | |
| 61 IAccessibleText::newText and IAccessibleText::oldText return this struct. | |
| 62 */ | |
| 63 typedef struct IA2TextSegment { | |
| 64 BSTR text; ///< A copy of a segment of text taken from an enclosing paragraph. | |
| 65 long start; ///< Index of the first character of the segment in the enclosing text. | |
| 66 long end; ///< Index of the character following the last character of the segment in the enclosing text. | |
| 67 } IA2TextSegment; | |
| 68 | |
| 69 /** This enum defines values which specify a text boundary type. | |
| 70 | |
| 71 IA2_TEXT_BOUNDARY_SENTENCE is optional. When a method doesn't implement this | |
| 72 method it must return S_FALSE. Typically this feature would not be implemented | |
| 73 by an application. However, if the application developer was not satisfied with | |
| 74 how screen readers have handled the reading of sentences this boundary type | |
| 75 could be implemented and screen readers could use the application's version of a | |
| 76 sentence rather than the screen reader's. | |
| 77 | |
| 78 The rest of the boundary types must be supported. | |
| 79 | |
| 80 This enum is used in IAccessibleText::textBeforeOffset, IAccessibleText::textAtOffset, | |
| 81 and IAccessibleText::textAfterOffset. | |
| 82 */ | |
| 83 | |
| 84 enum IA2TextBoundaryType { | |
| 85 IA2_TEXT_BOUNDARY_CHAR, /**< Typically, a single character is returned. In some cases more than | |
| 86 one character is returned, for example, when a document contains field | |
| 87 data such as a field containing a date, time, or footnote reference. | |
| 88 In this case the caret can move over several characters in one movement | |
| 89 of the caret. Note that after the caret moves, the caret offset changes | |
| 90 by the number of characters in the field, e.g. by 8 characters in the | |
| 91 following date: 03/26/07. */ | |
| 92 IA2_TEXT_BOUNDARY_WORD, /**< The range provided matches the range observed when the application | |
| 93 processes the Ctrl + left arrow and Ctrl + right arrow key sequences. | |
| 94 Typically this is from the start of one word to the start of the next, but | |
| 95 various applications are inconsistent in the handling of the end of a line. */ | |
| 96 IA2_TEXT_BOUNDARY_SENTENCE, ///< Range is from start of one sentence to the start of another sentence. | |
| 97 IA2_TEXT_BOUNDARY_PARAGRAPH, ///< Range is from start of one paragraph to the start of another paragraph. | |
| 98 IA2_TEXT_BOUNDARY_LINE, /**< Range is from start of one line to the start of another line. This | |
| 99 often means that an end-of-line character will appear at the end of the | |
| 100 range. However in the case of some applications an end-of-line character | |
| 101 indicates the end of a paragraph and the lines composing the paragraph, | |
| 102 other than the last line, do not contain an end of line character. */ | |
| 103 IA2_TEXT_BOUNDARY_ALL ///< Using this value will cause all text to be returned. | |
| 104 }; | |
| 105 | |
| 106 /** @brief This interface gives read-only access to text. | |
| 107 | |
| 108 The %IAccessibleText interface should be implemented by all components | |
| 109 that present textual information on the display like buttons, | |
| 110 text entry fields, or text portions of the document window. The interface | |
| 111 provides access to the text's content, attributes, and spatial location. | |
| 112 However, text can not be modified with this interface. That is the task | |
| 113 of the IAccessibleEditableText interface. | |
| 114 | |
| 115 The text length, i.e. the number of characters in the text, is | |
| 116 returned by IAccessibleText::nCharacters. All methods that operate | |
| 117 on particular characters (e.g. IAccessibleText::textAtOffset) use character | |
| 118 indices from 0 to length-1. All methods that operate on character positions | |
| 119 (e.g. IAccessibleText::text) use indices from 0 to length. | |
| 120 | |
| 121 Please note that accessible text does not necessarily support selection. | |
| 122 In this case it should behave as if there where no selection. An empty | |
| 123 selection is used for example to express the current cursor position. | |
| 124 | |
| 125 Refer to @ref _specialOffsets | |
| 126 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 127 for information about special offsets that can be used in %IAccessibleText methods. | |
| 128 | |
| 129 E_FAIL is returned in the following cases | |
| 130 @li endOffset < startOffset | |
| 131 @li endoffset > length | |
| 132 */ | |
| 133 [object, uuid(24FD2FFB-3AAD-4a08-8335-A3AD89C0FB4B)] | |
| 134 interface IAccessibleText : IUnknown | |
| 135 { | |
| 136 | |
| 137 /** @brief Adds a text selection | |
| 138 @param [in] startOffset | |
| 139 Starting offset ( 0 based). | |
| 140 @param [in] endOffset | |
| 141 Offset of first character after new selection (0 based). | |
| 142 @retval S_OK | |
| 143 @retval E_INVALIDARG if bad [in] passed | |
| 144 @note Refer to @ref _specialOffsets | |
| 145 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 146 for information about special offsets that can be used in %IAccessibleText methods. | |
| 147 */ | |
| 148 HRESULT addSelection | |
| 149 ( | |
| 150 [in] long startOffset, | |
| 151 [in] long endOffset | |
| 152 ); | |
| 153 | |
| 154 /** @brief Returns text attributes. | |
| 155 @param [in] offset | |
| 156 Text offset (0 based). Refer to @ref _specialOffsets | |
| 157 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 158 for information about special offsets that can be used in %IAccessibleText methods. | |
| 159 @param [out] startOffset | |
| 160 The starting offset of the character range over which all text attributes match | |
| 161 those of offset. (0 based) | |
| 162 @param [out] endOffset | |
| 163 The offset of the first character past the character range over which all text | |
| 164 attributes match those of offset. (0 based) | |
| 165 @param [out] textAttributes | |
| 166 A string of attributes describing the text. The attributes are described in the | |
| 167 <a href="http://www.linuxfoundation.org/en/Accessibility/IAccessible2/TextAttributes"> | |
| 168 text attributes specification</a> on the %IAccessible2 web site. | |
| 169 @retval S_OK | |
| 170 @retval S_FALSE if there is nothing to return, [out] values are 0s and NULL respectively | |
| 171 @retval E_INVALIDARG if bad [in] passed | |
| 172 */ | |
| 173 [propget] HRESULT attributes | |
| 174 ( | |
| 175 [in] long offset, | |
| 176 [out] long *startOffset, | |
| 177 [out] long *endOffset, | |
| 178 [out, retval] BSTR *textAttributes | |
| 179 ); | |
| 180 | |
| 181 /** @brief Returns the position of the caret. | |
| 182 | |
| 183 Returns the 0-based offset of the caret within the text. If the text is | |
| 184 implemented as a tree of text objects with embed characters in higher levels | |
| 185 representing substrings of child text objects and the caret is in one of the | |
| 186 child text objects, then the offset in the higher level text object would be | |
| 187 at the embed character representing child text object that contains the caret. | |
| 188 | |
| 189 For example, if the string "one two three" is implemented as a two text objects, | |
| 190 with a top level text object containing an embed character "one ? three" and a | |
| 191 child text object containing "two" and if the caret is in the descendant object | |
| 192 just before the 'o' in "two", then: | |
| 193 <ul> | |
| 194 <li>the caretOffset for the "one ? three" object would be 4, matching the embed character</li> | |
| 195 <li>the caretOffset for "two" would be 2, matching the "o"</li> | |
| 196 </ul> | |
| 197 The caret position/offset is that of the character logically following it, e.g. | |
| 198 to the right of it in a left to right language, or to the left of it in a right | |
| 199 to left language. | |
| 200 @param [out] offset | |
| 201 The returned offset is relative to the text represented by this object. | |
| 202 @retval S_OK | |
| 203 @retval S_FALSE if the caret is not currently active on this object, i.e. the | |
| 204 caret is located on some other object. The returned offset value will be -1. | |
| 205 @note S_FALSE (and an offset of -1) will not be returned if the caret is somewhere | |
| 206 in the text object or one of its descendants. | |
| 207 */ | |
| 208 [propget] HRESULT caretOffset | |
| 209 ( | |
| 210 [out, retval] long *offset | |
| 211 ); | |
| 212 | |
| 213 | |
| 214 /** @brief Returns the bounding box of the specified position. | |
| 215 | |
| 216 The virtual character after the last character of the represented | |
| 217 text, i.e. the one at position length is a special case. It represents the | |
| 218 current input position and will therefore typically be queried by AT more | |
| 219 often than other positions. Because it does not represent an existing character | |
| 220 its bounding box is defined in relation to preceding characters. It should be | |
| 221 roughly equivalent to the bounding box of some character when inserted at the | |
| 222 end of the text. Its height typically being the maximal height of all the | |
| 223 characters in the text or the height of the preceding character, its width being | |
| 224 at least one pixel so that the bounding box is not degenerate. | |
| 225 | |
| 226 Note that the index 'length' is not always valid. Whether it is or not is | |
| 227 implementation dependent. It typically is when text is editable or otherwise | |
| 228 when on the screen the caret can be placed behind the text. You can be sure | |
| 229 that the index is valid after you have received a ::IA2_EVENT_TEXT_CARET_MOVED | |
| 230 event for this index. | |
| 231 @param [in] offset | |
| 232 Index of the character for which to return its bounding box. The valid range | |
| 233 is 0..length. Refer to @ref _specialOffsets | |
| 234 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 235 for information about special offsets that can be used in %IAccessibleText methods. | |
| 236 @param [in] coordType | |
| 237 Specifies if the coordinates are relative to the screen or to the parent window. | |
| 238 @param [out] x | |
| 239 X coordinate of the top left corner of the bounding box of the referenced character. | |
| 240 @param [out] y | |
| 241 Y coordinate of the top left corner of the bounding box of the referenced character. | |
| 242 @param [out] width | |
| 243 Width of the bounding box of the referenced character. | |
| 244 @param [out] height | |
| 245 Height of the bounding box of the referenced character. | |
| 246 @retval S_OK | |
| 247 @retval E_INVALIDARG if bad [in] passed | |
| 248 */ | |
| 249 [propget] HRESULT characterExtents | |
| 250 ( | |
| 251 [in] long offset, | |
| 252 [in] enum IA2CoordinateType coordType, | |
| 253 [out] long *x, | |
| 254 [out] long *y, | |
| 255 [out] long *width, | |
| 256 [out, retval] long *height | |
| 257 ); | |
| 258 | |
| 259 | |
| 260 /** @brief Returns the number of active non-contiguous selections | |
| 261 @param [out] nSelections | |
| 262 @retval S_OK | |
| 263 */ | |
| 264 [propget] HRESULT nSelections | |
| 265 ( | |
| 266 [out, retval] long *nSelections | |
| 267 ); | |
| 268 | |
| 269 /** @brief Returns the text position for the specified screen position. | |
| 270 | |
| 271 Given a point return the zero-based index of the character under that | |
| 272 point. The same functionality could be achieved by using the bounding | |
| 273 boxes for each character as returned by IAccessibleText::characterExtents. | |
| 274 The method IAccessibleText::offsetAtPoint, however, can be implemented | |
| 275 more efficiently. | |
| 276 | |
| 277 @param [in] x | |
| 278 The position's x value for which to look up the index of the character that | |
| 279 is rendered on to the display at that point. | |
| 280 @param [in] y | |
| 281 The position's y value for which to look up the index of the character that | |
| 282 is rendered on to the display at that point. | |
| 283 @param [in] coordType | |
| 284 Screen coordinates or window coordinates. | |
| 285 @param [out] offset | |
| 286 Index of the character under the given point or -1 if the point | |
| 287 is invalid or there is no character under the point. | |
| 288 @retval S_OK | |
| 289 @retval S_FALSE if nothing to return, [out] value is -1 | |
| 290 | |
| 291 @retval E_INVALIDARG if bad [in] passed | |
| 292 */ | |
| 293 [propget] HRESULT offsetAtPoint | |
| 294 ( | |
| 295 [in] long x, | |
| 296 [in] long y, | |
| 297 [in] enum IA2CoordinateType coordType, | |
| 298 [out, retval] long *offset | |
| 299 ); | |
| 300 | |
| 301 /** @brief Returns the character offsets of Nth active text selection | |
| 302 | |
| 303 Returns the 0-based starting and ending offsets of the Nth selection. If the | |
| 304 text is implemented as a tree of text objects with embed characters in higher | |
| 305 levels representing substrings of child text objects, consider the following. | |
| 306 If the starting selection offset is in one of the child text objects, then the | |
| 307 starting offset in the higher level text object would be at the embed character | |
| 308 representing the child text object that contains the starting selection offset. | |
| 309 If the ending selection offset is in one of the child text objects, then the | |
| 310 ending offset in the higher level text object would be just after the embed | |
| 311 character representing the child text object that contains the ending selection | |
| 312 offset. | |
| 313 | |
| 314 For example, if the string "one two three" is implemented as a two text objects, | |
| 315 with a top level text object containing an embed character "one ? three" and a | |
| 316 child text object containing "two" and if the selection is the string "two" then: | |
| 317 <ul> | |
| 318 <li>the startOffset for the "one ? three" object would be 4, matching the embed character and the endOffset would be 5.</li> | |
| 319 <li>the startOffset for the "two" object would be 0, and the endOffset would be 3</li> | |
| 320 </ul> | |
| 321 Selection offsets are that of the character logically following it, e.g. | |
| 322 to the right of it in a left to right language or to the left of it in a right to left language. | |
| 323 @param [in] selectionIndex | |
| 324 Index of selection (0 based). | |
| 325 @param [out] startOffset | |
| 326 0 based offset of first selected character | |
| 327 @param [out] endOffset | |
| 328 0 based offset of one past the last selected character. | |
| 329 @retval S_OK | |
| 330 @retval E_INVALIDARG if bad [in] passed | |
| 331 */ | |
| 332 [propget] HRESULT selection | |
| 333 ( | |
| 334 [in] long selectionIndex, | |
| 335 [out] long *startOffset, | |
| 336 [out, retval] long *endOffset | |
| 337 ); | |
| 338 | |
| 339 /** @brief Returns the substring between the two given indices. | |
| 340 | |
| 341 The substring starts with the character at startOffset (inclusive) and up to | |
| 342 the character at endOffset (exclusive), if startOffset is less or equal | |
| 343 endOffset. If endOffset is lower than startOffset, the result is the same | |
| 344 as a call with the two arguments being exchanged. | |
| 345 | |
| 346 The whole text can be requested by passing the indices zero and | |
| 347 IAccessibleText::nCharacters. If both indices have the same value, an empty | |
| 348 string is returned. | |
| 349 @param [in] startOffset | |
| 350 Index of the first character to include in the returned string. The valid range | |
| 351 is 0..length. | |
| 352 @param [in] endOffset | |
| 353 Index of the last character to exclude in the returned string. The valid range | |
| 354 is 0..length. | |
| 355 @param [out] text | |
| 356 Returns the substring starting with the character at startOffset (inclusive) | |
| 357 and up to the character at endOffset (exclusive), if startOffset is less than | |
| 358 or equal to endOffset. | |
| 359 @retval S_OK | |
| 360 @retval E_INVALIDARG if bad [in] passed | |
| 361 @note | |
| 362 @li The returned string may be longer than endOffset-startOffset bytes if text | |
| 363 contains multi-byte characters. | |
| 364 @li Refer to @ref _specialOffsets | |
| 365 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 366 for information about special offsets that can be used in %IAccessibleText methods. | |
| 367 */ | |
| 368 [propget] HRESULT text | |
| 369 ( | |
| 370 [in] long startOffset, | |
| 371 [in] long endOffset, | |
| 372 [out, retval] BSTR *text | |
| 373 ); | |
| 374 | |
| 375 /** @brief Returns a text portion before the given position. | |
| 376 | |
| 377 Returns the substring of the specified text type that is located before the | |
| 378 given character and does not include it. The result of this method should be | |
| 379 same as a result for IAccessibleText::textAtOffset with a suitably decreased | |
| 380 index value. | |
| 381 | |
| 382 For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete | |
| 383 word that is closest to and located before offset is returned. | |
| 384 | |
| 385 If the index is valid, but no text is found, S_FALSE is returned along with out | |
| 386 values of 0, 0, and a NULL pointer. This would happen for boundary types other | |
| 387 than character when the text consists entirely of whitespace. | |
| 388 | |
| 389 @param [in] offset | |
| 390 Index of the character for which to return the text part before it. The index | |
| 391 character will not be part of the returned string. The valid range is 0..length. | |
| 392 Refer to @ref _specialOffsets | |
| 393 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 394 for information about special offsets that can be used in %IAccessibleText methods. | |
| 395 @param [in] boundaryType | |
| 396 The type of the text portion to return. See ::IA2TextBoundaryType for the | |
| 397 complete list. | |
| 398 @param [out] startOffset | |
| 399 0 based offset of first character. | |
| 400 @param [out] endOffset | |
| 401 0 based offset of one past the last character. | |
| 402 @param [out] text | |
| 403 Returns the requested text portion. This portion may be empty or invalid when | |
| 404 no appropriate text portion is found or text type is invalid. | |
| 405 @retval S_OK | |
| 406 @retval S_FALSE if the requested boundary type is not implemented, such as | |
| 407 ::IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return; | |
| 408 [out] values are 0s and NULL respectively | |
| 409 @retval E_INVALIDARG if bad [in] passed | |
| 410 */ | |
| 411 [propget] HRESULT textBeforeOffset | |
| 412 ( | |
| 413 [in] long offset, | |
| 414 [in] enum IA2TextBoundaryType boundaryType, | |
| 415 [out] long *startOffset, | |
| 416 [out] long *endOffset, | |
| 417 [out, retval] BSTR *text | |
| 418 ); | |
| 419 | |
| 420 /** @brief Returns a text portion after the given position. | |
| 421 | |
| 422 Returns the substring of the specified text type that is located after the | |
| 423 given character and does not include it. The result of this method should be | |
| 424 same as a result for IAccessibleText::textAtOffset with a suitably increased | |
| 425 index value. | |
| 426 | |
| 427 For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete | |
| 428 word that is closest to and located after offset is returned. | |
| 429 | |
| 430 If the index is valid, but no text is found, S_FALSE is returned along with out | |
| 431 values of 0, 0, and a NULL pointer. This would happen for boundary types other | |
| 432 than character when the text consists entirely of whitespace. | |
| 433 | |
| 434 @param [in] offset | |
| 435 Index of the character for which to return the text part after it. The index | |
| 436 character will not be part of the returned string. The valid range is 0..length. | |
| 437 Refer to @ref _specialOffsets | |
| 438 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 439 for information about special offsets that can be used in %IAccessibleText methods. | |
| 440 @param [in] boundaryType | |
| 441 The type of the text portion to return. See ::IA2TextBoundaryType for the complete | |
| 442 list. | |
| 443 @param [out] startOffset | |
| 444 0 based offset of first character. | |
| 445 @param [out] endOffset | |
| 446 0 based offset of one past the last character. | |
| 447 @param [out] text | |
| 448 Returns the requested text portion. This portion may be empty or invalid when | |
| 449 no appropriate text portion is found or text type is invalid. | |
| 450 @retval S_OK | |
| 451 @retval S_FALSE if the requested boundary type is not implemented, such as | |
| 452 ::IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return; | |
| 453 [out] values are 0s and NULL respectively | |
| 454 @retval E_INVALIDARG if bad [in] passed | |
| 455 */ | |
| 456 [propget] HRESULT textAfterOffset | |
| 457 ( | |
| 458 [in] long offset, | |
| 459 [in] enum IA2TextBoundaryType boundaryType, | |
| 460 [out] long *startOffset, | |
| 461 [out] long *endOffset, | |
| 462 [out, retval] BSTR *text | |
| 463 ); | |
| 464 | |
| 465 /** @brief Returns a text portion that spans the given position. | |
| 466 | |
| 467 Returns the substring defined by the specified boundary type at the specified | |
| 468 offset. Refer to IA2TextBoundaryType for more details. | |
| 469 | |
| 470 For the word boundary type the returned string will contain the word at the | |
| 471 offset if the offset is inside a word and will contain the word before the | |
| 472 offset if the offset is not inside a word. All offsets from the first to the | |
| 473 last characters of a word are considered inside the word. Boundary types of | |
| 474 sentence and paragraph should exhibit similar behavior. | |
| 475 | |
| 476 If the index is valid, but no text is found, S_FALSE is returned along with out | |
| 477 values of 0, 0, and a NULL pointer. This would happen for boundary types other | |
| 478 than character when the text consists entirely of whitespace. | |
| 479 | |
| 480 @param [in] offset | |
| 481 Index of the character for which to return the text part it belongs to. The valid | |
| 482 range is 0..length. | |
| 483 Refer to @ref _specialOffsets | |
| 484 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 485 for information about special offsets that can be used in %IAccessibleText methods. | |
| 486 @param [in] boundaryType | |
| 487 The type of the text portion to return. See ::IA2TextBoundaryType for the complete | |
| 488 list. | |
| 489 @param [out] startOffset | |
| 490 0 based offset of first character. | |
| 491 @param [out] endOffset | |
| 492 0 based offset of one past the last character. | |
| 493 @param [out] text | |
| 494 Returns the requested text portion. This portion may be empty or invalid when | |
| 495 no appropriate text portion is found or text type is invalid. | |
| 496 @retval S_OK | |
| 497 @retval S_FALSE if the requested boundary type is not implemented, such as | |
| 498 ::IA2_TEXT_BOUNDARY_SENTENCE, or if there is nothing to return; | |
| 499 [out] values are 0s and NULL respectively | |
| 500 @retval E_INVALIDARG if bad [in] passed | |
| 501 */ | |
| 502 [propget] HRESULT textAtOffset | |
| 503 ( | |
| 504 [in] long offset, | |
| 505 [in] enum IA2TextBoundaryType boundaryType, | |
| 506 [out] long *startOffset, | |
| 507 [out] long *endOffset, | |
| 508 [out, retval] BSTR *text | |
| 509 ); | |
| 510 | |
| 511 /** @brief Unselects a range of text. | |
| 512 @param [in] selectionIndex | |
| 513 Index of selection to remove (0 based). | |
| 514 @retval S_OK | |
| 515 @retval E_INVALIDARG if bad [in] passed | |
| 516 */ | |
| 517 HRESULT removeSelection | |
| 518 ( | |
| 519 [in] long selectionIndex | |
| 520 ); | |
| 521 | |
| 522 /** @brief Sets the position of the caret. | |
| 523 | |
| 524 The caret position/offset is that of the character logically following it, | |
| 525 e.g. to the right of it in a left to right language. | |
| 526 | |
| 527 Setting the caret position may or may not alter the current selection. A | |
| 528 change of the selection is notified to the accessibility event listeners with | |
| 529 an ::IA2_EVENT_TEXT_SELECTION_CHANGED event. | |
| 530 | |
| 531 When the new caret position differs from the old one (which, of course, is the | |
| 532 standard case) this is notified to the accessibility event listeners with an | |
| 533 ::IA2_EVENT_TEXT_CARET_MOVED event. | |
| 534 @param [in] offset | |
| 535 The new index of the caret. This caret is actually placed to the left side of | |
| 536 the character with that index. An index of 0 places the caret so that the next | |
| 537 insertion goes before the first character. An index of IAccessibleText::nCharacters | |
| 538 leads to insertion after the last character. Refer to @ref _specialOffsets | |
| 539 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 540 for information about special offsets that can be used in %IAccessibleText methods. | |
| 541 @retval S_OK | |
| 542 @retval E_FAIL if the caret cannot be set | |
| 543 @retval E_INVALIDARG if bad [in] passed | |
| 544 */ | |
| 545 HRESULT setCaretOffset | |
| 546 ( | |
| 547 [in] long offset | |
| 548 ); | |
| 549 | |
| 550 /** @brief Changes the bounds of an existing selection. | |
| 551 @param [in] selectionIndex | |
| 552 Index of selection to change (0 based) | |
| 553 @param [in] startOffset | |
| 554 New starting offset (0 based) | |
| 555 @param [in] endOffset | |
| 556 New ending offset (0 based) - the offset of the character just past the last character of the selection. | |
| 557 @retval S_OK | |
| 558 @retval E_INVALIDARG if bad [in] passed | |
| 559 @note Refer to @ref _specialOffsets | |
| 560 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 561 for information about special offsets that can be used in %IAccessibleText methods. | |
| 562 */ | |
| 563 HRESULT setSelection | |
| 564 ( | |
| 565 [in] long selectionIndex, | |
| 566 [in] long startOffset, | |
| 567 [in] long endOffset | |
| 568 ); | |
| 569 | |
| 570 /** @brief Returns total number of characters. | |
| 571 | |
| 572 Note that this may be different than the total number of bytes required to store the | |
| 573 text, if the text contains multi-byte characters. | |
| 574 @param [out] nCharacters | |
| 575 @retval S_OK | |
| 576 */ | |
| 577 [propget] HRESULT nCharacters | |
| 578 ( | |
| 579 [out, retval] long *nCharacters | |
| 580 ); | |
| 581 | |
| 582 /** @brief Makes a specific part of string visible on screen. | |
| 583 @param [in] startIndex | |
| 584 0 based character offset. | |
| 585 @param [in] endIndex | |
| 586 0 based character offset - the offset of the character just past the last character of the string. | |
| 587 @param [in] scrollType | |
| 588 Defines where the object should be placed on the screen. | |
| 589 @retval S_OK | |
| 590 @retval E_INVALIDARG if bad [in] passed | |
| 591 @note Refer to @ref _specialOffsets | |
| 592 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 593 for information about special offsets that can be used in %IAccessibleText methods. | |
| 594 */ | |
| 595 HRESULT scrollSubstringTo | |
| 596 ( | |
| 597 [in] long startIndex, | |
| 598 [in] long endIndex, | |
| 599 [in] enum IA2ScrollType scrollType | |
| 600 ); | |
| 601 | |
| 602 /** @brief Moves the top left of a substring to a specified location. | |
| 603 | |
| 604 @param [in] startIndex | |
| 605 0 based character offset. | |
| 606 @param [in] endIndex | |
| 607 0 based character offset - the offset of the character just past the last character of the string. | |
| 608 @param [in] coordinateType | |
| 609 Specifies whether the coordinates are relative to the screen or the parent object. | |
| 610 @param [in] x | |
| 611 Defines the x coordinate. | |
| 612 @param [in] y | |
| 613 Defines the y coordinate. | |
| 614 @retval S_OK | |
| 615 @retval S_FALSE if the object is already at the specified location. | |
| 616 @retval E_INVALIDARG if bad [in] passed | |
| 617 @note Refer to @ref _specialOffsets | |
| 618 "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods" | |
| 619 for information about special offsets that can be used in %IAccessibleText methods. | |
| 620 */ | |
| 621 HRESULT scrollSubstringToPoint | |
| 622 ( | |
| 623 [in] long startIndex, | |
| 624 [in] long endIndex, | |
| 625 [in] enum IA2CoordinateType coordinateType, | |
| 626 [in] long x, | |
| 627 [in] long y | |
| 628 ); | |
| 629 | |
| 630 /** @brief Returns any inserted text. | |
| 631 | |
| 632 Provided for use by the ::IA2_EVENT_TEXT_INSERTED and ::IA2_EVENT_TEXT_UPDATED | |
| 633 event handlers. | |
| 634 | |
| 635 This data is only guaranteed to be valid while the thread notifying the event | |
| 636 continues. Once the handler has returned, the validity of the data depends on | |
| 637 how the server manages the life cycle of its objects. Also, note that the server | |
| 638 may have different life cycle management strategies for controls depending on | |
| 639 whether or not a control manages its children. Lists, trees, and tables can have | |
| 640 a large number of children and thus it's possible that the child objects for those | |
| 641 controls would only be created as needed. Servers should document their life cycle | |
| 642 strategy as this will be of interest to assistive technology or script engines | |
| 643 accessing data out of process or from other threads. Servers only need to save the | |
| 644 last inserted block of text and a scope of the entire application is adequate. | |
| 645 | |
| 646 @param [out] newText | |
| 647 The text that was just inserted. | |
| 648 @retval S_OK | |
| 649 @retval S_FALSE If there is nothing to return, the values of IA2TextSegment | |
| 650 struct are set as follows: text = NULL, start = 0, end = 0. | |
| 651 | |
| 652 */ | |
| 653 [propget] HRESULT newText | |
| 654 ( | |
| 655 [out, retval] IA2TextSegment *newText | |
| 656 ); | |
| 657 | |
| 658 /** @brief Returns any removed text. | |
| 659 | |
| 660 Provided for use by the IA2_EVENT_TEXT_REMOVED/UPDATED event handlers. | |
| 661 | |
| 662 This data is only guaranteed to be valid while the thread notifying the event | |
| 663 continues. Once the handler has returned, the validity of the data depends on | |
| 664 how the server manages the life cycle of its objects. Also, note that the server | |
| 665 may have different life cycle management strategies for controls depending on | |
| 666 whether or not a control manages its children. Lists, trees, and tables can have | |
| 667 a large number of children and thus it's possible that the child objects for those | |
| 668 controls would only be created as needed. Servers should document their life cycle | |
| 669 strategy as this will be of interest to assistive technology or script engines | |
| 670 accessing data out of process or from other threads. Servers only need to save the | |
| 671 last removed block of text and a scope of the entire application is adequate. | |
| 672 | |
| 673 @param [out] oldText | |
| 674 The text that was just removed. | |
| 675 @retval S_OK | |
| 676 @retval S_FALSE If there is nothing to return, the values of IA2TextSegment | |
| 677 struct are set as follows: text = NULL, start = 0, end = 0. | |
| 678 */ | |
| 679 [propget] HRESULT oldText | |
| 680 ( | |
| 681 [out, retval] IA2TextSegment *oldText | |
| 682 ); | |
| 683 | |
| 684 } |
