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.

Method overview

Methods

description()

Returns a description of the specified action of the object.

[propget] HRESULT description(
  [in] long actionIndex,
  [out] BSTR description
);

Parameters

actionIndex

0 based index specifying which action's description to return. If it lies outside the valid range an empty string is returned.

description

The returned value is a localized string of the specified action.

Return value

E_INVALIDARG if bad [in] passed, [out] value is null. S_FALSE if there is nothing to return, [out] value is null. S_OK.

doAction()

Performs the specified Action on the object.

HRESULT doAction(
  [in] long actionIndex
);

Parameters

actionIndex

0 based index specifying the action to perform. If it lies outside the valid range no action is performed.

Return value

E_INVALIDARG if bad [in] passed. S_OK.

keyBinding()

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.

[propget] HRESULT keyBinding(
  [in] long actionIndex,
  [in] long nMaxBindings,
  [out, size_is(,nMaxBindings), length_is(, nBindings)] BSTR keyBindings,
  [out] long nBindings
);

Parameters

actionIndex

0 based index specifying which action's key bindings should be returned.

nMaxBindings

This parameter is ignored. Refer to @ref _arrayConsideration "Special Consideration when using Arrays" for more details.

keyBindings

An array of BSTRs, allocated by the server, one for each key binding. Free it with CoTaskMemFree.

nBindings

The number of key bindings returned; the size of the returned array.

Return value

E_INVALIDARG if bad [in] passed, [out] values are null and 0 respectively. S_FALSE if there are no relations, [out] values are null and 0 respectively. S_OK.

localizedName()

Returns the localized name of specified action.

[propget] HRESULT localizedName(
  [in] long actionIndex,
  [out] BSTR localizedName
);

Parameters

actionIndex

0 based index specifying which action's localized name should be returned.

localizedName

The localized name of specified action.

Return value

E_INVALIDARG if bad [in] passed, [out] value is null. S_FALSE if there is nothing to return, [out] value is null. S_OK.

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.

HRESULT nActions(
  [out] long nActions
);

Parameters

nActions

The returned value of the number of actions is zero if there are no actions.

Return value

S_OK.

name()

Returns the non-localized name of the specified action.

[propget] HRESULT name(
  [in] long actionIndex,
  [out] BSTR name
);

Parameters

actionIndex

0 based index specifying which action's non-localized name should be returned.

name

The non-localized name of the specified action.

Return value

E_INVALIDARG if bad [in] passed, [out] value is null. S_FALSE if there is nothing to return, [out] value is null. S_OK.