The Tor Browser / file comparison
comparison: other-licenses/ia2/AccessibleAction.idl
other-licenses/ia2/AccessibleAction.idl
- changeset 0
- 6474c204b198
equal
deleted
inserted
replaced
| -1:000000000000 | 0:1e34f4895943 |
|---|---|
| 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 } |
