gecko/other-licenses/ia2/Accessible2.idl

619 lines
26 KiB
Plaintext
Raw Normal View History

/*************************************************************************
*
* 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&reg;.
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&reg; Active Accessibility&reg;) 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&reg; 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
);
}