michael@0: /************************************************************************* michael@0: * michael@0: * File Name (Accessible2.idl) michael@0: * michael@0: * IAccessible2 IDL Specification michael@0: * michael@0: * Copyright (c) 2007, 2013 Linux Foundation michael@0: * Copyright (c) 2006 IBM Corporation michael@0: * Copyright (c) 2000, 2006 Sun Microsystems, Inc. michael@0: * All rights reserved. michael@0: * michael@0: * michael@0: * Redistribution and use in source and binary forms, with or without michael@0: * modification, are permitted provided that the following conditions michael@0: * are met: michael@0: * michael@0: * 1. Redistributions of source code must retain the above copyright michael@0: * notice, this list of conditions and the following disclaimer. michael@0: * michael@0: * 2. Redistributions in binary form must reproduce the above michael@0: * copyright notice, this list of conditions and the following michael@0: * disclaimer in the documentation and/or other materials michael@0: * provided with the distribution. michael@0: * michael@0: * 3. Neither the name of the Linux Foundation nor the names of its michael@0: * contributors may be used to endorse or promote products michael@0: * derived from this software without specific prior written michael@0: * permission. michael@0: * michael@0: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND michael@0: * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, michael@0: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF michael@0: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE michael@0: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR michael@0: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, michael@0: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT michael@0: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; michael@0: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) michael@0: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN michael@0: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR michael@0: * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, michael@0: * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. michael@0: * michael@0: * This BSD License conforms to the Open Source Initiative "Simplified michael@0: * BSD License" as published at: michael@0: * http://www.opensource.org/licenses/bsd-license.php michael@0: * michael@0: * IAccessible2 is a trademark of the Linux Foundation. The IAccessible2 michael@0: * mark may be used in accordance with the Linux Foundation Trademark michael@0: * Policy to indicate compliance with the IAccessible2 specification. michael@0: * michael@0: ************************************************************************/ michael@0: michael@0: /** @mainpage michael@0: michael@0: @section _interfaces Interfaces michael@0: IAccessible2\n michael@0: IAccessible2_2\n michael@0: IAccessibleAction\n michael@0: IAccessibleApplication\n michael@0: IAccessibleComponent\n michael@0: IAccessibleDocument\n michael@0: IAccessibleEditableText\n michael@0: IAccessibleHypertext\n michael@0: IAccessibleHypertext2\n michael@0: IAccessibleHyperlink\n michael@0: IAccessibleImage\n michael@0: IAccessibleRelation\n michael@0: IAccessibleTable [Deprecated]\n michael@0: IAccessibleTable2\n michael@0: IAccessibleTableCell\n michael@0: IAccessibleText\n michael@0: IAccessibleText2\n michael@0: IAccessibleValue michael@0: michael@0: @section _structs Structs michael@0: IA2Locale\n michael@0: IA2TableModelChange\n michael@0: IA2TextSegment michael@0: michael@0: @section _enums Enums michael@0: ::IA2Actions values are predefined actions for use when implementing support for HTML5 media.\n michael@0: ::IA2CoordinateType values define the requested coordinate type (screen or parent window).\n michael@0: ::IA2EventID values identify events.\n michael@0: ::IA2Role values defines roles which are in addition to the existing MSAA roles.\n michael@0: ::IA2ScrollType values define where to place an object or substring on the screen.\n michael@0: ::IA2States values define states which are in addition to the existing MSAA states.\n michael@0: ::IA2TableModelChangeType values describe the kinds of changes made to a table (insert, delete, update).\n michael@0: ::IA2TextBoundaryType values define the requested text unit (character, word, sentence, line, paragraph).\n michael@0: ::IA2TextSpecialOffsets values define special offsets for use in the text interfaces. michael@0: michael@0: @section _constants Constants michael@0: @ref grpRelations michael@0: michael@0: @section _misc Miscellaneous michael@0: @ref _licensePage "BSD License"\n michael@0: @ref _generalInfo "General Information"\n michael@0: michael@0: @page _licensePage BSD License michael@0: %IAccessible2 IDL Specification michael@0: michael@0: Copyright (c) 2007, 2013 Linux Foundation\n michael@0: Copyright (c) 2006 IBM Corporation\n michael@0: Copyright (c) 2000, 2006 Sun Microsystems, Inc.\n michael@0: All rights reserved. michael@0: michael@0: Redistribution and use in source and binary forms, with or without michael@0: modification, are permitted provided that the following conditions michael@0: are met: michael@0: michael@0: 1. Redistributions of source code must retain the above copyright michael@0: notice, this list of conditions and the following disclaimer. michael@0: michael@0: 2. Redistributions in binary form must reproduce the above michael@0: copyright notice, this list of conditions and the following michael@0: disclaimer in the documentation and/or other materials michael@0: provided with the distribution. michael@0: michael@0: 3. Neither the name of the Linux Foundation nor the names of its michael@0: contributors may be used to endorse or promote products michael@0: derived from this software without specific prior written michael@0: permission. michael@0: michael@0: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND michael@0: CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, michael@0: INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF michael@0: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE michael@0: DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR michael@0: CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, michael@0: SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT michael@0: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; michael@0: LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) michael@0: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN michael@0: CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR michael@0: OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, michael@0: EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. michael@0: michael@0: This BSD License conforms to the Open Source Initiative "Simplified michael@0: BSD License" as published at: michael@0: http://www.opensource.org/licenses/bsd-license.php michael@0: michael@0: %IAccessible2 is a trademark of the Linux Foundation. The %IAccessible2 michael@0: mark may be used in accordance with the michael@0: michael@0: Linux Foundation Trademark Policy to indicate compliance with the %IAccessible2 specification. michael@0: michael@0: @page _generalInfo General Information michael@0: The following information is applicable to two or more interfaces. michael@0: michael@0: @ref _errors\n michael@0: @ref _memory\n michael@0:   @ref _arrayConsideration\n michael@0: @ref _indexes\n michael@0: @ref _enums\n michael@0: @ref _specialOffsets\n michael@0: @ref _dicoveringInterfaces\n michael@0: @ref _changingInterfaces\n michael@0: @ref _applicationInfo\n michael@0: @ref _childIDs\n michael@0: @ref _variants\n michael@0: @ref _iaaction-iahyperlink\n michael@0: @ref _trademark michael@0: michael@0: @section _errors Error Handling michael@0: HRESULT values are defined by the Microsoft® Win32® API. For more information, refer to michael@0: michael@0: Interpreting HRESULT Values in MSDN®. michael@0: michael@0: Note that the S_FALSE return value is considered a non-error value and the michael@0: SUCCEEDED macro will return TRUE. S_FALSE is used when there is no failure michael@0: but there was nothing valid to return, e.g. in IAccessible2::attributes when michael@0: there are no attributes. When S_FALSE is returned [out] pointer types should michael@0: be NULL and [out] longs should generally be 0, but sometimes -1 is used such michael@0: as IAccessible2::indexInParent, IAccessibleText::caretOffset, and michael@0: IAccessibleHypertext::hyperlinkIndex. michael@0: michael@0: Note that for BSTR [out] variables common COM practice is that the server does michael@0: the SysAllocString and the client does the SysFreeString. Also note that when michael@0: NULL is returned there is no need for the client to call SysFreeString. Please michael@0: refer to the documentation for each method for more details regarding error handling. michael@0: michael@0: @section _memory Memory Management michael@0: The following memory management issues should be considered: michael@0: @li Although [out] BSTR variables are declared by the client, their space is michael@0: allocated by the server. They need to be freed with SysFreeString by the michael@0: client at end of life; the same is true when BSTRs are used in structs or michael@0: arrays which are passed to the server. michael@0: @li If there is no valid [out] BSTR to return, the server should return S_FALSE and michael@0: assign NULL to the output, e.g. *theOutBSTR = NULL;. michael@0: @li COM interfaces need to be referenced with AddRef when used and dereferenced michael@0: with Release at end of life. michael@0: @li Single [out] longs, HWNDs, booleans, and structs are declared by the caller michael@0: and passed by reference. The marshaller does all the memory management. michael@0: michael@0: The following articles may be helpful for understanding memory management issues: michael@0: @li An article by Don Box in a michael@0: Q & A section michael@0: of the November 1996 edition of the Microsoft Systems Journal. michael@0: @li A posting to a CodeGuru forum, michael@0: Windows SDK michael@0: String: What are the rules for BSTR allocation and deallocation? michael@0: michael@0: @subsection _arrayConsideration Special Consideration when using Arrays michael@0: There are several methods which return arrays. In the case of IAccessible2::relations michael@0: and IAccessibleRelation::targets the client must allocate and free the arrays. michael@0: michael@0: For the remaining methods which return arrays, the server must allocate the array michael@0: and the client must free the array when no longer needed. These methods are michael@0: IAccessible2::extendedStates, IAccessible2::localizedExtendedStates, michael@0: IAccessible2_2::relationTargetsOfType, IAccessibleAction::keyBinding, michael@0: IAccessibleHypertext2::hyperlinks, IAccessibleTable::selectedChildren, michael@0: IAccessibleTable::selectedColumns, IAccessibleTable::selectedRows, michael@0: IAccessibleTable2::selectedCells, IAccessibleTable2::selectedColumns, michael@0: IAccessibleTable2::selectedRows, IAccessibleTableCell::columnHeaderCells, michael@0: and IAccessibleTableCell::rowHeaderCells. michael@0: For those methods, the server must allocate both the top level array and any storage michael@0: associated with it, e.g. for BSTRs. The server must allocate the arrays with michael@0: CoTaskMemAlloc and any BSTRs with SysAllocString. The client must use CoTaskMemFree michael@0: to free the array and any BSTRs must be freed with SysFreeString. michael@0: michael@0: Also, the IDL for IAccessible2::extendedStates, IAccessible2::localizedExtendedStates, michael@0: IAccessibleAction::keyBinding, IAccessibleTable::selectedChildren, michael@0: IAccessibleTable::selectedColumns, and IAccessibleTable::selectedRows includes an michael@0: extraneous [in] parameter for the caller to specify the max size of the array. michael@0: This parameter will be ignored by the COM server. michael@0: michael@0: @section _indexes Zero and One Based Indexes michael@0: Unless otherwise specified all offsets and indexes are 0 based. michael@0: michael@0: @section _enums Enums michael@0: Note that enums start at 0. michael@0: michael@0: @section _specialOffsets Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods michael@0: IAccessibleText and IAccessibleEditableText can use one or more of the following michael@0: special offset values. They are defined in the ::IA2TextSpecialOffsets enum. michael@0: @li Using ::IA2_TEXT_OFFSET_LENGTH (-1) as an offset in any of the IAccessibleText or michael@0: IAccessibleEditableText methods is the same as specifying the length of the string. michael@0: @li Using ::IA2_TEXT_OFFSET_CARET (-2) as an offset for IAccessibleText::textBeforeOffset, michael@0: IAccessibleText::textAtOffset, and IAccessibleText::textAfterOffset indicates that the michael@0: text related to the physical location of the caret should be used. This is needed for michael@0: applications that consider the character offset of the end of one line (as reached by michael@0: pressing the End key) the same as the offset of the first character on the next line. michael@0: Since the same offset is associated with two different lines a special means is needed michael@0: to fetch text from the line where the caret is physically located. michael@0: michael@0: @section _dicoveringInterfaces Discovery of Interfaces michael@0: In general AT (Assistive Technology) should try IAccessible2 interfaces, followed by using michael@0: the MSAA (Microsoft® Active Accessibility®) interfaces. (In cases where the an application michael@0: is known to have custom interfaces which provide information not supplied by IAccessible2 michael@0: or MSAA, then those custom interfaces can be used.) The AT can then, by default, support michael@0: unknown IAccessible2/MSAA applications, without the application developers having to request michael@0: AT vendors for support on an individual application by application basis. michael@0: michael@0: When you have a reference to an IAccessible and require a reference to an IAccessible2 use michael@0: QueryService as follows: michael@0: @code michael@0: // pAcc is a reference to the accessible object's IAccessible interface. michael@0: IServiceProvider *pService = NULL; michael@0: hr = pAcc->QueryInterface(IID_IServiceProvider, (void **)&pService); michael@0: if(SUCCEEDED(hr)) { michael@0: IAccessible2 *pIA2 = NULL; michael@0: hr = pService->QueryService(IID_IAccessible, IID_IAccessible2, (void**)&pIA2); michael@0: if (SUCCEEDED(hr) && pIA2) { michael@0: // The control supports IAccessible2. michael@0: // pIA2 is the reference to the accessible object's IAccessible2 interface. michael@0: } michael@0: } michael@0: @endcode michael@0: michael@0: @section _changingInterfaces Changing between Accessible Interfaces michael@0: Note that developers must always implement MSAA's IAccessible and, if needed, some michael@0: of the interfaces in the set of IAccessible2 interfaces. Although the IAccessible2 michael@0: IDL is coded such that IAccessible2 is a subclass of MSAA's IAccessible, none of michael@0: MSAA's IAccessible methods are redefined by IAccessible2. michael@0: michael@0: QueryService must be used to switch from a reference to an MSAA IAccessible interface michael@0: to another interface. This has been michael@0: michael@0: documented and the pertinent facts have been extracted below: michael@0: michael@0: @par michael@0: Why use QueryService instead of just using QueryInterface to get IAccessibleEx michael@0: directly? The reason is that since MSAA 2.0, clients don't talk to a server's michael@0: IAccessible interface directly; instead they talk to an intermediate MSAA-provided michael@0: wrapper that calls through to the original IAccessible. This wrapper provides services michael@0: such as implementing IDispatch, supplying information from MSAA 2.0's Dynamic Annotation michael@0: service, and scaling locations when running on Windows Vista with DPI scaling enabled. michael@0: QueryService is the supported way to expose additional interfaces from an existing michael@0: IAccessible and was originally used by MSHTML to expose IHTMLElement objects corresponding michael@0: to IAccessibles. QueryService is often more convenient for servers to implement than michael@0: QueryInterface because it does not have the same requirements for preserving object michael@0: identity or symmetry/transitivity as QueryInterface, so QueryService allows servers to michael@0: easily implement the interface on the same object or a separate object. The latter is michael@0: often hard to do with QueryInterface unless the original object supports aggregation. michael@0: michael@0: Two related references in MSDN® are: michael@0: @li michael@0: "Using QueryService to expose a native object model interface for an IAccessible object" michael@0: @li michael@0: "Accessing the Internet Explorer Object Associated with an Accessible Object" michael@0: michael@0: Based on this information from Microsoft, QueryService must be used to switch back and forth michael@0: between a reference to an MSAA IAccessible interface and any of the IAccessible2 interfaces. michael@0: michael@0: Regarding switching between any of the IAccessible2 interfaces, applications implementing michael@0: IAccessible2 should implement the IAccessible2 interfaces on a single object since ATs michael@0: will be using QueryInterface to switch between the IAccessilbe2 interfaces. Implementing michael@0: the IAccessible2 interfaces on separate objects would require the use of QueryService. michael@0: There is one exception, IAccessibleApplication can be implemented on a separate object so michael@0: its common code doesn't have to be included in each accessible object. ATs should use michael@0: QueryService to access IAccessibleApplication. michael@0: michael@0: @section _applicationInfo Access to Information about the Application michael@0: Servers implementing IAccessible2 should provide access to the IAccessibleApplication michael@0: interface via QueryService from any object so that ATs can easily determine specific michael@0: information about the application such as its name or version. michael@0: michael@0: @section _childIDs Child IDs michael@0: The IAccessible2 interfaces do not support child IDs, i.e. simple child elements. michael@0: Full accessible objects must be created for each object that supports IAccessible2. michael@0: Therefore MSAA's get_accChild should never return a child ID (other than CHILDID_SELF) michael@0: for an object that implements any of the IAccessible2 interfaces. michael@0: michael@0: Microsoft's UI Automation specification has the same limitation and this was resolved michael@0: in the UI Automation Express specification by adding IAccessibleEx::GetObjectForChild michael@0: and IAccessibleEx::GetIAccessiblePair. These methods allow mapping back and forth michael@0: between an IAccessibleEx and an {IAccessible, Child ID} pair. A future version of michael@0: IAccessible2 may include similar methods to map back and forth between an IAccessible2 michael@0: and an {IAccessible, Child ID} pair. michael@0: michael@0: @section _variants VARIANTs michael@0: Some methods return a VARIANT. Implementers need to make sure that the return type is michael@0: specified, i.e. VT_I4, VT_IDISPATCH, etc. The methods that return VARIANTs are michael@0: IAccessibleHyperlink::anchor, IAccessibleHyperlink::anchorTarget, IAccessibleValue::currentValue, michael@0: IAccessibleValue::maximumValue, IAccessibleValue::minimumValue. michael@0: michael@0: @section _iaaction-iahyperlink IAccessibleHyperlink as subclass of IAccessibleAction michael@0: In this version of the IDL, IAccessibleHyperlink is a subclass of IAccessibleAction. michael@0: However, there is no practical need for that inheritance and in some cases, such as michael@0: an image map of smart tags, it doesn't make sense because such an image map doesn't michael@0: have actionable objects; it's the secondary smart tags that are actionable. As a michael@0: result, implementations should not rely on the inheritance as it may be removed in michael@0: a later version of the IDL. michael@0: michael@0: @section _trademark Trademark Attribution michael@0: The names of actual companies and products mentioned herein may be the trademarks of michael@0: their respective owners. In particular, Active Accessibility, Microsoft, MSDN, and Win32 michael@0: are trademarks of the Microsoft group of companies in the U.S.A. and/or other countries. michael@0: michael@0: **/ michael@0: michael@0: import "objidl.idl"; michael@0: import "oaidl.idl"; michael@0: import "oleacc.idl"; michael@0: import "AccessibleRelation.idl"; michael@0: import "AccessibleStates.idl"; michael@0: import "IA2CommonTypes.idl"; michael@0: michael@0: /** A structure defining the locale of an accessible object. michael@0: michael@0: IAccessible2::locale returns this struct. michael@0: */ michael@0: typedef struct IA2Locale { michael@0: BSTR language; ///< ISO 639-1 Alpha-2 two character language code michael@0: BSTR country; ///< ISO 3166-1 Alpha-2 two character country code michael@0: BSTR variant; ///< Application specific variant of the locale michael@0: } IA2Locale; michael@0: michael@0: /** @brief This interface exposes the primary set of information about an michael@0: IAccessible2 enabled accessible object. michael@0: michael@0: This interface must always be provided for objects that support some michael@0: portion of the collection of the %IAccessible2 interfaces. michael@0: michael@0: Please refer to @ref _changingInterfaces "Changing between Accessible Interfaces" michael@0: for special considerations related to use of the MSAA IAccessible interface and michael@0: the set of %IAccessible2 interfaces. michael@0: */ michael@0: [object, uuid(E89F726E-C4F4-4c19-BB19-B647D7FA8478)] michael@0: interface IAccessible2 : IAccessible michael@0: { michael@0: michael@0: /** @brief Returns the number of accessible relations for this object. michael@0: @param [out] nRelations michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT nRelations michael@0: ( michael@0: [out, retval] long *nRelations michael@0: ); michael@0: michael@0: /** @brief Returns one accessible relation for this object. michael@0: @param [in] relationIndex michael@0: 0 based michael@0: @param [out] relation michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT relation michael@0: ( michael@0: [in] long relationIndex, michael@0: [out, retval] IAccessibleRelation **relation michael@0: ); michael@0: michael@0: /** @brief Returns multiple accessible relations for this object. michael@0: @param [in] maxRelations michael@0: maximum size of the array allocated by the client michael@0: @param [out] relations michael@0: The array of accessible relation objects. Note that this array is to be michael@0: allocated by the client and freed when no longer needed. Refer to @ref michael@0: _arrayConsideration "Special Consideration when using Arrays" for more details. michael@0: @param [out] nRelations michael@0: actual number of relations in the returned array (not more than maxRelations) michael@0: @retval S_OK michael@0: @retval S_FALSE if there are no relations, nRelations is set to 0 michael@0: @note As a performant alternative, client code should consider using IAccessible2_2::relationTargetsOfType. michael@0: */ michael@0: [propget] HRESULT relations michael@0: ( michael@0: [in] long maxRelations, michael@0: [out, size_is(maxRelations), length_is(*nRelations)] michael@0: IAccessibleRelation **relations, michael@0: [out, retval] long *nRelations michael@0: ); michael@0: michael@0: /** @brief Returns the role of an %IAccessible2 object. michael@0: @param [out] role michael@0: The role of an %IAccessible2 object. michael@0: @retval S_OK michael@0: @note michael@0: @li For convenience MSAA roles are also passed through this method so the michael@0: AT doesn't have to also fetch roles through MSAA's get_accRole. michael@0: @li %IAccessible2 roles should not be passed through MSAA's get_accRole. michael@0: @li For compatibility with non IAccessible2 enabled ATs, IAccessible2 michael@0: applications should also add support to get_accRole to return the closest michael@0: MSAA role or ROLE_SYSTEM_CLIENT (the MSAA defined default role) if there michael@0: is not a good match. michael@0: @li This method is missing a [propget] prefix in the IDL. The result is the michael@0: method is named role in generated C++ code instead of get_role. michael@0: */ michael@0: HRESULT role michael@0: ( michael@0: [out, retval] long *role michael@0: ); michael@0: michael@0: /** @brief Makes an object visible on the screen. michael@0: @param [in] scrollType michael@0: Defines where the object should be placed on the screen. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: HRESULT scrollTo michael@0: ( michael@0: [in] enum IA2ScrollType scrollType michael@0: ); michael@0: michael@0: /** @brief Moves the top left of an object to a specified location. michael@0: michael@0: @param [in] coordinateType michael@0: Specifies whether the coordinates are relative to the screen or the parent object. michael@0: @param [in] x michael@0: Defines the x coordinate. michael@0: @param [in] y michael@0: Defines the y coordinate. michael@0: @retval S_OK michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: HRESULT scrollToPoint michael@0: ( michael@0: [in] enum IA2CoordinateType coordinateType, michael@0: [in] long x, michael@0: [in] long y michael@0: ); michael@0: michael@0: /** @brief Returns grouping information. michael@0: michael@0: Used for tree items, list items, tab panel labels, radio buttons, etc. michael@0: Also used for collections of non-text objects. michael@0: michael@0: @param [out] groupLevel michael@0: 1 based, 0 indicates that this value is not applicable michael@0: @param [out] similarItemsInGroup michael@0: 1 based, 0 indicates that this value is not applicable michael@0: @param [out] positionInGroup michael@0: 1 based, 0 indicates that this value is not applicable. This is an index michael@0: into the objects in the current group, not an index into all the objects michael@0: at the same group level. michael@0: @retval S_OK if at least one value is valid michael@0: @retval S_FALSE if no values are valid, [out] values are 0s michael@0: @note This method is meant to describe the nature of an object's containment michael@0: structure. It's exposed by trees, tree grids, nested lists, nested menus, michael@0: but not headings, which uses the level object attribute. It is also exposed michael@0: by radio buttons (with groupLevel == 0). michael@0: @note This is normally not implemented on a combo box to describe the nature michael@0: of its contents. Normally an AT will get that information from its child list michael@0: object. However, in some cases when non-edit combo boxes are not able to be structured michael@0: such that the list is a child of the combo box, this method is implemented on michael@0: the combo box itself. ATs can use this interface if a child list is not found. michael@0: */ michael@0: [propget] HRESULT groupPosition michael@0: ( michael@0: [out] long *groupLevel, michael@0: [out] long *similarItemsInGroup, michael@0: [out, retval] long *positionInGroup michael@0: ); michael@0: michael@0: /** @brief Returns the bit strip containing any IAccessible2 states. michael@0: michael@0: The IAccessible2 states are in addition to the MSAA states and are defined in michael@0: the IA2States enum. michael@0: michael@0: @param [out] states michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT states michael@0: ( michael@0: [out, retval] AccessibleStates *states michael@0: ); michael@0: michael@0: /** @brief Returns the extended role. michael@0: michael@0: An extended role is a role which is dynamically generated by the application. michael@0: It is not predefined by the %IAccessible2 specification. michael@0: michael@0: @param [out] extendedRole michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: */ michael@0: [propget] HRESULT extendedRole michael@0: ( michael@0: [out, retval] BSTR *extendedRole michael@0: ); michael@0: michael@0: /** @brief Returns the localized extended role. michael@0: @param [out] localizedExtendedRole michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: */ michael@0: [propget] HRESULT localizedExtendedRole michael@0: ( michael@0: [out, retval] BSTR *localizedExtendedRole michael@0: ); michael@0: michael@0: /** @brief Returns the number of extended states. michael@0: @param [out] nExtendedStates michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT nExtendedStates michael@0: ( michael@0: [out, retval] long *nExtendedStates michael@0: ); michael@0: michael@0: /** @brief Returns the extended states (array of strings). michael@0: michael@0: An extended state is a state which is dynamically generated by the application. michael@0: It is not predefined by the %IAccessible2 specification. michael@0: michael@0: @param [in] maxExtendedStates michael@0: This parameter is ignored. Refer to @ref _arrayConsideration michael@0: "Special Consideration when using Arrays" for more details. michael@0: @param [out] extendedStates michael@0: This array is allocated by the server. The client must free it with CoTaskMemFree. michael@0: @param [out] nExtendedStates michael@0: The number of extended states returned; the size of the returned array. michael@0: @retval S_OK michael@0: @retval S_FALSE if there are no states, [out] values are NULL and 0 respectively michael@0: */ michael@0: [propget] HRESULT extendedStates michael@0: ( michael@0: [in] long maxExtendedStates, michael@0: [out, size_is(,maxExtendedStates), length_is(,*nExtendedStates)] BSTR **extendedStates, michael@0: [out, retval] long *nExtendedStates michael@0: ); michael@0: michael@0: /** @brief Returns the localized extended states (array of strings). michael@0: michael@0: @param [in] maxLocalizedExtendedStates michael@0: This parameter is ignored. Refer to @ref _arrayConsideration michael@0: "Special Consideration when using Arrays" for more details. michael@0: @param [out] localizedExtendedStates michael@0: This array is allocated by the server. The client must free it with CoTaskMemFree. michael@0: @param [out] nLocalizedExtendedStates michael@0: The number of localized extended states returned; the size of the returned array. michael@0: @retval S_OK michael@0: @retval S_FALSE if there are no states, [out] values are NULL and 0 respectively michael@0: */ michael@0: [propget] HRESULT localizedExtendedStates michael@0: ( michael@0: [in] long maxLocalizedExtendedStates, michael@0: [out, size_is(,maxLocalizedExtendedStates), length_is(,*nLocalizedExtendedStates)] BSTR **localizedExtendedStates, michael@0: [out, retval] long *nLocalizedExtendedStates michael@0: ); michael@0: michael@0: /** @brief Returns the unique ID. michael@0: michael@0: The uniqueID is an identifier for this object, is unique within the michael@0: current window, and remains the same for the lifetime of the accessible michael@0: object. michael@0: michael@0: The uniqueID is not related to: michael@0: - the MSAA objectID which is used by the server to disambiguate between michael@0: IAccessibles per HWND or michael@0: - the MSAA childID which is used to disambiguate between children being michael@0: managed by an IAccessible. michael@0: michael@0: This value is provided so the AT can have access to a unique runtime persistent michael@0: identifier even when not handling an event for the object. michael@0: michael@0: An example of when this value is useful is if the AT wants to build a cache. michael@0: The AT could cache the uniqueIDs in addition to other data being cached. michael@0: When an event is fired the AT could map the uniqueID to its internal model. michael@0: Thus, if there's a REORDER/SHOW/HIDE event the AT knows which part of the michael@0: internal structure has been invalidated and can refetch just that part. michael@0: michael@0: This value can also be used by an AT to determine when the current control michael@0: has changed. If the role is the same for two controls that are adjacent in michael@0: the tab order, this can be used to detect the new control. michael@0: michael@0: Another use of this value by an AT is to identify when a grouping object has michael@0: changed, e.g. when moving from a radio button in one group to a radio button in a michael@0: different group. michael@0: michael@0: One means of implementing this would be to create a factory with a 32 bit number michael@0: generator and a reuse pool. The number generator would emit numbers starting michael@0: at 1. Each time an object's life cycle ended, its number would be saved into a michael@0: reuse pool. The number generator would be used whenever the reuse pool was empty. michael@0: michael@0: Another way to create a unique ID is to generate it from a pointer value, e.g. an michael@0: object's address. That would be unique because no two active objects can use the michael@0: same allocated memory space. michael@0: michael@0: @param [out] uniqueID michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT uniqueID michael@0: ( michael@0: [out, retval] long *uniqueID michael@0: ); michael@0: michael@0: /** @brief Returns the window handle for the parent window which contains this object. michael@0: michael@0: This is the same window handle which will be passed for any events that occur on the michael@0: object, but is cached in the accessible object for use when it would be helpful to michael@0: access the window handle in cases where an event isn't fired on this object. michael@0: michael@0: A use case is when a screen reader is grabbing an entire web page on a page load. michael@0: Without the availability of windowHandle, the AT would have to get the window handle michael@0: by using WindowFromAccessibleObject on each IAccessible, which is slow because it's michael@0: implemented by oleacc.dll as a loop which crawls up the ancestor chain and looks for michael@0: a ROLE_WINDOW object, mapping that back to a window handle. michael@0: michael@0: @param [out] windowHandle michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT windowHandle michael@0: ( michael@0: [out, retval] HWND *windowHandle michael@0: ); michael@0: michael@0: /** @brief Returns the index of this object in its parent object. michael@0: @param [out] indexInParent michael@0: 0 based; -1 indicates there is no parent; the upper bound is the value michael@0: returned by the parent's IAccessible::get_accChildCount. michael@0: @retval S_OK michael@0: @retval S_FALSE if no parent, [out] value is -1 michael@0: */ michael@0: [propget] HRESULT indexInParent michael@0: ( michael@0: [out, retval] long *indexInParent michael@0: ); michael@0: michael@0: /** @brief Returns the IA2Locale of the accessible object. michael@0: @param [out] locale michael@0: @retval S_OK michael@0: */ michael@0: [propget] HRESULT locale michael@0: ( michael@0: [out, retval] IA2Locale *locale michael@0: ); michael@0: michael@0: /** @brief Returns the attributes specific to this object, such as a cell's formula. michael@0: @param [out] attributes michael@0: @retval S_OK michael@0: @retval S_FALSE returned if there is nothing to return, [out] value is NULL michael@0: */ michael@0: [propget] HRESULT attributes michael@0: ( michael@0: [out, retval] BSTR *attributes michael@0: ); michael@0: michael@0: } michael@0: