other-licenses/ia2/AccessibleEditableText.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (AccessibleEditableText.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) 2007, 2012 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 import "IA2CommonTypes.idl";
  58
  59 /** @brief This interface provides clipboard capability to text objects.
  60
  61  This interface is typically used in conjunction with the IAccessibleText
  62   interface and complements that interface with the additional capability of
  63   clipboard operations.  Note that even a read only text object can support
  64   the copy capability so this interface is not limited to editable objects.
  65
  66  The substrings used with this interface are specified as follows:
  67   If startOffset is less than endOffset, the substring starts with the
  68   character at startOffset and ends with the character just before endOffset.
  69   If endOffset is lower than startOffset,  the result is the same as a call
  70   with the two arguments exchanged. The whole text can be defined by passing
  71   the indices zero and IAccessibleText::nCharacters. If both indices have the
  72   same value, an empty string is defined.
  73
  74  Refer to the @ref _specialOffsets
  75   "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
  76   for information about a special offset constant that can be used in %IAccessibleEditableText methods.
  77 */
  78 [object, uuid(A59AA09A-7011-4b65-939D-32B1FB5547E3)]
  79 interface IAccessibleEditableText : IUnknown
  80 {
  81
  82   /** @brief Copies the text range into the clipboard.
  83
  84    The selection is set to the specified offsets and then selection is copied into
  85    the system clipboard.
  86
  87    @param [in] startOffset
  88     Start index of the text to moved into the clipboard.
  89     The valid range is 0..length.
  90    @param [in] endOffset
  91     End index of the text to moved into the clipboard.
  92     The valid range is 0..length.
  93    @retval S_OK
  94    @retval E_INVALIDARG if bad [in] passed
  95    @note Refer to @ref _specialOffsets
  96     "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
  97     for information about special offsets that can be used in %IAccessibleEditableText
  98     methods.
  99    @deprecated This function is available via the application's GUI.
 100   */
 101   HRESULT copyText
 102     (
 103      [in] long startOffset,
 104      [in] long endOffset
 105     );
 106
 107   /** @brief Deletes a range of text.
 108
 109    The text between and including the two given indices is deleted
 110     from the text represented by this object.
 111
 112    @param [in] startOffset
 113     Start index of the text to be deleted.
 114     The valid range is 0..length.
 115    @param [in] endOffset
 116     End index of the text to be deleted.
 117     The valid range is 0..length.
 118    @retval S_OK
 119    @retval E_INVALIDARG if bad [in] passed
 120    @note Refer to @ref _specialOffsets
 121     "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
 122     for information about special offsets that can be used in %IAccessibleEditableText
 123     methods.
 124   */
 125   HRESULT deleteText
 126     (
 127      [in] long startOffset,
 128      [in] long endOffset
 129     );
 130
 131   /** @brief Inserts text at the specified position.
 132
 133    The specified string is inserted at the given index into the text
 134     represented by this object.
 135
 136    @param [in] offset
 137     Index at which to insert the text.
 138     The valid range is 0..length.
 139         Refer to @ref _specialOffsets
 140     "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
 141     for information about special offsets that can be used in %IAccessibleEditableText
 142     methods.
 143    @param [in] text
 144     Text that is inserted.
 145    @retval S_OK
 146    @retval E_INVALIDARG if bad [in] passed
 147   */
 148   HRESULT insertText
 149     (
 150      [in] long offset,
 151      [in] BSTR *text
 152     );
 153
 154   /** @brief Deletes a range of text and copies it to the clipboard.
 155
 156    The selection is set to the specified offsets, the selection is then copied into
 157     the system clipboard, and then the selection is deleted.
 158
 159    @param [in] startOffset
 160     Start index of the text to be deleted.
 161     The valid range is 0..length.
 162    @param [in] endOffset
 163     End index of the text to be deleted.
 164     The valid range is 0..length.
 165    @retval S_OK
 166    @retval E_INVALIDARG if bad [in] passed
 167    @note Refer to @ref _specialOffsets
 168     "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
 169     for information about special offsets that can be used in %IAccessibleEditableText
 170     methods.
 171    @deprecated This function is available via the application's GUI.
 172   */
 173   HRESULT cutText
 174     (
 175      [in] long startOffset,
 176      [in] long endOffset
 177     );
 178
 179   /** @brief Pastes content from the clipboard.
 180
 181    Any existing selection is removed, the clipboard content is then pasted into
 182     this object's text at the given offset.  This method is similar to the insertText
 183     method.  If the index is not valid the system clipboard content is not inserted. The
 184     behavior is the same as     when Ctrl+V is used, i.e. the pasted contents are not
 185     necessarily plain text.
 186
 187    @param [in] offset
 188     Index at which to insert the content from the system clipboard into
 189     the text represented by this object.
 190     The valid range is 0..length.
 191         Refer to @ref _specialOffsets
 192     "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
 193     for information about special offsets that can be used in %IAccessibleEditableText
 194     methods.
 195    @retval S_OK
 196    @retval E_INVALIDARG if bad [in] passed
 197    @deprecated This function is available via the application's GUI.
 198   */
 199   HRESULT pasteText
 200     (
 201      [in] long offset
 202     );
 203
 204   /** @brief Replaces text.
 205
 206    The text between the two given indices is replaced by the specified
 207     replacement string. This method is equivalent to calling first
 208     IAccessibleEditableText::deleteText with the two indices and then
 209     calling IAccessibleEditableText::insertText with the replacement text
 210         at the start index.
 211
 212    @param [in] startOffset
 213     Start index of the text to be replaced.
 214     The valid range is 0..length.
 215    @param [in] endOffset
 216     End index of the text to be replaced.
 217     The valid range is 0..length.
 218    @param [in] text
 219     The Text that replaces the text between the given indices.
 220    @retval S_OK
 221    @retval E_INVALIDARG if bad [in] passed
 222    @note Refer to @ref _specialOffsets
 223     "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
 224     for information about special offsets that can be used in %IAccessibleEditableText
 225     methods.
 226   */
 227   HRESULT replaceText
 228     (
 229      [in] long startOffset,
 230      [in] long endOffset,
 231      [in] BSTR *text
 232     );
 233
 234   /** @brief Replaces the attributes of a text range by the given set of attributes.
 235
 236    Sets the attributes for the text between the two given indices. The old
 237     attributes are replaced by the new list of attributes.
 238
 239    @param [in] startOffset
 240     Start index of the text whose attributes are modified.
 241     The valid range is 0..length.
 242    @param [in] endOffset
 243     End index of the text whose attributes are modified.
 244     The valid range is 0..length.
 245    @param [in] attributes
 246     Set of attributes that replaces the old list of attributes of
 247     the specified text portion.
 248    @retval S_OK
 249    @retval E_INVALIDARG if bad [in] passed
 250    @note Refer to @ref _specialOffsets
 251     "Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
 252     for information about special offsets that can be used in %IAccessibleEditableText
 253     methods.
 254   */
 255   HRESULT setAttributes
 256     (
 257      [in] long startOffset,
 258      [in] long endOffset,
 259      [in] BSTR *attributes
 260     );
 261 }
 262