IAccessibleAction Interface Reference

This interface gives access to actions that can be executed for accessible objects. More...

import "AccessibleAction.idl";

Inheritance diagram for IAccessibleAction:

IAccessibleHyperlink

List of all members.


Public Member Functions

HRESULT nActions ([out, retval] long *nActions)
 Returns the number of accessible actions available in this object.
HRESULT doAction ([in] long actionIndex)
 Performs the specified Action on the object.
HRESULT description ([in] long actionIndex,[out, retval] BSTR *description)
 Returns a description of the specified action of the object.
HRESULT keyBinding ([in] long actionIndex,[in] long nMaxBindings,[out, size_is(, nMaxBindings), length_is(,*nBindings)] BSTR **keyBindings,[out, retval] long *nBindings)
 Returns an array of BSTRs describing one or more key bindings, if there are any, associated with the specified action.
HRESULT name ([in] long actionIndex,[out, retval] BSTR *name)
 Returns the non-localized name of specified action.
HRESULT localizedName ([in] long actionIndex,[out, retval] BSTR *localizedName)
 Returns the localized name of specified action.

Detailed Description

This interface gives access to actions that can be executed for accessible objects.

Every accessible object that can be manipulated via the native GUI beyond the methods available either in the MSAA IAccessible interface or in the set of IAccessible2 interfaces (other than this IAccessibleAction interface) should support the IAccessibleAction interface in order to provide Assistive Technology access to all the actions that can be performed by the object. Each action can be performed or queried for a name, description or associated key bindings. Actions are needed more for ATs that assist the mobility impaired, such as on-screen keyboards and voice command software. By providing actions directly, the AT can present them to the user without the user having to perform the extra steps to navigate a context menu.

The first action should be equivalent to the MSAA default action. If there is only one action, IAccessibleAction should also be implemented.


Member Function Documentation

HRESULT IAccessibleAction::description ( [in] long  actionIndex,
[out, retval] BSTR *  description 
) [get]

Returns a description of the specified action of the object.

Parameters:
[in] actionIndex 0 based index specifying which action's description to return. If it lies outside the valid range an empty string is returned.
[out] description The returned value is a localized string of the specified action.
Return values:
S_OK 
S_FALSE if there is nothing to return, [out] value is NULL
E_INVALIDARG if bad [in] passed

HRESULT IAccessibleAction::doAction ( [in] long  actionIndex  ) 

Performs the specified Action on the object.

Parameters:
[in] actionIndex 0 based index specifying the action to perform. If it lies outside the valid range no action is performed.
Return values:
S_OK 
S_FALSE if action could not be performed
E_INVALIDARG if bad [in] passed

HRESULT IAccessibleAction::keyBinding ( [in] long  actionIndex,
[in] long  nMaxBindings,
[out, size_is(, nMaxBindings), length_is(,*nBindings)] BSTR **  keyBindings,
[out, retval] long *  nBindings 
) [get]

Returns an array of BSTRs describing one or more key bindings, if there are any, associated with the specified action.

The returned strings are the localized human readable key sequences to be used to activate each action, e.g. "Ctrl+Shift+D". Since these key sequences are to be used when the object has focus, they are like mnemonics (access keys), and not like shortcut (accelerator) keys.

There is no need to implement this method for single action controls since that would be redundant with the standard MSAA programming practice of getting the mnemonic from get_accKeyboardShortcut.

An AT such as an On Screen Keyboard might not expose these bindings but provide alternative means of activation.

Note: the client allocates and passes in an array of pointers. The server allocates the BSTRs and passes back one or more pointers to these BSTRs into the array of pointers allocated by the client. The client is responsible for deallocating the BSTRs.

Parameters:
[in] actionIndex 0 based index specifying which action's key bindings should be returned.
[in] nMaxBindings This parameter is ignored. Refer to Special Consideration when using Arrays for more details.
[out] keyBindings An array of BSTRs, allocated by the server, one for each key binding. Free it with CoTaskMemFree.
[out] nBindings The number of key bindings returned; the size of the returned array.
Return values:
S_OK 
S_FALSE if there are no key bindings, [out] values are NULL and 0 respectively
E_INVALIDARG if bad [in] passed

HRESULT IAccessibleAction::localizedName ( [in] long  actionIndex,
[out, retval] BSTR *  localizedName 
) [get]

Returns the localized name of specified action.

Parameters:
[in] actionIndex 0 based index specifying which action's localized name should be returned.
[out] localizedName 
Return values:
S_OK 
S_FALSE if there is nothing to return, [out] value is NULL
E_INVALIDARG if bad [in] passed

HRESULT IAccessibleAction::nActions ( [out, retval] long *  nActions  ) 

Returns the number of accessible actions available in this object.

If there are more than one, the first one is considered the "default" action of the object.

Parameters:
[out] nActions The returned value of the number of actions is zero if there are no actions.
Return values:
S_OK 
Note:
This method is missing a [propget] prefix in the IDL. The result is the method is named nActions in generated C++ code instead of get_nActions.

HRESULT IAccessibleAction::name ( [in] long  actionIndex,
[out, retval] BSTR *  name 
) [get]

Returns the non-localized name of specified action.

Parameters:
[in] actionIndex 0 based index specifying which action's non-localized name should be returned.
[out] name 
Return values:
S_OK 
S_FALSE if there is nothing to return, [out] value is NULL
E_INVALIDARG if bad [in] passed


The documentation for this interface was generated from the following file:

To submit feedback on IAccessible2 API Version 1.2.1, please use the Bugzilla interface located at: http://bugs.linuxfoundation.org/. When using Bugzilla please be sure to select IAccessible2 from the list of components. Bugzilla is the preferred method for receiving feedback because it automatically logs one's feedback in the IAccessible2 tracking system without additional human intervention. One may also, however, send email to accessibility-rfc@a11y.org, a publicly archived emailing list. Please address any technical problems you encounter with this document or the resources to which it links, to the Open A11y Webmaster <webmaster@a11y.org>

A stable online reference version of the documentation for IAccessible2 API Version 1.2.1, is available at: http://a11y.org/ia2-spec. A list of known and reported errors in the documentation for IAccessible2 API Version 1.2.1 can be found at: http://a11y.org/ia2-errata


Generated on Fri Jan 21 14:02:45 2011 for IAccessible2 API Version 1.2.1 by  doxygen 1.5.6