other-licenses/ia2/AccessibleAction.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (AccessibleAction.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) 2007, 2013 Linux Foundation
   8  *  Copyright (c) 2006 IBM Corporation
   9  *  Copyright (c) 2000, 2006 Sun Microsystems, Inc.
  10  *  All rights reserved.
  11  *
  12  *
  13  *  Redistribution and use in source and binary forms, with or without
  14  *  modification, are permitted provided that the following conditions
  15  *  are met:
  16  *
  17  *   1. Redistributions of source code must retain the above copyright
  18  *      notice, this list of conditions and the following disclaimer.
  19  *
  20  *   2. Redistributions in binary form must reproduce the above
  21  *      copyright notice, this list of conditions and the following
  22  *      disclaimer in the documentation and/or other materials
  23  *      provided with the distribution.
  24  *
  25  *   3. Neither the name of the Linux Foundation nor the names of its
  26  *      contributors may be used to endorse or promote products
  27  *      derived from this software without specific prior written
  28  *      permission.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  31  *  CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  32  *  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  33  *  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  34  *  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
  35  *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  36  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  37  *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  38  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  39  *  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  40  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  41  *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  42  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  43  *
  44  *  This BSD License conforms to the Open Source Initiative "Simplified
  45  *  BSD License" as published at:
  46  *  http://www.opensource.org/licenses/bsd-license.php
  47  *
  48  *  IAccessible2 is a trademark of the Linux Foundation. The IAccessible2
  49  *  mark may be used in accordance with the Linux Foundation Trademark
  50  *  Policy to indicate compliance with the IAccessible2 specification.
  51  *
  52  ************************************************************************/
  53
  54 import "objidl.idl";
  55 import "oaidl.idl";
  56 import "oleacc.idl";
  57
  58 /** This enum defines values which are predefined actions for use when implementing
  59  support for media.
  60
  61  This enum is used when specifying an action for IAccessibleAction::doAction.
  62 */
  63
  64 enum IA2Actions {
  65   IA2_ACTION_OPEN = -1,         /**< Used to inform the server that the client will
  66                                 signal via IA2_ACTION_COMPLETE when it has consumed
  67                                 the content provided by the object.  This action
  68                                 allows the object's server to wait for all clients
  69                                 to signal their readiness for additional content.
  70                                 Any form of content generation that requires
  71                                 synchronization with an AT would require use of this
  72                                 action.  One example is the generation of text describing
  73                                 visual content not obvious from a video's sound track.
  74                                 In this scenario the Text to Speech or Braille output
  75                                 may take more time than the related length of silence
  76                                 in the video's sound track. */
  77   IA2_ACTION_COMPLETE = -2,     /**< Used by the client to inform the server that it has
  78                                 consumed the most recent content provided by this object. */
  79   IA2_ACTION_CLOSE = -3         /**< Used to inform the server that the client no longer
  80                                 requires synchronization. */
  81 };
  82
  83 /** @brief This interface gives access to actions that can be executed
  84   for accessible objects.
  85
  86  Every accessible object that can be manipulated via the native GUI beyond the
  87   methods available either in the MSAA IAccessible interface or in the set of
  88   IAccessible2 interfaces (other than this IAccessibleAction interface) should
  89   support the IAccessibleAction interface in order to provide Assistive Technology
  90   access to all the actions that can be performed by the object.  Each action can
  91   be performed or queried for a name, description or associated key bindings.
  92   Actions are needed more for ATs that assist the mobility impaired, such as
  93   on-screen keyboards and voice command software.  By providing actions directly,
  94   the AT can present them to the user without the user having to perform the extra
  95   steps to navigate a context menu.
  96
  97  The first action should be equivalent to the MSAA default action.  If there is
  98   only one action, %IAccessibleAction should also be implemented.
  99 */
 100 [object, uuid(B70D9F59-3B5A-4dba-AB9E-22012F607DF5)]
 101 interface IAccessibleAction : IUnknown
 102 {
 103
 104   /** @brief Returns the number of accessible actions available in this object.
 105
 106    If there are more than one, the first one is considered the
 107     "default" action of the object.
 108    @param [out] nActions
 109     The returned value of the number of actions is zero if there are
 110     no actions.
 111    @retval S_OK
 112    @note This method is missing a [propget] prefix in the IDL.  The result is the
 113     method is named nActions in generated C++ code instead of get_nActions.
 114   */
 115   HRESULT nActions
 116     (
 117      [out,retval] long* nActions
 118     );
 119
 120   /** @brief Performs the specified Action on the object.
 121    @param [in] actionIndex
 122     0 based index specifying the action to perform.  If it lies outside
 123     the valid range no action is performed.
 124    @retval S_OK
 125    @retval S_FALSE if action could not be performed
 126    @retval E_INVALIDARG if bad [in] passed
 127    @note If implementing support for media, refer to the predefined constants in the ::IA2Actions enum.
 128     */
 129   HRESULT doAction
 130     (
 131      [in] long actionIndex
 132     );
 133
 134   /** @brief Returns a description of the specified action of the object.
 135    @param [in] actionIndex
 136     0 based index specifying which action's description to return.
 137     If it lies outside the valid range an empty string is returned.
 138    @param [out] description
 139     The returned value is a localized string of the specified action.
 140    @retval S_OK
 141    @retval S_FALSE if there is nothing to return, [out] value is NULL
 142    @retval E_INVALIDARG if bad [in] passed
 143     */
 144   [propget] HRESULT description
 145     (
 146      [in] long actionIndex,
 147      [out, retval] BSTR *description
 148     );
 149
 150   /** @brief Returns an array of BSTRs describing one or more key bindings, if
 151    there are any, associated with the specified action.
 152
 153    The returned strings are the localized human readable key sequences to be
 154    used to activate each action, e.g. "Ctrl+Shift+D".  Since these key
 155    sequences are to be used when the object has focus, they are like
 156    mnemonics (access keys), and not like shortcut (accelerator) keys.
 157
 158    There is no need to implement this method for single action controls since
 159    that would be redundant with the standard MSAA programming practice of
 160    getting the mnemonic from get_accKeyboardShortcut.
 161
 162    An AT such as an On Screen Keyboard might not expose these bindings but
 163    provide alternative means of activation.
 164
 165    Note: the client allocates and passes in an array of pointers.  The server
 166    allocates the BSTRs and passes back one or more pointers to these BSTRs into
 167    the array of pointers allocated by the client.  The client is responsible
 168    for deallocating the BSTRs.
 169
 170    @param [in] actionIndex
 171     0 based index specifying which action's key bindings should be returned.
 172    @param [in] nMaxBindings
 173     This parameter is ignored. Refer to @ref _arrayConsideration
 174         "Special Consideration when using Arrays" for more details.
 175    @param [out] keyBindings
 176     An array of BSTRs, allocated by the server, one for each key binding.
 177         The client must free it with CoTaskMemFree.
 178    @param [out] nBindings
 179     The number of key bindings returned; the size of the returned array.
 180    @retval S_OK
 181    @retval S_FALSE if there are no key bindings, [out] values are NULL and 0 respectively
 182    @retval E_INVALIDARG if bad [in] passed
 183         */
 184   [propget] HRESULT keyBinding
 185     (
 186      [in] long actionIndex,
 187      [in] long nMaxBindings,
 188      [out, size_is(,nMaxBindings), length_is(,*nBindings)] BSTR **keyBindings,
 189          [out, retval] long *nBindings
 190     );
 191
 192   /** @brief Returns the non-localized name of specified action.
 193    @param [in] actionIndex
 194     0 based index specifying which action's non-localized name should be returned.
 195    @param [out] name
 196    @retval S_OK
 197    @retval S_FALSE if there is nothing to return, [out] value is NULL
 198    @retval E_INVALIDARG if bad [in] passed
 199    */
 200   [propget] HRESULT name
 201     (
 202      [in] long actionIndex,
 203      [out, retval] BSTR *name
 204     );
 205
 206   /** @brief Returns the localized name of specified action.
 207    @param [in] actionIndex
 208     0 based index specifying which action's localized name should be returned.
 209    @param [out] localizedName
 210    @retval S_OK
 211    @retval S_FALSE if there is nothing to return, [out] value is NULL
 212    @retval E_INVALIDARG if bad [in] passed
 213    */
 214   [propget] HRESULT localizedName
 215     (
 216      [in] long actionIndex,
 217      [out, retval] BSTR *localizedName
 218     );
 219
 220 }