AccessibleAction.idl (9496B)
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 }