1/************************************************************************* 2 * 3 * File Name (Accessible2.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/** @mainpage 55 56 @section _interfaces Interfaces 57 IAccessible2\n 58 IAccessible2_2\n 59 IAccessible2_3\n 60 IAccessibleAction\n 61 IAccessibleApplication\n 62 IAccessibleComponent\n 63 IAccessibleDocument\n 64 IAccessibleEditableText\n 65 IAccessibleHypertext\n 66 IAccessibleHypertext2\n 67 IAccessibleHyperlink\n 68 IAccessibleImage\n 69 IAccessibleRelation\n 70 IAccessibleTable [Deprecated]\n 71 IAccessibleTable2\n 72 IAccessibleTableCell\n 73 IAccessibleText\n 74 IAccessibleText2\n 75 IAccessibleValue 76 77 @section _structs Structs 78 IA2Locale\n 79 IA2Range\n 80 IA2TableModelChange\n 81 IA2TextSegment 82 83 @section _enums Enums 84 ::IA2Actions values are predefined actions for use when implementing support for HTML5 media.\n 85 ::IA2CoordinateType values define the requested coordinate type (screen or parent window).\n 86 ::IA2EventID values identify events.\n 87 ::IA2Role values defines roles which are in addition to the existing MSAA roles.\n 88 ::IA2ScrollType values define where to place an object or substring on the screen.\n 89 ::IA2States values define states which are in addition to the existing MSAA states.\n 90 ::IA2TableModelChangeType values describe the kinds of changes made to a table (insert, delete, update).\n 91 ::IA2TextBoundaryType values define the requested text unit (character, word, sentence, line, paragraph).\n 92 ::IA2TextSpecialOffsets values define special offsets for use in the text interfaces. 93 94 @section _constants Constants 95 @ref grpRelations 96 97 @section _misc Miscellaneous 98 @ref _licensePage "BSD License"\n 99 @ref _generalInfo "General Information"\n 100 101 @page _licensePage BSD License 102 %IAccessible2 IDL Specification 103 104 Copyright (c) 2007, 2013 Linux Foundation\n 105 Copyright (c) 2006 IBM Corporation\n 106 Copyright (c) 2000, 2006 Sun Microsystems, Inc.\n 107 All rights reserved. 108 109 Redistribution and use in source and binary forms, with or without 110 modification, are permitted provided that the following conditions 111 are met: 112 113 1. Redistributions of source code must retain the above copyright 114 notice, this list of conditions and the following disclaimer. 115 116 2. Redistributions in binary form must reproduce the above 117 copyright notice, this list of conditions and the following 118 disclaimer in the documentation and/or other materials 119 provided with the distribution. 120 121 3. Neither the name of the Linux Foundation nor the names of its 122 contributors may be used to endorse or promote products 123 derived from this software without specific prior written 124 permission. 125 126 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 127 CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 128 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 129 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 130 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 131 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 132 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 133 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 134 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 135 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 136 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 137 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 138 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 139 140 This BSD License conforms to the Open Source Initiative "Simplified 141 BSD License" as published at: 142 http://www.opensource.org/licenses/bsd-license.php 143 144 %IAccessible2 is a trademark of the Linux Foundation. The %IAccessible2 145 mark may be used in accordance with the 146 <a href="http://www.linuxfoundation.org/collaborate/workgroups/accessibility/trademark-policy"> 147 Linux Foundation Trademark Policy</a> to indicate compliance with the %IAccessible2 specification. 148 149 @page _generalInfo General Information 150 The following information is applicable to two or more interfaces. 151 152 @ref _errors\n 153 @ref _memory\n 154 @ref _arrayConsideration\n 155 @ref _indexes\n 156 @ref _enums\n 157 @ref _specialOffsets\n 158 @ref _dicoveringInterfaces\n 159 @ref _changingInterfaces\n 160 @ref _applicationInfo\n 161 @ref _childIDs\n 162 @ref _variants\n 163 @ref _iaaction-iahyperlink\n 164 @ref _trademark 165 166 @section _errors Error Handling 167 HRESULT values are defined by the Microsoft® Win32® API. For more information, refer to 168 <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa378137%28v=vs.85%29.aspx"> 169 Interpreting HRESULT Values</a> in MSDN®. 170 171 Note that the S_FALSE return value is considered a non-error value and the 172 SUCCEEDED macro will return TRUE. S_FALSE is used when there is no failure 173 but there was nothing valid to return, e.g. in IAccessible2::attributes when 174 there are no attributes. When S_FALSE is returned [out] pointer types should 175 be NULL and [out] longs should generally be 0, but sometimes -1 is used such 176 as IAccessible2::indexInParent, IAccessibleText::caretOffset, and 177 IAccessibleHypertext::hyperlinkIndex. 178 179 Note that for BSTR [out] variables common COM practice is that the server does 180 the SysAllocString and the client does the SysFreeString. Also note that when 181 NULL is returned there is no need for the client to call SysFreeString. Please 182 refer to the documentation for each method for more details regarding error handling. 183 184 @section _memory Memory Management 185 The following memory management issues should be considered: 186 @li Although [out] BSTR variables are declared by the client, their space is 187 allocated by the server. They need to be freed with SysFreeString by the 188 client at end of life; the same is true when BSTRs are used in structs or 189 arrays which are passed to the server. 190 @li If there is no valid [out] BSTR to return, the server should return S_FALSE and 191 assign NULL to the output, e.g. *theOutBSTR = NULL;. 192 @li COM interfaces need to be referenced with AddRef when used and dereferenced 193 with Release at end of life. 194 @li Single [out] longs, HWNDs, booleans, and structs are declared by the caller 195 and passed by reference. The marshaller does all the memory management. 196 197 The following articles may be helpful for understanding memory management issues: 198 @li An article by Don Box in a 199 <a href="http://www.microsoft.com/msj/1196/activex1196.aspx">Q & A section</a> 200 of the November 1996 edition of the Microsoft Systems Journal. 201 @li A posting to a CodeGuru forum, 202 <a href="http://www.codeguru.com/forum/showthread.php?t=364511">Windows SDK 203 String: What are the rules for BSTR allocation and deallocation?</a> 204 205 @subsection _arrayConsideration Special Consideration when using Arrays 206 There are several methods which return arrays. In the case of IAccessible2::relations 207 and IAccessibleRelation::targets the client must allocate and free the arrays. 208 209 For the remaining methods which return arrays, the server must allocate the array 210 and the client must free the array when no longer needed. These methods are 211 IAccessible2::extendedStates, IAccessible2::localizedExtendedStates, 212 IAccessible2_2::relationTargetsOfType, IAccessibleAction::keyBinding, 213 IAccessibleHypertext2::hyperlinks, IAccessibleTable::selectedChildren, 214 IAccessibleTable::selectedColumns, IAccessibleTable::selectedRows, 215 IAccessibleTable2::selectedCells, IAccessibleTable2::selectedColumns, 216 IAccessibleTable2::selectedRows, IAccessibleTableCell::columnHeaderCells, 217 and IAccessibleTableCell::rowHeaderCells. 218 For those methods, the server must allocate both the top level array and any storage 219 associated with it, e.g. for BSTRs. The server must allocate the arrays with 220 CoTaskMemAlloc and any BSTRs with SysAllocString. The client must use CoTaskMemFree 221 to free the array and any BSTRs must be freed with SysFreeString. 222 223 Also, the IDL for IAccessible2::extendedStates, IAccessible2::localizedExtendedStates, 224 IAccessibleAction::keyBinding, IAccessibleTable::selectedChildren, 225 IAccessibleTable::selectedColumns, and IAccessibleTable::selectedRows includes an 226 extraneous [in] parameter for the caller to specify the max size of the array. 227 This parameter will be ignored by the COM server. 228 229 @section _indexes Zero and One Based Indexes 230 Unless otherwise specified all offsets and indexes are 0 based. 231 232 @section _enums Enums 233 Note that enums start at 0. 234 235 @section _specialOffsets Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods 236 IAccessibleText and IAccessibleEditableText can use one or more of the following 237 special offset values. They are defined in the ::IA2TextSpecialOffsets enum. 238 @li Using ::IA2_TEXT_OFFSET_LENGTH (-1) as an offset in any of the IAccessibleText or 239 IAccessibleEditableText methods is the same as specifying the length of the string. 240 @li Using ::IA2_TEXT_OFFSET_CARET (-2) as an offset for IAccessibleText::textBeforeOffset, 241 IAccessibleText::textAtOffset, and IAccessibleText::textAfterOffset indicates that the 242 text related to the physical location of the caret should be used. This is needed for 243 applications that consider the character offset of the end of one line (as reached by 244 pressing the End key) the same as the offset of the first character on the next line. 245 Since the same offset is associated with two different lines a special means is needed 246 to fetch text from the line where the caret is physically located. 247 248 @section _dicoveringInterfaces Discovery of Interfaces 249 In general AT (Assistive Technology) should try IAccessible2 interfaces, followed by using 250 the MSAA (Microsoft® Active Accessibility®) interfaces. (In cases where the an application 251 is known to have custom interfaces which provide information not supplied by IAccessible2 252 or MSAA, then those custom interfaces can be used.) The AT can then, by default, support 253 unknown IAccessible2/MSAA applications, without the application developers having to request 254 AT vendors for support on an individual application by application basis. 255 256 When you have a reference to an IAccessible and require a reference to an IAccessible2 use 257 QueryService as follows: 258 @code 259 // pAcc is a reference to the accessible object's IAccessible interface. 260 IServiceProvider *pService = NULL; 261 hr = pAcc->QueryInterface(IID_IServiceProvider, (void **)&pService); 262 if(SUCCEEDED(hr)) { 263 IAccessible2 *pIA2 = NULL; 264 hr = pService->QueryService(IID_IAccessible, IID_IAccessible2, (void**)&pIA2); 265 if (SUCCEEDED(hr) && pIA2) { 266 // The control supports IAccessible2. 267 // pIA2 is the reference to the accessible object's IAccessible2 interface. 268 } 269 } 270 @endcode 271 272 @section _changingInterfaces Changing between Accessible Interfaces 273 Note that developers must always implement MSAA's IAccessible and, if needed, some 274 of the interfaces in the set of IAccessible2 interfaces. Although the IAccessible2 275 IDL is coded such that IAccessible2 is a subclass of MSAA's IAccessible, none of 276 MSAA's IAccessible methods are redefined by IAccessible2. 277 278 QueryService must be used to switch from a reference to an MSAA IAccessible interface 279 to another interface. This has been 280 <a href="http://www.atia.org/files/public/Introducing_IAccessibleEx.doc"> 281 documented</a> and the pertinent facts have been extracted below: 282 283 @par 284 Why use QueryService instead of just using QueryInterface to get IAccessibleEx 285 directly? The reason is that since MSAA 2.0, clients don't talk to a server's 286 IAccessible interface directly; instead they talk to an intermediate MSAA-provided 287 wrapper that calls through to the original IAccessible. This wrapper provides services 288 such as implementing IDispatch, supplying information from MSAA 2.0's Dynamic Annotation 289 service, and scaling locations when running on Windows Vista with DPI scaling enabled. 290 QueryService is the supported way to expose additional interfaces from an existing 291 IAccessible and was originally used by MSHTML to expose IHTMLElement objects corresponding 292 to IAccessibles. QueryService is often more convenient for servers to implement than 293 QueryInterface because it does not have the same requirements for preserving object 294 identity or symmetry/transitivity as QueryInterface, so QueryService allows servers to 295 easily implement the interface on the same object or a separate object. The latter is 296 often hard to do with QueryInterface unless the original object supports aggregation. 297 298 Two related references in MSDN® are: 299 @li <a href="http://msdn.microsoft.com/en-us/library/ms696078(VS.85).aspx"> 300 "Using QueryService to expose a native object model interface for an IAccessible object"</a> 301 @li <a href="http://msdn.microsoft.com/en-us/library/ms528415.aspx#acc_obj"> 302 "Accessing the Internet Explorer Object Associated with an Accessible Object"</a> 303 304 Based on this information from Microsoft, QueryService must be used to switch back and forth 305 between a reference to an MSAA IAccessible interface and any of the IAccessible2 interfaces. 306 307 Regarding switching between any of the IAccessible2 interfaces, applications implementing 308 IAccessible2 should implement the IAccessible2 interfaces on a single object since ATs 309 will be using QueryInterface to switch between the IAccessilbe2 interfaces. Implementing 310 the IAccessible2 interfaces on separate objects would require the use of QueryService. 311 There is one exception, IAccessibleApplication can be implemented on a separate object so 312 its common code doesn't have to be included in each accessible object. ATs should use 313 QueryService to access IAccessibleApplication. 314 315 @section _applicationInfo Access to Information about the Application 316 Servers implementing IAccessible2 should provide access to the IAccessibleApplication 317 interface via QueryService from any object so that ATs can easily determine specific 318 information about the application such as its name or version. 319 320 @section _childIDs Child IDs 321 The IAccessible2 interfaces do not support child IDs, i.e. simple child elements. 322 Full accessible objects must be created for each object that supports IAccessible2. 323 Therefore MSAA's get_accChild should never return a child ID (other than CHILDID_SELF) 324 for an object that implements any of the IAccessible2 interfaces. 325 326 Microsoft's UI Automation specification has the same limitation and this was resolved 327 in the UI Automation Express specification by adding IAccessibleEx::GetObjectForChild 328 and IAccessibleEx::GetIAccessiblePair. These methods allow mapping back and forth 329 between an IAccessibleEx and an {IAccessible, Child ID} pair. A future version of 330 IAccessible2 may include similar methods to map back and forth between an IAccessible2 331 and an {IAccessible, Child ID} pair. 332 333 @section _variants VARIANTs 334 Some methods return a VARIANT. Implementers need to make sure that the return type is 335 specified, i.e. VT_I4, VT_IDISPATCH, etc. The methods that return VARIANTs are 336 IAccessibleHyperlink::anchor, IAccessibleHyperlink::anchorTarget, IAccessibleValue::currentValue, 337 IAccessibleValue::maximumValue, IAccessibleValue::minimumValue. 338 339 @section _iaaction-iahyperlink IAccessibleHyperlink as subclass of IAccessibleAction 340 In this version of the IDL, IAccessibleHyperlink is a subclass of IAccessibleAction. 341 However, there is no practical need for that inheritance and in some cases, such as 342 an image map of smart tags, it doesn't make sense because such an image map doesn't 343 have actionable objects; it's the secondary smart tags that are actionable. As a 344 result, implementations should not rely on the inheritance as it may be removed in 345 a later version of the IDL. 346 347 @section _trademark Trademark Attribution 348 The names of actual companies and products mentioned herein may be the trademarks of 349 their respective owners. In particular, Active Accessibility, Microsoft, MSDN, and Win32 350 are trademarks of the Microsoft group of companies in the U.S.A. and/or other countries. 351 352**/ 353 354import "objidl.idl"; 355import "oaidl.idl"; 356import "oleacc.idl"; 357import "AccessibleRelation.idl"; 358import "AccessibleStates.idl"; 359import "IA2CommonTypes.idl"; 360 361/** A structure defining the locale of an accessible object. 362 363IAccessible2::locale returns this struct. 364*/ 365typedef struct IA2Locale { 366 BSTR language; ///< ISO 639-1 Alpha-2 two character language code 367 BSTR country; ///< ISO 3166-1 Alpha-2 two character country code 368 BSTR variant; ///< Application specific variant of the locale 369} IA2Locale; 370 371/** @brief This interface exposes the primary set of information about an 372 IAccessible2 enabled accessible object. 373 374 This interface must always be provided for objects that support some 375 portion of the collection of the %IAccessible2 interfaces. 376 377 Please refer to @ref _changingInterfaces "Changing between Accessible Interfaces" 378 for special considerations related to use of the MSAA IAccessible interface and 379 the set of %IAccessible2 interfaces. 380 */ 381[object, uuid(E89F726E-C4F4-4c19-BB19-B647D7FA8478)] 382interface IAccessible2 : IAccessible 383{ 384 385 /** @brief Returns the number of accessible relations for this object. 386 @param [out] nRelations 387 @retval S_OK 388 */ 389 [propget] HRESULT nRelations 390 ( 391 [out, retval] long *nRelations 392 ); 393 394 /** @brief Returns one accessible relation for this object. 395 @param [in] relationIndex 396 0 based 397 @param [out] relation 398 @retval S_OK 399 @retval E_INVALIDARG if bad [in] passed 400 */ 401 [propget] HRESULT relation 402 ( 403 [in] long relationIndex, 404 [out, retval] IAccessibleRelation **relation 405 ); 406 407 /** @brief Returns multiple accessible relations for this object. 408 @param [in] maxRelations 409 maximum size of the array allocated by the client 410 @param [out] relations 411 The array of accessible relation objects. Note that this array is to be 412 allocated by the client and freed when no longer needed. Refer to @ref 413 _arrayConsideration "Special Consideration when using Arrays" for more details. 414 @param [out] nRelations 415 actual number of relations in the returned array (not more than maxRelations) 416 @retval S_OK 417 @retval S_FALSE if there are no relations, nRelations is set to 0 418 @note As a performant alternative, client code should consider using IAccessible2_2::relationTargetsOfType. 419 */ 420 [propget] HRESULT relations 421 ( 422 [in] long maxRelations, 423 [out, size_is(maxRelations), length_is(*nRelations)] 424 IAccessibleRelation **relations, 425 [out, retval] long *nRelations 426 ); 427 428 /** @brief Returns the role of an %IAccessible2 object. 429 @param [out] role 430 The role of an %IAccessible2 object. 431 @retval S_OK 432 @note 433 @li For convenience MSAA roles are also passed through this method so the 434 AT doesn't have to also fetch roles through MSAA's get_accRole. 435 @li %IAccessible2 roles should not be passed through MSAA's get_accRole. 436 @li For compatibility with non IAccessible2 enabled ATs, IAccessible2 437 applications should also add support to get_accRole to return the closest 438 MSAA role or ROLE_SYSTEM_CLIENT (the MSAA defined default role) if there 439 is not a good match. 440 @li This method is missing a [propget] prefix in the IDL. The result is the 441 method is named role in generated C++ code instead of get_role. 442 */ 443 HRESULT role 444 ( 445 [out, retval] long *role 446 ); 447 448 /** @brief Makes an object visible on the screen. 449 @param [in] scrollType 450 Defines where the object should be placed on the screen. 451 @retval S_OK 452 @retval E_INVALIDARG if bad [in] passed 453 */ 454 HRESULT scrollTo 455 ( 456 [in] enum IA2ScrollType scrollType 457 ); 458 459 /** @brief Moves the top left of an object to a specified location. 460 461 @param [in] coordinateType 462 Specifies whether the coordinates are relative to the screen or the parent object. 463 @param [in] x 464 Defines the x coordinate. 465 @param [in] y 466 Defines the y coordinate. 467 @retval S_OK 468 @retval E_INVALIDARG if bad [in] passed 469 */ 470 HRESULT scrollToPoint 471 ( 472 [in] enum IA2CoordinateType coordinateType, 473 [in] long x, 474 [in] long y 475 ); 476 477 /** @brief Returns grouping information. 478 479 Used for tree items, list items, tab panel labels, radio buttons, etc. 480 Also used for collections of non-text objects. 481 482 @param [out] groupLevel 483 1 based, 0 indicates that this value is not applicable 484 @param [out] similarItemsInGroup 485 1 based, 0 indicates that this value is not applicable 486 @param [out] positionInGroup 487 1 based, 0 indicates that this value is not applicable. This is an index 488 into the objects in the current group, not an index into all the objects 489 at the same group level. 490 @retval S_OK if at least one value is valid 491 @retval S_FALSE if no values are valid, [out] values are 0s 492 @note This method is meant to describe the nature of an object's containment 493 structure. It's exposed by trees, tree grids, nested lists, nested menus, 494 but not headings, which uses the level object attribute. It is also exposed 495 by radio buttons (with groupLevel == 0). 496 @note This is normally not implemented on a combo box to describe the nature 497 of its contents. Normally an AT will get that information from its child list 498 object. However, in some cases when non-edit combo boxes are not able to be structured 499 such that the list is a child of the combo box, this method is implemented on 500 the combo box itself. ATs can use this interface if a child list is not found. 501 */ 502 [propget] HRESULT groupPosition 503 ( 504 [out] long *groupLevel, 505 [out] long *similarItemsInGroup, 506 [out, retval] long *positionInGroup 507 ); 508 509 /** @brief Returns the bit strip containing any IAccessible2 states. 510 511 The IAccessible2 states are in addition to the MSAA states and are defined in 512 the IA2States enum. 513 514 @param [out] states 515 @retval S_OK 516 */ 517 [propget] HRESULT states 518 ( 519 [out, retval] AccessibleStates *states 520 ); 521 522 /** @brief Returns the extended role. 523 524 An extended role is a role which is dynamically generated by the application. 525 It is not predefined by the %IAccessible2 specification. 526 527 @param [out] extendedRole 528 @retval S_OK 529 @retval S_FALSE if there is nothing to return, [out] value is NULL 530 */ 531 [propget] HRESULT extendedRole 532 ( 533 [out, retval] BSTR *extendedRole 534 ); 535 536 /** @brief Returns the localized extended role. 537 @param [out] localizedExtendedRole 538 @retval S_OK 539 @retval S_FALSE if there is nothing to return, [out] value is NULL 540 */ 541 [propget] HRESULT localizedExtendedRole 542 ( 543 [out, retval] BSTR *localizedExtendedRole 544 ); 545 546 /** @brief Returns the number of extended states. 547 @param [out] nExtendedStates 548 @retval S_OK 549 */ 550 [propget] HRESULT nExtendedStates 551 ( 552 [out, retval] long *nExtendedStates 553 ); 554 555 /** @brief Returns the extended states (array of strings). 556 557 An extended state is a state which is dynamically generated by the application. 558 It is not predefined by the %IAccessible2 specification. 559 560 @param [in] maxExtendedStates 561 This parameter is ignored. Refer to @ref _arrayConsideration 562 "Special Consideration when using Arrays" for more details. 563 @param [out] extendedStates 564 This array is allocated by the server. The client must free it with CoTaskMemFree. 565 @param [out] nExtendedStates 566 The number of extended states returned; the size of the returned array. 567 @retval S_OK 568 @retval S_FALSE if there are no states, [out] values are NULL and 0 respectively 569 */ 570 [propget] HRESULT extendedStates 571 ( 572 [in] long maxExtendedStates, 573 [out, size_is(,maxExtendedStates), length_is(,*nExtendedStates)] BSTR **extendedStates, 574 [out, retval] long *nExtendedStates 575 ); 576 577 /** @brief Returns the localized extended states (array of strings). 578 579 @param [in] maxLocalizedExtendedStates 580 This parameter is ignored. Refer to @ref _arrayConsideration 581 "Special Consideration when using Arrays" for more details. 582 @param [out] localizedExtendedStates 583 This array is allocated by the server. The client must free it with CoTaskMemFree. 584 @param [out] nLocalizedExtendedStates 585 The number of localized extended states returned; the size of the returned array. 586 @retval S_OK 587 @retval S_FALSE if there are no states, [out] values are NULL and 0 respectively 588 */ 589 [propget] HRESULT localizedExtendedStates 590 ( 591 [in] long maxLocalizedExtendedStates, 592 [out, size_is(,maxLocalizedExtendedStates), length_is(,*nLocalizedExtendedStates)] BSTR **localizedExtendedStates, 593 [out, retval] long *nLocalizedExtendedStates 594 ); 595 596 /** @brief Returns the unique ID. 597 598 The uniqueID is an identifier for this object, is unique within the 599 current window, and remains the same for the lifetime of the accessible 600 object. 601 602 The uniqueID is not related to: 603 - the MSAA objectID which is used by the server to disambiguate between 604 IAccessibles per HWND or 605 - the MSAA childID which is used to disambiguate between children being 606 managed by an IAccessible. 607 608 This value is provided so the AT can have access to a unique runtime persistent 609 identifier even when not handling an event for the object. 610 611 An example of when this value is useful is if the AT wants to build a cache. 612 The AT could cache the uniqueIDs in addition to other data being cached. 613 When an event is fired the AT could map the uniqueID to its internal model. 614 Thus, if there's a REORDER/SHOW/HIDE event the AT knows which part of the 615 internal structure has been invalidated and can refetch just that part. 616 617 This value can also be used by an AT to determine when the current control 618 has changed. If the role is the same for two controls that are adjacent in 619 the tab order, this can be used to detect the new control. 620 621 Another use of this value by an AT is to identify when a grouping object has 622 changed, e.g. when moving from a radio button in one group to a radio button in a 623 different group. 624 625 One means of implementing this would be to create a factory with a 32 bit number 626 generator and a reuse pool. The number generator would emit numbers starting 627 at 1. Each time an object's life cycle ended, its number would be saved into a 628 reuse pool. The number generator would be used whenever the reuse pool was empty. 629 630 Another way to create a unique ID is to generate it from a pointer value, e.g. an 631 object's address. That would be unique because no two active objects can use the 632 same allocated memory space. 633 634 @param [out] uniqueID 635 @retval S_OK 636 */ 637 [propget] HRESULT uniqueID 638 ( 639 [out, retval] long *uniqueID 640 ); 641 642 /** @brief Returns the window handle for the parent window which contains this object. 643 644 This is the same window handle which will be passed for any events that occur on the 645 object, but is cached in the accessible object for use when it would be helpful to 646 access the window handle in cases where an event isn't fired on this object. 647 648 A use case is when a screen reader is grabbing an entire web page on a page load. 649 Without the availability of windowHandle, the AT would have to get the window handle 650 by using WindowFromAccessibleObject on each IAccessible, which is slow because it's 651 implemented by oleacc.dll as a loop which crawls up the ancestor chain and looks for 652 a ROLE_WINDOW object, mapping that back to a window handle. 653 654 @param [out] windowHandle 655 @retval S_OK 656 */ 657 [propget] HRESULT windowHandle 658 ( 659 [out, retval] HWND *windowHandle 660 ); 661 662 /** @brief Returns the index of this object in its parent object. 663 @param [out] indexInParent 664 0 based; -1 indicates there is no parent; the upper bound is the value 665 returned by the parent's IAccessible::get_accChildCount. 666 @retval S_OK 667 @retval S_FALSE if no parent, [out] value is -1 668 */ 669 [propget] HRESULT indexInParent 670 ( 671 [out, retval] long *indexInParent 672 ); 673 674 /** @brief Returns the IA2Locale of the accessible object. 675 @param [out] locale 676 @retval S_OK 677 */ 678 [propget] HRESULT locale 679 ( 680 [out, retval] IA2Locale *locale 681 ); 682 683 /** @brief Returns the attributes specific to this object, such as a cell's formula. 684 @param [out] attributes 685 @retval S_OK 686 @retval S_FALSE returned if there is nothing to return, [out] value is NULL 687 */ 688 [propget] HRESULT attributes 689 ( 690 [out, retval] BSTR *attributes 691 ); 692 693} 694 695