mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-08 20:47:44 +00:00
7f9931aed9
--HG-- rename : accessible/src/atk/nsXULTreeAccessibleWrap.h => accessible/src/atk/nsXULTreeGridAccessibleWrap.h rename : accessible/src/mac/nsXULTreeAccessibleWrap.h => accessible/src/mac/nsXULTreeGridAccessibleWrap.h rename : accessible/src/msaa/nsXULTreeAccessibleWrap.cpp => accessible/src/msaa/nsXULTreeGridAccessibleWrap.cpp rename : accessible/src/msaa/nsXULTreeAccessibleWrap.h => accessible/src/msaa/nsXULTreeGridAccessibleWrap.h rename : accessible/src/other/nsXULTreeAccessibleWrap.h => accessible/src/other/nsXULTreeGridAccessibleWrap.h rename : accessible/src/xul/nsXULSelectAccessible.cpp => accessible/src/xul/nsXULListboxAccessible.cpp rename : accessible/src/xul/nsXULSelectAccessible.h => accessible/src/xul/nsXULListboxAccessible.h rename : accessible/tests/mochitest/test_relations_table.html => accessible/tests/mochitest/test_table_headers.html rename : accessible/tests/mochitest/test_nsIAccessibleTable_listboxes.xul => accessible/tests/mochitest/test_table_sels_listbox.xul rename : accessible/tests/mochitest/test_elm_table.html => accessible/tests/mochitest/test_table_struct.html
619 lines
26 KiB
Plaintext
619 lines
26 KiB
Plaintext
/*************************************************************************
|
|
*
|
|
* File Name (Accessible2.idl)
|
|
*
|
|
* IAccessible2 IDL Specification
|
|
*
|
|
* Copyright (c) Linux Foundation 2007, 2009
|
|
* Copyright (c) IBM Corp. 2006
|
|
* Copyright (c) Sun Microsystems, Inc. 2000, 2006
|
|
*
|
|
* This library is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
* License version 2.1, as published by the Free Software Foundation; either
|
|
* version 2.1 of the License, or (at your option) any later version.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
* License along with this library; if not, write to the Free Software
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
*
|
|
************************************************************************/
|
|
|
|
/** @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 "LGPL License"\n
|
|
@ref _generalInfo "General Information"\n
|
|
|
|
@page _licensePage LGPL License
|
|
IAccessible2 IDL Specification
|
|
|
|
Copyright (c) Linux Foundation 2007, 2008\n
|
|
Copyright (c) IBM Corp. 2006\n
|
|
Copyright (c) Sun Microsystems, Inc. 2000, 2006
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Lesser General Public
|
|
License version 2.1, as published by the Free Software Foundation; either
|
|
version 2.1 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this library; if not, write to the Free Software
|
|
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
|
|
You may also refer to http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
|
|
|
|
@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. It is considered a best practice
|
|
for the client to allocate and free the arrays. This can be done for
|
|
IAccessible2::relations and IAccessibleRelation::targets. However, due to the
|
|
coding of the IDL 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, IAccessibleTable::selectedChildren,
|
|
IAccessibleTable::selectedColumns, and IAccessibleTable::selectedRows. For those
|
|
methods, the server must allocate both the top level array and any storage
|
|
associated with it, e.g. for BSTRs. The client must use CoTaskMemFree to free
|
|
the array and any BSTRs must be freed with SysFreeString.
|
|
|
|
Also, the IDL for those 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 currently coded such that IAccessible2 is a subclass of MSAA's IAccessible,
|
|
none of MSAA's IAccessible methods are overridden or extended. In order to allow
|
|
future removal of the inheritance, Assistive Technologies (ATs) should not rely on
|
|
that inheritance.
|
|
|
|
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;
|
|
|
|
/** 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, [out] value is NULL
|
|
*/
|
|
[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
|
|
@note This method is meant to describe the nature of an object's containment
|
|
structure. 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 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
|
|
resuse pool. The number generator would be used whenever the reuse pool was empty.
|
|
|
|
@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
|
|
);
|
|
|
|
}
|