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