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