michael@0: /************************************************************************* michael@0: * michael@0: * File Name (AccessibleAction.idl) michael@0: * michael@0: * IAccessible2 IDL Specification michael@0: * michael@0: * Copyright (c) 2007, 2013 Linux Foundation michael@0: * Copyright (c) 2006 IBM Corporation michael@0: * Copyright (c) 2000, 2006 Sun Microsystems, Inc. michael@0: * All rights reserved. michael@0: * michael@0: * michael@0: * Redistribution and use in source and binary forms, with or without michael@0: * modification, are permitted provided that the following conditions michael@0: * are met: michael@0: * michael@0: * 1. Redistributions of source code must retain the above copyright michael@0: * notice, this list of conditions and the following disclaimer. michael@0: * michael@0: * 2. Redistributions in binary form must reproduce the above michael@0: * copyright notice, this list of conditions and the following michael@0: * disclaimer in the documentation and/or other materials michael@0: * provided with the distribution. michael@0: * michael@0: * 3. Neither the name of the Linux Foundation nor the names of its michael@0: * contributors may be used to endorse or promote products michael@0: * derived from this software without specific prior written michael@0: * permission. michael@0: * michael@0: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND michael@0: * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, michael@0: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF michael@0: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE michael@0: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR michael@0: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, michael@0: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT michael@0: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; michael@0: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) michael@0: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN michael@0: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR michael@0: * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, michael@0: * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. michael@0: * michael@0: * This BSD License conforms to the Open Source Initiative "Simplified michael@0: * BSD License" as published at: michael@0: * http://www.opensource.org/licenses/bsd-license.php michael@0: * michael@0: * IAccessible2 is a trademark of the Linux Foundation. The IAccessible2 michael@0: * mark may be used in accordance with the Linux Foundation Trademark michael@0: * Policy to indicate compliance with the IAccessible2 specification. michael@0: * michael@0: ************************************************************************/ michael@0: michael@0: import "objidl.idl"; michael@0: import "oaidl.idl"; michael@0: import "oleacc.idl"; michael@0: michael@0: /** This enum defines values which are predefined actions for use when implementing michael@0: support for media. michael@0: michael@0: This enum is used when specifying an action for IAccessibleAction::doAction. michael@0: */ michael@0: michael@0: enum IA2Actions { michael@0: IA2_ACTION_OPEN = -1, /**< Used to inform the server that the client will michael@0: signal via IA2_ACTION_COMPLETE when it has consumed michael@0: the content provided by the object. This action michael@0: allows the object's server to wait for all clients michael@0: to signal their readiness for additional content. michael@0: Any form of content generation that requires michael@0: synchronization with an AT would require use of this michael@0: action. One example is the generation of text describing michael@0: visual content not obvious from a video's sound track. michael@0: In this scenario the Text to Speech or Braille output michael@0: may take more time than the related length of silence michael@0: in the video's sound track. */ michael@0: IA2_ACTION_COMPLETE = -2, /**< Used by the client to inform the server that it has michael@0: consumed the most recent content provided by this object. */ michael@0: IA2_ACTION_CLOSE = -3 /**< Used to inform the server that the client no longer michael@0: requires synchronization. */ michael@0: }; michael@0: michael@0: /** @brief This interface gives access to actions that can be executed michael@0: for accessible objects. michael@0: michael@0: Every accessible object that can be manipulated via the native GUI beyond the michael@0: methods available either in the MSAA IAccessible interface or in the set of michael@0: IAccessible2 interfaces (other than this IAccessibleAction interface) should michael@0: support the IAccessibleAction interface in order to provide Assistive Technology michael@0: access to all the actions that can be performed by the object. Each action can michael@0: be performed or queried for a name, description or associated key bindings. michael@0: Actions are needed more for ATs that assist the mobility impaired, such as michael@0: on-screen keyboards and voice command software. By providing actions directly, michael@0: the AT can present them to the user without the user having to perform the extra michael@0: steps to navigate a context menu. michael@0: michael@0: The first action should be equivalent to the MSAA default action. If there is michael@0: only one action, %IAccessibleAction should also be implemented. michael@0: */ michael@0: [object, uuid(B70D9F59-3B5A-4dba-AB9E-22012F607DF5)] michael@0: interface IAccessibleAction : IUnknown michael@0: { michael@0: michael@0: /** @brief Returns the number of accessible actions available in this object. michael@0: michael@0: If there are more than one, the first one is considered the michael@0: "default" action of the object. michael@0: @param [out] nActions michael@0: The returned value of the number of actions is zero if there are michael@0: no actions. michael@0: @retval S_OK michael@0: @note This method is missing a [propget] prefix in the IDL. The result is the michael@0: method is named nActions in generated C++ code instead of get_nActions. michael@0: */ michael@0: HRESULT nActions michael@0: ( michael@0: [out,retval] long* nActions michael@0: ); michael@0: michael@0: /** @brief Performs the specified Action on the object. michael@0: @param [in] actionIndex michael@0: 0 based index specifying the action to perform. If it lies outside michael@0: the valid range no action is performed. michael@0: @retval S_OK michael@0: @retval S_FALSE if action could not be performed michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: @note If implementing support for media, refer to the predefined constants in the ::IA2Actions enum. michael@0: */ michael@0: HRESULT doAction michael@0: ( michael@0: [in] long actionIndex michael@0: ); michael@0: michael@0: /** @brief Returns a description of the specified action of the object. michael@0: @param [in] actionIndex michael@0: 0 based index specifying which action's description to return. michael@0: If it lies outside the valid range an empty string is returned. michael@0: @param [out] description michael@0: The returned value is a localized string of the specified action. michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT description michael@0: ( michael@0: [in] long actionIndex, michael@0: [out, retval] BSTR *description michael@0: ); michael@0: michael@0: /** @brief Returns an array of BSTRs describing one or more key bindings, if michael@0: there are any, associated with the specified action. michael@0: michael@0: The returned strings are the localized human readable key sequences to be michael@0: used to activate each action, e.g. "Ctrl+Shift+D". Since these key michael@0: sequences are to be used when the object has focus, they are like michael@0: mnemonics (access keys), and not like shortcut (accelerator) keys. michael@0: michael@0: There is no need to implement this method for single action controls since michael@0: that would be redundant with the standard MSAA programming practice of michael@0: getting the mnemonic from get_accKeyboardShortcut. michael@0: michael@0: An AT such as an On Screen Keyboard might not expose these bindings but michael@0: provide alternative means of activation. michael@0: michael@0: Note: the client allocates and passes in an array of pointers. The server michael@0: allocates the BSTRs and passes back one or more pointers to these BSTRs into michael@0: the array of pointers allocated by the client. The client is responsible michael@0: for deallocating the BSTRs. michael@0: michael@0: @param [in] actionIndex michael@0: 0 based index specifying which action's key bindings should be returned. michael@0: @param [in] nMaxBindings michael@0: This parameter is ignored. Refer to @ref _arrayConsideration michael@0: "Special Consideration when using Arrays" for more details. michael@0: @param [out] keyBindings michael@0: An array of BSTRs, allocated by the server, one for each key binding. michael@0: The client must free it with CoTaskMemFree. michael@0: @param [out] nBindings michael@0: The number of key bindings returned; the size of the returned array. michael@0: @retval S_OK michael@0: @retval S_FALSE if there are no key bindings, [out] values are NULL and 0 respectively michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT keyBinding michael@0: ( michael@0: [in] long actionIndex, michael@0: [in] long nMaxBindings, michael@0: [out, size_is(,nMaxBindings), length_is(,*nBindings)] BSTR **keyBindings, michael@0: [out, retval] long *nBindings michael@0: ); michael@0: michael@0: /** @brief Returns the non-localized name of specified action. michael@0: @param [in] actionIndex michael@0: 0 based index specifying which action's non-localized name should be returned. michael@0: @param [out] name michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT name michael@0: ( michael@0: [in] long actionIndex, michael@0: [out, retval] BSTR *name michael@0: ); michael@0: michael@0: /** @brief Returns the localized name of specified action. michael@0: @param [in] actionIndex michael@0: 0 based index specifying which action's localized name should be returned. michael@0: @param [out] localizedName michael@0: @retval S_OK michael@0: @retval S_FALSE if there is nothing to return, [out] value is NULL michael@0: @retval E_INVALIDARG if bad [in] passed michael@0: */ michael@0: [propget] HRESULT localizedName michael@0: ( michael@0: [in] long actionIndex, michael@0: [out, retval] BSTR *localizedName michael@0: ); michael@0: michael@0: }