other-licenses/ia2/AccessibleAction.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (AccessibleAction.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) IBM Corp. 2006
   8  *  Copyright (c) Sun Microsystems, Inc. 2000, 2006
   9  *
  10  *  This library is free software; you can redistribute it and/or
  11  *  modify it under the terms of the GNU Lesser General Public
  12  *  License version 2.1, as published by the Free Software Foundation; either
  13  *  version 2.1 of the License, or (at your option) any later version.
  14  *
  15  *  This library is distributed in the hope that it will be useful,
  16  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  *  Lesser General Public License for more details.
  19  *
  20  *  You should have received a copy of the GNU Lesser General Public
  21  *  License along with this library; if not, write to the Free Software
  22  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
  23  *
  24  ************************************************************************/
  25
  26 import "objidl.idl";
  27 import "oaidl.idl";
  28 import "oleacc.idl";
  29
  30 /** @brief This interface gives access to actions that can be executed
  31   for accessible objects.
  32
  33  Every accessible object that can be manipulated beyond its methods
  34   exported over the accessibility API should support this interface to
  35   expose all actions that it can perform.  Each action can be performed
  36   or queried for a name, description or associated key bindings.  Actions
  37   are needed more for ATs that assist the mobility impaired.  By providing
  38   actions directly, the AT can present them to the user without the user having
  39   to perform the extra steps to navigate a context menu.
  40 */
  41 [object, uuid(B70D9F59-3B5A-4dba-AB9E-22012F607DF5)]
  42 interface IAccessibleAction : IUnknown
  43 {
  44
  45   /** @brief Returns the number of accessible actions available in this object.
  46
  47    If there are more than one, the first one is considered the
  48     "default" action of the object.
  49    @param [out] nActions
  50     The returned value of the number of actions is zero if there are
  51     no actions.
  52   */
  53   HRESULT nActions
  54     (
  55      [out,retval] long* nActions
  56     );
  57
  58   /** @brief Performs the specified Action on the object.
  59    @param [in] actionIndex
  60     This index specifies the action to perform.  If it lies outside
  61     the valid range no action is performed.
  62     */
  63   HRESULT doAction
  64     (
  65      [in] long actionIndex
  66     );
  67
  68   /** @brief Returns a description of the specified action of the object.
  69    @param [in] actionIndex
  70     This index specifies the action of which to return a
  71     description.  If it lies outside the valid range an empty string
  72     is returned.
  73    @param [out] description
  74     The returned value is a localized string of the specified action.
  75     */
  76   [propget] HRESULT description
  77     (
  78      [in] long actionIndex,
  79      [out, retval] BSTR *description
  80     );
  81
  82   /** @brief Returns an array of BSTRs describing one or more key bindings, if there
  83    are any, associated with the specified action.
  84
  85    Note: the client allocates and passes in an array of pointers.  The server
  86    allocates the BSTRs and passes back one or more pointers to these BSTRs into
  87    the array of pointers allocated by the client.  The client is responsible
  88    for deallocating the BSTRs.
  89
  90    @param [in] actionIndex
  91     This index specifies the action of which to return the key bindings.
  92    @param [in] nMaxBinding
  93     The maximum number of keybindings requested, i.e. the size of the array
  94         allocated to hold the results.
  95    @param [out] keyBinding
  96     An array of BSTRs, one for each key binding.
  97    @param [out] nBinding
  98     The actual number of key bindings returned.
  99   */
 100   [propget] HRESULT keyBinding
 101     (
 102      [in] long actionIndex,
 103      [in] long nMaxBinding,
 104      [out, size_is(,nMaxBinding), length_is(,*nBinding)] BSTR **keyBinding,
 105          [out, retval] long *nBinding
 106     );
 107
 108   /** @brief Returns the non-localized name of specified action.
 109    @param [in] actionIndex
 110    @param [out] name
 111   */
 112   [propget] HRESULT name
 113     (
 114      [in] long actionIndex,
 115      [out, retval] BSTR *name
 116     );
 117
 118   /** @brief Returns the localized name of specified action.
 119    @param [in] actionIndex
 120    @param [out] localizedName
 121   */
 122   [propget] HRESULT localizedName
 123     (
 124      [in] long actionIndex,
 125      [out, retval] BSTR *localizedName
 126     );
 127
 128 }