gecko-dev/other-licenses/ia2/Accessible2.idl

351 строка
11 KiB
Plaintext

/*************************************************************************
*
* File Name (Accessible2.idl)
*
* IAccessible2 IDL Specification
*
* Copyright (c) IBM Corp. 2007
* 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., 59 Temple Place, Suite 330, 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\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 define roles.\n
::IA2ScrollType values define where to place an object or substring on the screen.\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).
@section _constants Constants
@ref grpRelations\n
@ref grpStates\n
@section _license License
@ref _licensePage "LGPL"
@page _licensePage License
IAccessible2 IDL Specification
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., 59 Temple Place, Suite 330, Boston, MA 02110-1301 USA
You may also refer to http://www.gnu.org/licenses/lgpl.html
**/
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.
typedef struct {
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.
IAccessible2 is a subclass of MSAA's IAccessible. This is a matter of
convenience, i.e. an IAccessible2 is an IAccessible so MSAA methods can be
easily accessed. None of MSAA's IAccessible methods are overridden or extended.
*/
[object, uuid(E89F726E-C4F4-4c19-BB19-B647D7FA8478)]
interface IAccessible2 : IAccessible
{
/** @brief Returns the number of accessible relations for this object.
@param [out] nRelations
*/
[propget] HRESULT nRelations
(
[out, retval] long *nRelations
);
/** @brief Returns one accessible relation for this object.
@param [in] relationIndex
0-based
@param [out] relation
*/
[propget] HRESULT relation
(
[in] long relationIndex,
[out, retval] IAccessibleRelation **relation
);
/** @brief Returns multiple accessible relations for this object.
@param [in] maxRelations
maximum number of relations to get
@param [out] relation
array of accessible relation objects
@param [out] nRelations
length of array (not more than maxRelations)
*/
[propget] HRESULT relations
(
[in] long maxRelations,
[out, size_is(maxRelations), length_is(*nRelations)]
IAccessibleRelation **relation,
[out, retval] long *nRelations
);
/** @brief Returns the role of an IAccessible2 object.
Note: 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.
@param [out] role
The role of an IAccessible2 object.
*/
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.
*/
HRESULT scrollTo
(
[in] enum IA2ScrollType scrollType
);
/** @brief Moves the top left of an object to a specified location.
Note: S_FALSE is returned if the object is already at the 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.
*/
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 collectons of non-text objects.
@param [out] groupLevel
0-based
@param [out] similarItemsInGroup
1-based
@param [out] positionInGroup
0-based
*/
[propget] HRESULT groupPosition
(
[out] long *groupLevel,
[out] long *similarItemsInGroup,
[out, retval] long *positionInGroup
);
/** @brief Returns the bit strip containing any IAccessible2 states.
@param [out] states
*/
[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
*/
[propget] HRESULT extendedRole
(
[out, retval] BSTR *extendedRole
);
/** @brief Returns the localized extended role.
@param [out] localizedExtendedRole
*/
[propget] HRESULT localizedExtendedRole
(
[out, retval] BSTR *localizedExtendedRole
);
/** @brief Returns the number of extended states.
@param [out] nExtendedStates
*/
[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
@param [out] extendedStates
@param [out] nExtendedStates
*/
[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
@param [out] localizedExtendedStates
@param [out] nLocalizedExtendedStates
*/
[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. This is the same value that is passed in the idChild parameter of
the WinEventProc callback function for any events that occur on the object,
and is typically a negative number. Using negative numbers prevents the ID
from conflicting with the use of positive numbers that might possibly be
used to indicate a direct child N of the window's root accessible object,
and thus the implementation of get_accChild() can differentiate between
requests for direct child N vs. a descendant lower in the hierarchy with a
given uniqueID. This is important because get_accChild() is used by
AccessibleObjectFromEvent() to retrieve the accessible object which fired
the event by starting from the window's root accessible object.
This value is provided so the AT can have access to it even when not
handling an event for the object.
An example of when this value is useful 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 that 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 and 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.
@param [out] uniqueID
*/
[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
*/
[propget] HRESULT windowHandle
(
[out, retval] HWND *windowHandle
);
/** @brief Returns the index of this object in its parent object.
@param [out] indexInParent
*/
[propget] HRESULT indexInParent
(
[out, retval] long *indexInParent
);
/** @brief Returns the IA2Locale of the accessible object.
@param [out] locale
*/
[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
*/
[propget] HRESULT attributes
(
[out, retval] BSTR *attributes
);
}