1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/other-licenses/ia2/Accessible2.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,692 @@
1.4 +/*************************************************************************
1.5 + *
1.6 + * File Name (Accessible2.idl)
1.7 + *
1.8 + * IAccessible2 IDL Specification
1.9 + *
1.10 + * Copyright (c) 2007, 2013 Linux Foundation
1.11 + * Copyright (c) 2006 IBM Corporation
1.12 + * Copyright (c) 2000, 2006 Sun Microsystems, Inc.
1.13 + * All rights reserved.
1.14 + *
1.15 + *
1.16 + * Redistribution and use in source and binary forms, with or without
1.17 + * modification, are permitted provided that the following conditions
1.18 + * are met:
1.19 + *
1.20 + * 1. Redistributions of source code must retain the above copyright
1.21 + * notice, this list of conditions and the following disclaimer.
1.22 + *
1.23 + * 2. Redistributions in binary form must reproduce the above
1.24 + * copyright notice, this list of conditions and the following
1.25 + * disclaimer in the documentation and/or other materials
1.26 + * provided with the distribution.
1.27 + *
1.28 + * 3. Neither the name of the Linux Foundation nor the names of its
1.29 + * contributors may be used to endorse or promote products
1.30 + * derived from this software without specific prior written
1.31 + * permission.
1.32 + *
1.33 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
1.34 + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
1.35 + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.36 + * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1.37 + * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
1.38 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.39 + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
1.40 + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
1.41 + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1.42 + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
1.43 + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1.44 + * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
1.45 + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.46 + *
1.47 + * This BSD License conforms to the Open Source Initiative "Simplified
1.48 + * BSD License" as published at:
1.49 + * http://www.opensource.org/licenses/bsd-license.php
1.50 + *
1.51 + * IAccessible2 is a trademark of the Linux Foundation. The IAccessible2
1.52 + * mark may be used in accordance with the Linux Foundation Trademark
1.53 + * Policy to indicate compliance with the IAccessible2 specification.
1.54 + *
1.55 + ************************************************************************/
1.56 +
1.57 +/** @mainpage
1.58 +
1.59 + @section _interfaces Interfaces
1.60 + IAccessible2\n
1.61 + IAccessible2_2\n
1.62 + IAccessibleAction\n
1.63 + IAccessibleApplication\n
1.64 + IAccessibleComponent\n
1.65 + IAccessibleDocument\n
1.66 + IAccessibleEditableText\n
1.67 + IAccessibleHypertext\n
1.68 + IAccessibleHypertext2\n
1.69 + IAccessibleHyperlink\n
1.70 + IAccessibleImage\n
1.71 + IAccessibleRelation\n
1.72 + IAccessibleTable [Deprecated]\n
1.73 + IAccessibleTable2\n
1.74 + IAccessibleTableCell\n
1.75 + IAccessibleText\n
1.76 + IAccessibleText2\n
1.77 + IAccessibleValue
1.78 +
1.79 + @section _structs Structs
1.80 + IA2Locale\n
1.81 + IA2TableModelChange\n
1.82 + IA2TextSegment
1.83 +
1.84 + @section _enums Enums
1.85 + ::IA2Actions values are predefined actions for use when implementing support for HTML5 media.\n
1.86 + ::IA2CoordinateType values define the requested coordinate type (screen or parent window).\n
1.87 + ::IA2EventID values identify events.\n
1.88 + ::IA2Role values defines roles which are in addition to the existing MSAA roles.\n
1.89 + ::IA2ScrollType values define where to place an object or substring on the screen.\n
1.90 + ::IA2States values define states which are in addition to the existing MSAA states.\n
1.91 + ::IA2TableModelChangeType values describe the kinds of changes made to a table (insert, delete, update).\n
1.92 + ::IA2TextBoundaryType values define the requested text unit (character, word, sentence, line, paragraph).\n
1.93 + ::IA2TextSpecialOffsets values define special offsets for use in the text interfaces.
1.94 +
1.95 + @section _constants Constants
1.96 + @ref grpRelations
1.97 +
1.98 + @section _misc Miscellaneous
1.99 + @ref _licensePage "BSD License"\n
1.100 + @ref _generalInfo "General Information"\n
1.101 +
1.102 + @page _licensePage BSD License
1.103 + %IAccessible2 IDL Specification
1.104 +
1.105 + Copyright (c) 2007, 2013 Linux Foundation\n
1.106 + Copyright (c) 2006 IBM Corporation\n
1.107 + Copyright (c) 2000, 2006 Sun Microsystems, Inc.\n
1.108 + All rights reserved.
1.109 +
1.110 + Redistribution and use in source and binary forms, with or without
1.111 + modification, are permitted provided that the following conditions
1.112 + are met:
1.113 +
1.114 + 1. Redistributions of source code must retain the above copyright
1.115 + notice, this list of conditions and the following disclaimer.
1.116 +
1.117 + 2. Redistributions in binary form must reproduce the above
1.118 + copyright notice, this list of conditions and the following
1.119 + disclaimer in the documentation and/or other materials
1.120 + provided with the distribution.
1.121 +
1.122 + 3. Neither the name of the Linux Foundation nor the names of its
1.123 + contributors may be used to endorse or promote products
1.124 + derived from this software without specific prior written
1.125 + permission.
1.126 +
1.127 + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
1.128 + CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
1.129 + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.130 + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1.131 + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
1.132 + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.133 + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
1.134 + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
1.135 + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1.136 + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
1.137 + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1.138 + OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
1.139 + EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.140 +
1.141 + This BSD License conforms to the Open Source Initiative "Simplified
1.142 + BSD License" as published at:
1.143 + http://www.opensource.org/licenses/bsd-license.php
1.144 +
1.145 + %IAccessible2 is a trademark of the Linux Foundation. The %IAccessible2
1.146 + mark may be used in accordance with the
1.147 + <a href="http://www.linuxfoundation.org/collaborate/workgroups/accessibility/trademark-policy">
1.148 + Linux Foundation Trademark Policy</a> to indicate compliance with the %IAccessible2 specification.
1.149 +
1.150 + @page _generalInfo General Information
1.151 + The following information is applicable to two or more interfaces.
1.152 +
1.153 + @ref _errors\n
1.154 + @ref _memory\n
1.155 + @ref _arrayConsideration\n
1.156 + @ref _indexes\n
1.157 + @ref _enums\n
1.158 + @ref _specialOffsets\n
1.159 + @ref _dicoveringInterfaces\n
1.160 + @ref _changingInterfaces\n
1.161 + @ref _applicationInfo\n
1.162 + @ref _childIDs\n
1.163 + @ref _variants\n
1.164 + @ref _iaaction-iahyperlink\n
1.165 + @ref _trademark
1.166 +
1.167 + @section _errors Error Handling
1.168 + HRESULT values are defined by the Microsoft® Win32® API. For more information, refer to
1.169 + <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa378137%28v=vs.85%29.aspx">
1.170 + Interpreting HRESULT Values</a> in MSDN®.
1.171 +
1.172 + Note that the S_FALSE return value is considered a non-error value and the
1.173 + SUCCEEDED macro will return TRUE. S_FALSE is used when there is no failure
1.174 + but there was nothing valid to return, e.g. in IAccessible2::attributes when
1.175 + there are no attributes. When S_FALSE is returned [out] pointer types should
1.176 + be NULL and [out] longs should generally be 0, but sometimes -1 is used such
1.177 + as IAccessible2::indexInParent, IAccessibleText::caretOffset, and
1.178 + IAccessibleHypertext::hyperlinkIndex.
1.179 +
1.180 + Note that for BSTR [out] variables common COM practice is that the server does
1.181 + the SysAllocString and the client does the SysFreeString. Also note that when
1.182 + NULL is returned there is no need for the client to call SysFreeString. Please
1.183 + refer to the documentation for each method for more details regarding error handling.
1.184 +
1.185 + @section _memory Memory Management
1.186 + The following memory management issues should be considered:
1.187 + @li Although [out] BSTR variables are declared by the client, their space is
1.188 + allocated by the server. They need to be freed with SysFreeString by the
1.189 + client at end of life; the same is true when BSTRs are used in structs or
1.190 + arrays which are passed to the server.
1.191 + @li If there is no valid [out] BSTR to return, the server should return S_FALSE and
1.192 + assign NULL to the output, e.g. *theOutBSTR = NULL;.
1.193 + @li COM interfaces need to be referenced with AddRef when used and dereferenced
1.194 + with Release at end of life.
1.195 + @li Single [out] longs, HWNDs, booleans, and structs are declared by the caller
1.196 + and passed by reference. The marshaller does all the memory management.
1.197 +
1.198 + The following articles may be helpful for understanding memory management issues:
1.199 + @li An article by Don Box in a
1.200 + <a href="http://www.microsoft.com/msj/1196/activex1196.aspx">Q & A section</a>
1.201 + of the November 1996 edition of the Microsoft Systems Journal.
1.202 + @li A posting to a CodeGuru forum,
1.203 + <a href="http://www.codeguru.com/forum/showthread.php?t=364511">Windows SDK
1.204 + String: What are the rules for BSTR allocation and deallocation?</a>
1.205 +
1.206 + @subsection _arrayConsideration Special Consideration when using Arrays
1.207 + There are several methods which return arrays. In the case of IAccessible2::relations
1.208 + and IAccessibleRelation::targets the client must allocate and free the arrays.
1.209 +
1.210 + For the remaining methods which return arrays, the server must allocate the array
1.211 + and the client must free the array when no longer needed. These methods are
1.212 + IAccessible2::extendedStates, IAccessible2::localizedExtendedStates,
1.213 + IAccessible2_2::relationTargetsOfType, IAccessibleAction::keyBinding,
1.214 + IAccessibleHypertext2::hyperlinks, IAccessibleTable::selectedChildren,
1.215 + IAccessibleTable::selectedColumns, IAccessibleTable::selectedRows,
1.216 + IAccessibleTable2::selectedCells, IAccessibleTable2::selectedColumns,
1.217 + IAccessibleTable2::selectedRows, IAccessibleTableCell::columnHeaderCells,
1.218 + and IAccessibleTableCell::rowHeaderCells.
1.219 + For those methods, the server must allocate both the top level array and any storage
1.220 + associated with it, e.g. for BSTRs. The server must allocate the arrays with
1.221 + CoTaskMemAlloc and any BSTRs with SysAllocString. The client must use CoTaskMemFree
1.222 + to free the array and any BSTRs must be freed with SysFreeString.
1.223 +
1.224 + Also, the IDL for IAccessible2::extendedStates, IAccessible2::localizedExtendedStates,
1.225 + IAccessibleAction::keyBinding, IAccessibleTable::selectedChildren,
1.226 + IAccessibleTable::selectedColumns, and IAccessibleTable::selectedRows includes an
1.227 + extraneous [in] parameter for the caller to specify the max size of the array.
1.228 + This parameter will be ignored by the COM server.
1.229 +
1.230 + @section _indexes Zero and One Based Indexes
1.231 + Unless otherwise specified all offsets and indexes are 0 based.
1.232 +
1.233 + @section _enums Enums
1.234 + Note that enums start at 0.
1.235 +
1.236 + @section _specialOffsets Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods
1.237 + IAccessibleText and IAccessibleEditableText can use one or more of the following
1.238 + special offset values. They are defined in the ::IA2TextSpecialOffsets enum.
1.239 + @li Using ::IA2_TEXT_OFFSET_LENGTH (-1) as an offset in any of the IAccessibleText or
1.240 + IAccessibleEditableText methods is the same as specifying the length of the string.
1.241 + @li Using ::IA2_TEXT_OFFSET_CARET (-2) as an offset for IAccessibleText::textBeforeOffset,
1.242 + IAccessibleText::textAtOffset, and IAccessibleText::textAfterOffset indicates that the
1.243 + text related to the physical location of the caret should be used. This is needed for
1.244 + applications that consider the character offset of the end of one line (as reached by
1.245 + pressing the End key) the same as the offset of the first character on the next line.
1.246 + Since the same offset is associated with two different lines a special means is needed
1.247 + to fetch text from the line where the caret is physically located.
1.248 +
1.249 + @section _dicoveringInterfaces Discovery of Interfaces
1.250 + In general AT (Assistive Technology) should try IAccessible2 interfaces, followed by using
1.251 + the MSAA (Microsoft® Active Accessibility®) interfaces. (In cases where the an application
1.252 + is known to have custom interfaces which provide information not supplied by IAccessible2
1.253 + or MSAA, then those custom interfaces can be used.) The AT can then, by default, support
1.254 + unknown IAccessible2/MSAA applications, without the application developers having to request
1.255 + AT vendors for support on an individual application by application basis.
1.256 +
1.257 + When you have a reference to an IAccessible and require a reference to an IAccessible2 use
1.258 + QueryService as follows:
1.259 + @code
1.260 + // pAcc is a reference to the accessible object's IAccessible interface.
1.261 + IServiceProvider *pService = NULL;
1.262 + hr = pAcc->QueryInterface(IID_IServiceProvider, (void **)&pService);
1.263 + if(SUCCEEDED(hr)) {
1.264 + IAccessible2 *pIA2 = NULL;
1.265 + hr = pService->QueryService(IID_IAccessible, IID_IAccessible2, (void**)&pIA2);
1.266 + if (SUCCEEDED(hr) && pIA2) {
1.267 + // The control supports IAccessible2.
1.268 + // pIA2 is the reference to the accessible object's IAccessible2 interface.
1.269 + }
1.270 + }
1.271 + @endcode
1.272 +
1.273 + @section _changingInterfaces Changing between Accessible Interfaces
1.274 + Note that developers must always implement MSAA's IAccessible and, if needed, some
1.275 + of the interfaces in the set of IAccessible2 interfaces. Although the IAccessible2
1.276 + IDL is coded such that IAccessible2 is a subclass of MSAA's IAccessible, none of
1.277 + MSAA's IAccessible methods are redefined by IAccessible2.
1.278 +
1.279 + QueryService must be used to switch from a reference to an MSAA IAccessible interface
1.280 + to another interface. This has been
1.281 + <a href="http://www.atia.org/files/public/Introducing_IAccessibleEx.doc">
1.282 + documented</a> and the pertinent facts have been extracted below:
1.283 +
1.284 + @par
1.285 + Why use QueryService instead of just using QueryInterface to get IAccessibleEx
1.286 + directly? The reason is that since MSAA 2.0, clients don't talk to a server's
1.287 + IAccessible interface directly; instead they talk to an intermediate MSAA-provided
1.288 + wrapper that calls through to the original IAccessible. This wrapper provides services
1.289 + such as implementing IDispatch, supplying information from MSAA 2.0's Dynamic Annotation
1.290 + service, and scaling locations when running on Windows Vista with DPI scaling enabled.
1.291 + QueryService is the supported way to expose additional interfaces from an existing
1.292 + IAccessible and was originally used by MSHTML to expose IHTMLElement objects corresponding
1.293 + to IAccessibles. QueryService is often more convenient for servers to implement than
1.294 + QueryInterface because it does not have the same requirements for preserving object
1.295 + identity or symmetry/transitivity as QueryInterface, so QueryService allows servers to
1.296 + easily implement the interface on the same object or a separate object. The latter is
1.297 + often hard to do with QueryInterface unless the original object supports aggregation.
1.298 +
1.299 + Two related references in MSDN® are:
1.300 + @li <a href="http://msdn.microsoft.com/en-us/library/ms696078(VS.85).aspx">
1.301 + "Using QueryService to expose a native object model interface for an IAccessible object"</a>
1.302 + @li <a href="http://msdn.microsoft.com/en-us/library/ms528415.aspx#acc_obj">
1.303 + "Accessing the Internet Explorer Object Associated with an Accessible Object"</a>
1.304 +
1.305 + Based on this information from Microsoft, QueryService must be used to switch back and forth
1.306 + between a reference to an MSAA IAccessible interface and any of the IAccessible2 interfaces.
1.307 +
1.308 + Regarding switching between any of the IAccessible2 interfaces, applications implementing
1.309 + IAccessible2 should implement the IAccessible2 interfaces on a single object since ATs
1.310 + will be using QueryInterface to switch between the IAccessilbe2 interfaces. Implementing
1.311 + the IAccessible2 interfaces on separate objects would require the use of QueryService.
1.312 + There is one exception, IAccessibleApplication can be implemented on a separate object so
1.313 + its common code doesn't have to be included in each accessible object. ATs should use
1.314 + QueryService to access IAccessibleApplication.
1.315 +
1.316 + @section _applicationInfo Access to Information about the Application
1.317 + Servers implementing IAccessible2 should provide access to the IAccessibleApplication
1.318 + interface via QueryService from any object so that ATs can easily determine specific
1.319 + information about the application such as its name or version.
1.320 +
1.321 + @section _childIDs Child IDs
1.322 + The IAccessible2 interfaces do not support child IDs, i.e. simple child elements.
1.323 + Full accessible objects must be created for each object that supports IAccessible2.
1.324 + Therefore MSAA's get_accChild should never return a child ID (other than CHILDID_SELF)
1.325 + for an object that implements any of the IAccessible2 interfaces.
1.326 +
1.327 + Microsoft's UI Automation specification has the same limitation and this was resolved
1.328 + in the UI Automation Express specification by adding IAccessibleEx::GetObjectForChild
1.329 + and IAccessibleEx::GetIAccessiblePair. These methods allow mapping back and forth
1.330 + between an IAccessibleEx and an {IAccessible, Child ID} pair. A future version of
1.331 + IAccessible2 may include similar methods to map back and forth between an IAccessible2
1.332 + and an {IAccessible, Child ID} pair.
1.333 +
1.334 + @section _variants VARIANTs
1.335 + Some methods return a VARIANT. Implementers need to make sure that the return type is
1.336 + specified, i.e. VT_I4, VT_IDISPATCH, etc. The methods that return VARIANTs are
1.337 + IAccessibleHyperlink::anchor, IAccessibleHyperlink::anchorTarget, IAccessibleValue::currentValue,
1.338 + IAccessibleValue::maximumValue, IAccessibleValue::minimumValue.
1.339 +
1.340 + @section _iaaction-iahyperlink IAccessibleHyperlink as subclass of IAccessibleAction
1.341 + In this version of the IDL, IAccessibleHyperlink is a subclass of IAccessibleAction.
1.342 + However, there is no practical need for that inheritance and in some cases, such as
1.343 + an image map of smart tags, it doesn't make sense because such an image map doesn't
1.344 + have actionable objects; it's the secondary smart tags that are actionable. As a
1.345 + result, implementations should not rely on the inheritance as it may be removed in
1.346 + a later version of the IDL.
1.347 +
1.348 + @section _trademark Trademark Attribution
1.349 + The names of actual companies and products mentioned herein may be the trademarks of
1.350 + their respective owners. In particular, Active Accessibility, Microsoft, MSDN, and Win32
1.351 + are trademarks of the Microsoft group of companies in the U.S.A. and/or other countries.
1.352 +
1.353 +**/
1.354 +
1.355 +import "objidl.idl";
1.356 +import "oaidl.idl";
1.357 +import "oleacc.idl";
1.358 +import "AccessibleRelation.idl";
1.359 +import "AccessibleStates.idl";
1.360 +import "IA2CommonTypes.idl";
1.361 +
1.362 +/** A structure defining the locale of an accessible object.
1.363 +
1.364 +IAccessible2::locale returns this struct.
1.365 +*/
1.366 +typedef struct IA2Locale {
1.367 + BSTR language; ///< ISO 639-1 Alpha-2 two character language code
1.368 + BSTR country; ///< ISO 3166-1 Alpha-2 two character country code
1.369 + BSTR variant; ///< Application specific variant of the locale
1.370 +} IA2Locale;
1.371 +
1.372 +/** @brief This interface exposes the primary set of information about an
1.373 + IAccessible2 enabled accessible object.
1.374 +
1.375 + This interface must always be provided for objects that support some
1.376 + portion of the collection of the %IAccessible2 interfaces.
1.377 +
1.378 + Please refer to @ref _changingInterfaces "Changing between Accessible Interfaces"
1.379 + for special considerations related to use of the MSAA IAccessible interface and
1.380 + the set of %IAccessible2 interfaces.
1.381 + */
1.382 +[object, uuid(E89F726E-C4F4-4c19-BB19-B647D7FA8478)]
1.383 +interface IAccessible2 : IAccessible
1.384 +{
1.385 +
1.386 + /** @brief Returns the number of accessible relations for this object.
1.387 + @param [out] nRelations
1.388 + @retval S_OK
1.389 + */
1.390 + [propget] HRESULT nRelations
1.391 + (
1.392 + [out, retval] long *nRelations
1.393 + );
1.394 +
1.395 + /** @brief Returns one accessible relation for this object.
1.396 + @param [in] relationIndex
1.397 + 0 based
1.398 + @param [out] relation
1.399 + @retval S_OK
1.400 + @retval E_INVALIDARG if bad [in] passed
1.401 + */
1.402 + [propget] HRESULT relation
1.403 + (
1.404 + [in] long relationIndex,
1.405 + [out, retval] IAccessibleRelation **relation
1.406 + );
1.407 +
1.408 + /** @brief Returns multiple accessible relations for this object.
1.409 + @param [in] maxRelations
1.410 + maximum size of the array allocated by the client
1.411 + @param [out] relations
1.412 + The array of accessible relation objects. Note that this array is to be
1.413 + allocated by the client and freed when no longer needed. Refer to @ref
1.414 + _arrayConsideration "Special Consideration when using Arrays" for more details.
1.415 + @param [out] nRelations
1.416 + actual number of relations in the returned array (not more than maxRelations)
1.417 + @retval S_OK
1.418 + @retval S_FALSE if there are no relations, nRelations is set to 0
1.419 + @note As a performant alternative, client code should consider using IAccessible2_2::relationTargetsOfType.
1.420 + */
1.421 + [propget] HRESULT relations
1.422 + (
1.423 + [in] long maxRelations,
1.424 + [out, size_is(maxRelations), length_is(*nRelations)]
1.425 + IAccessibleRelation **relations,
1.426 + [out, retval] long *nRelations
1.427 + );
1.428 +
1.429 + /** @brief Returns the role of an %IAccessible2 object.
1.430 + @param [out] role
1.431 + The role of an %IAccessible2 object.
1.432 + @retval S_OK
1.433 + @note
1.434 + @li For convenience MSAA roles are also passed through this method so the
1.435 + AT doesn't have to also fetch roles through MSAA's get_accRole.
1.436 + @li %IAccessible2 roles should not be passed through MSAA's get_accRole.
1.437 + @li For compatibility with non IAccessible2 enabled ATs, IAccessible2
1.438 + applications should also add support to get_accRole to return the closest
1.439 + MSAA role or ROLE_SYSTEM_CLIENT (the MSAA defined default role) if there
1.440 + is not a good match.
1.441 + @li This method is missing a [propget] prefix in the IDL. The result is the
1.442 + method is named role in generated C++ code instead of get_role.
1.443 + */
1.444 + HRESULT role
1.445 + (
1.446 + [out, retval] long *role
1.447 + );
1.448 +
1.449 + /** @brief Makes an object visible on the screen.
1.450 + @param [in] scrollType
1.451 + Defines where the object should be placed on the screen.
1.452 + @retval S_OK
1.453 + @retval E_INVALIDARG if bad [in] passed
1.454 + */
1.455 + HRESULT scrollTo
1.456 + (
1.457 + [in] enum IA2ScrollType scrollType
1.458 + );
1.459 +
1.460 + /** @brief Moves the top left of an object to a specified location.
1.461 +
1.462 + @param [in] coordinateType
1.463 + Specifies whether the coordinates are relative to the screen or the parent object.
1.464 + @param [in] x
1.465 + Defines the x coordinate.
1.466 + @param [in] y
1.467 + Defines the y coordinate.
1.468 + @retval S_OK
1.469 + @retval E_INVALIDARG if bad [in] passed
1.470 + */
1.471 + HRESULT scrollToPoint
1.472 + (
1.473 + [in] enum IA2CoordinateType coordinateType,
1.474 + [in] long x,
1.475 + [in] long y
1.476 + );
1.477 +
1.478 + /** @brief Returns grouping information.
1.479 +
1.480 + Used for tree items, list items, tab panel labels, radio buttons, etc.
1.481 + Also used for collections of non-text objects.
1.482 +
1.483 + @param [out] groupLevel
1.484 + 1 based, 0 indicates that this value is not applicable
1.485 + @param [out] similarItemsInGroup
1.486 + 1 based, 0 indicates that this value is not applicable
1.487 + @param [out] positionInGroup
1.488 + 1 based, 0 indicates that this value is not applicable. This is an index
1.489 + into the objects in the current group, not an index into all the objects
1.490 + at the same group level.
1.491 + @retval S_OK if at least one value is valid
1.492 + @retval S_FALSE if no values are valid, [out] values are 0s
1.493 + @note This method is meant to describe the nature of an object's containment
1.494 + structure. It's exposed by trees, tree grids, nested lists, nested menus,
1.495 + but not headings, which uses the level object attribute. It is also exposed
1.496 + by radio buttons (with groupLevel == 0).
1.497 + @note This is normally not implemented on a combo box to describe the nature
1.498 + of its contents. Normally an AT will get that information from its child list
1.499 + object. However, in some cases when non-edit combo boxes are not able to be structured
1.500 + such that the list is a child of the combo box, this method is implemented on
1.501 + the combo box itself. ATs can use this interface if a child list is not found.
1.502 + */
1.503 + [propget] HRESULT groupPosition
1.504 + (
1.505 + [out] long *groupLevel,
1.506 + [out] long *similarItemsInGroup,
1.507 + [out, retval] long *positionInGroup
1.508 + );
1.509 +
1.510 + /** @brief Returns the bit strip containing any IAccessible2 states.
1.511 +
1.512 + The IAccessible2 states are in addition to the MSAA states and are defined in
1.513 + the IA2States enum.
1.514 +
1.515 + @param [out] states
1.516 + @retval S_OK
1.517 + */
1.518 + [propget] HRESULT states
1.519 + (
1.520 + [out, retval] AccessibleStates *states
1.521 + );
1.522 +
1.523 + /** @brief Returns the extended role.
1.524 +
1.525 + An extended role is a role which is dynamically generated by the application.
1.526 + It is not predefined by the %IAccessible2 specification.
1.527 +
1.528 + @param [out] extendedRole
1.529 + @retval S_OK
1.530 + @retval S_FALSE if there is nothing to return, [out] value is NULL
1.531 + */
1.532 + [propget] HRESULT extendedRole
1.533 + (
1.534 + [out, retval] BSTR *extendedRole
1.535 + );
1.536 +
1.537 + /** @brief Returns the localized extended role.
1.538 + @param [out] localizedExtendedRole
1.539 + @retval S_OK
1.540 + @retval S_FALSE if there is nothing to return, [out] value is NULL
1.541 + */
1.542 + [propget] HRESULT localizedExtendedRole
1.543 + (
1.544 + [out, retval] BSTR *localizedExtendedRole
1.545 + );
1.546 +
1.547 + /** @brief Returns the number of extended states.
1.548 + @param [out] nExtendedStates
1.549 + @retval S_OK
1.550 + */
1.551 + [propget] HRESULT nExtendedStates
1.552 + (
1.553 + [out, retval] long *nExtendedStates
1.554 + );
1.555 +
1.556 + /** @brief Returns the extended states (array of strings).
1.557 +
1.558 + An extended state is a state which is dynamically generated by the application.
1.559 + It is not predefined by the %IAccessible2 specification.
1.560 +
1.561 + @param [in] maxExtendedStates
1.562 + This parameter is ignored. Refer to @ref _arrayConsideration
1.563 + "Special Consideration when using Arrays" for more details.
1.564 + @param [out] extendedStates
1.565 + This array is allocated by the server. The client must free it with CoTaskMemFree.
1.566 + @param [out] nExtendedStates
1.567 + The number of extended states returned; the size of the returned array.
1.568 + @retval S_OK
1.569 + @retval S_FALSE if there are no states, [out] values are NULL and 0 respectively
1.570 + */
1.571 + [propget] HRESULT extendedStates
1.572 + (
1.573 + [in] long maxExtendedStates,
1.574 + [out, size_is(,maxExtendedStates), length_is(,*nExtendedStates)] BSTR **extendedStates,
1.575 + [out, retval] long *nExtendedStates
1.576 + );
1.577 +
1.578 + /** @brief Returns the localized extended states (array of strings).
1.579 +
1.580 + @param [in] maxLocalizedExtendedStates
1.581 + This parameter is ignored. Refer to @ref _arrayConsideration
1.582 + "Special Consideration when using Arrays" for more details.
1.583 + @param [out] localizedExtendedStates
1.584 + This array is allocated by the server. The client must free it with CoTaskMemFree.
1.585 + @param [out] nLocalizedExtendedStates
1.586 + The number of localized extended states returned; the size of the returned array.
1.587 + @retval S_OK
1.588 + @retval S_FALSE if there are no states, [out] values are NULL and 0 respectively
1.589 + */
1.590 + [propget] HRESULT localizedExtendedStates
1.591 + (
1.592 + [in] long maxLocalizedExtendedStates,
1.593 + [out, size_is(,maxLocalizedExtendedStates), length_is(,*nLocalizedExtendedStates)] BSTR **localizedExtendedStates,
1.594 + [out, retval] long *nLocalizedExtendedStates
1.595 + );
1.596 +
1.597 + /** @brief Returns the unique ID.
1.598 +
1.599 + The uniqueID is an identifier for this object, is unique within the
1.600 + current window, and remains the same for the lifetime of the accessible
1.601 + object.
1.602 +
1.603 + The uniqueID is not related to:
1.604 + - the MSAA objectID which is used by the server to disambiguate between
1.605 + IAccessibles per HWND or
1.606 + - the MSAA childID which is used to disambiguate between children being
1.607 + managed by an IAccessible.
1.608 +
1.609 + This value is provided so the AT can have access to a unique runtime persistent
1.610 + identifier even when not handling an event for the object.
1.611 +
1.612 + An example of when this value is useful is if the AT wants to build a cache.
1.613 + The AT could cache the uniqueIDs in addition to other data being cached.
1.614 + When an event is fired the AT could map the uniqueID to its internal model.
1.615 + Thus, if there's a REORDER/SHOW/HIDE event the AT knows which part of the
1.616 + internal structure has been invalidated and can refetch just that part.
1.617 +
1.618 + This value can also be used by an AT to determine when the current control
1.619 + has changed. If the role is the same for two controls that are adjacent in
1.620 + the tab order, this can be used to detect the new control.
1.621 +
1.622 + Another use of this value by an AT is to identify when a grouping object has
1.623 + changed, e.g. when moving from a radio button in one group to a radio button in a
1.624 + different group.
1.625 +
1.626 + One means of implementing this would be to create a factory with a 32 bit number
1.627 + generator and a reuse pool. The number generator would emit numbers starting
1.628 + at 1. Each time an object's life cycle ended, its number would be saved into a
1.629 + reuse pool. The number generator would be used whenever the reuse pool was empty.
1.630 +
1.631 + Another way to create a unique ID is to generate it from a pointer value, e.g. an
1.632 + object's address. That would be unique because no two active objects can use the
1.633 + same allocated memory space.
1.634 +
1.635 + @param [out] uniqueID
1.636 + @retval S_OK
1.637 + */
1.638 + [propget] HRESULT uniqueID
1.639 + (
1.640 + [out, retval] long *uniqueID
1.641 + );
1.642 +
1.643 + /** @brief Returns the window handle for the parent window which contains this object.
1.644 +
1.645 + This is the same window handle which will be passed for any events that occur on the
1.646 + object, but is cached in the accessible object for use when it would be helpful to
1.647 + access the window handle in cases where an event isn't fired on this object.
1.648 +
1.649 + A use case is when a screen reader is grabbing an entire web page on a page load.
1.650 + Without the availability of windowHandle, the AT would have to get the window handle
1.651 + by using WindowFromAccessibleObject on each IAccessible, which is slow because it's
1.652 + implemented by oleacc.dll as a loop which crawls up the ancestor chain and looks for
1.653 + a ROLE_WINDOW object, mapping that back to a window handle.
1.654 +
1.655 + @param [out] windowHandle
1.656 + @retval S_OK
1.657 + */
1.658 + [propget] HRESULT windowHandle
1.659 + (
1.660 + [out, retval] HWND *windowHandle
1.661 + );
1.662 +
1.663 + /** @brief Returns the index of this object in its parent object.
1.664 + @param [out] indexInParent
1.665 + 0 based; -1 indicates there is no parent; the upper bound is the value
1.666 + returned by the parent's IAccessible::get_accChildCount.
1.667 + @retval S_OK
1.668 + @retval S_FALSE if no parent, [out] value is -1
1.669 + */
1.670 + [propget] HRESULT indexInParent
1.671 + (
1.672 + [out, retval] long *indexInParent
1.673 + );
1.674 +
1.675 + /** @brief Returns the IA2Locale of the accessible object.
1.676 + @param [out] locale
1.677 + @retval S_OK
1.678 + */
1.679 + [propget] HRESULT locale
1.680 + (
1.681 + [out, retval] IA2Locale *locale
1.682 + );
1.683 +
1.684 + /** @brief Returns the attributes specific to this object, such as a cell's formula.
1.685 + @param [out] attributes
1.686 + @retval S_OK
1.687 + @retval S_FALSE returned if there is nothing to return, [out] value is NULL
1.688 + */
1.689 + [propget] HRESULT attributes
1.690 + (
1.691 + [out, retval] BSTR *attributes
1.692 + );
1.693 +
1.694 +}
1.695 +
