other-licenses/ia2/AccessibleText.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (AccessibleText.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) IBM Corp. 2007
   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 import "IA2CommonTypes.idl";
  30
  31 /// A structure containing a substring and the start and end offsets in the enclosing string.
  32 typedef struct {
  33   BSTR text;    ///< A copy of a segment of text taken from an enclosing paragraph.
  34   long start;   ///< Index of the first character of the segment in the enclosing text.
  35   long end;             ///< Index of the character following the last character of the segment in the enclosing text.
  36 } IA2TextSegment;
  37
  38 /** @brief Defines values to specify a text boundary type.
  39
  40  If one of these is not implemented, such as IA2_TEXT_BOUNDARY_SENTENCE, S_FALSE is returned.
  41 */
  42
  43 enum IA2TextBoundaryType {
  44   IA2_TEXT_BOUNDARY_CHAR,               ///< =0,
  45   IA2_TEXT_BOUNDARY_WORD,               ///< Range is from start of one word to the start of another word.
  46   IA2_TEXT_BOUNDARY_SENTENCE,   ///< Range is from start of one sentence to the start of another sentence.
  47   IA2_TEXT_BOUNDARY_PARAGRAPH,  ///< Range is from start of one paragraph to the start of another paragraph.
  48   IA2_TEXT_BOUNDARY_LINE,               /**< Range is from start of one line to the start of another line. This
  49                                  often means that an end-of-line character will appear at the  end of
  50                                                                  the range. However in the case of some apps an end-of-line character
  51                                                                  indicates the end of a paragraph and the lines composing the paragraph,
  52                                                                  other than the last line, do not contain an end of line character. */
  53   IA2_TEXT_BOUNDARY_ALL                 ///< Using this value will cause all text to be returned.
  54 };
  55
  56 /** @brief This interface gives read-only access to text.
  57
  58  The IAccessibleText interface should be implemented by all components
  59   that present textual information on the display like  buttons,
  60   text entry fields, or text portions of the document window.  The interface
  61   provides access to the text's content, attributes, and spatial location.
  62   However, text can not be modified with this interface.  That is the task
  63   of the IAccessibleEditableText interface.
  64
  65  The text length, i.e. the number of characters in the text, is
  66   returned by IAccessibleText::nCharacters. All methods that operate
  67   on particular characters (e.g. IAccessibleText::textAtOffset) use character
  68   indices from 0 to length-1. All methods that operate on character positions
  69   (e.g. IAccessibleText::text) use indices from 0 to length.
  70
  71  Please note that accessible text does not necessarily support selection.
  72   In this case it should behave as if there where no selection.  An empty
  73   selection is used for example to express the current cursor position.
  74 */
  75 [object, uuid(24FD2FFB-3AAD-4a08-8335-A3AD89C0FB4B)]
  76 interface IAccessibleText : IUnknown
  77 {
  78
  79   /** @brief Adds a text selection
  80    @param [in] startOffset
  81     Starting offset ( 0-based).
  82    @param [in] endOffset
  83     Offset of first character after new selection (0-based).
  84   */
  85   HRESULT addSelection
  86     (
  87      [in] long startOffset,
  88      [in] long endOffset
  89     );
  90
  91   /** @brief Returns text attributes.
  92    @param [in] offset
  93     Text offset (0-based).
  94    @param [out] startOffset
  95     Start of requested text range (0-based)
  96    @param [out] endOffset
  97     First character after requested text range (0-based)
  98    @param [out] textAttributes
  99     A string of attributes describing the text.
 100   */
 101   [propget] HRESULT attributes
 102     (
 103      [in] long offset,
 104      [out] long *startOffset,
 105      [out] long *endOffset,
 106      [out, retval] BSTR *textAttributes
 107     );
 108
 109   /** @brief Returns the position of the caret.
 110
 111    The caret is the position between two characters. Its position/offset
 112     is that of the character to the right of it.
 113    @param [out] offset
 114     The returned offset is relative to the text represented by this object.
 115   */
 116   [propget] HRESULT caretOffset
 117     (
 118      [out, retval] long *offset
 119     );
 120
 121
 122   /** @brief Returns the bounding box of the specified position.
 123
 124    The virtual character after the last character of the represented
 125     text, i.e. the one at position length is a special case. It represents the
 126     current input position and will therefore typically be queried by AT more
 127     often than other positions.  Because it does not represent an existing character
 128     its bounding box is defined in relation to preceding characters.  It should be
 129     roughly equivalent to the bounding box of some character when inserted at the
 130     end of the text.  Its height typically being the maximal height of all the
 131     characters in the text or the height of the preceding character, its width being
 132     at least one pixel so that the bounding box is not degenerate.
 133
 134    Note that the index 'length' is not always valid.  Whether it is or not is
 135     implementation dependent.  It typically is when text is editable or otherwise
 136     when on the screen the caret can be placed behind the text.  You can be sure
 137     that the index is valid after you have received a ::IA2_EVENT_TEXT_CARET_MOVED
 138     event for this index.
 139    @param [in] offset
 140     Index of the character for which to return its bounding box. The valid range
 141     is 0..length.
 142    @param [in] coordType
 143     Specifies if the coordinates are relative to the screen or to the parent window.
 144    @param [out] x
 145     X coordinate of the bounding box of the referenced character.
 146    @param [out] y
 147     Y coordinate of the bounding box of the referenced character.
 148    @param [out] width
 149     Width of the bounding box of the referenced character.
 150    @param [out] height
 151     Height of the bounding box of the referenced character.
 152   */
 153   [propget] HRESULT characterExtents
 154     (
 155      [in] long offset,
 156      [in] enum IA2CoordinateType coordType,
 157      [out] long *x,
 158      [out] long *y,
 159      [out] long *width,
 160      [out, retval] long *height
 161     );
 162
 163
 164   /** @brief Returns the number of active non-contiguous selections
 165    @param [out] nSelections
 166   */
 167   [propget] HRESULT nSelections
 168     (
 169      [out, retval] long *nSelections
 170     );
 171
 172   /** @brief Returns the text position for the specified screen position.
 173
 174    Given a point return the zero-based index of the character under that
 175    point.  The same functionality could be achieved by using the bounding
 176    boxes for each character as returned by IAccessibleText::characterExtents.
 177    The method IAccessibleText::offsetAtPoint, however, can be implemented
 178    more efficiently.
 179
 180    @param [in] x
 181     The position's x value for which to look up the index of the character that
 182         is rendered on to the display at that point.
 183    @param [in] y
 184     The position's y value for which to look up the index of the character that
 185         is rendered on to the display at that point.
 186    @param [in] coordType
 187     Screen coordinates or window coordinates.
 188    @param [out] offset
 189     Index of the character under the given point or -1 if the point
 190     is invalid or there is no character under the point.
 191     */
 192   [propget] HRESULT offsetAtPoint
 193     (
 194      [in] long x,
 195      [in] long y,
 196      [in] enum IA2CoordinateType coordType,
 197      [out, retval] long *offset
 198     );
 199
 200   /** @brief Returns the character offsets of N-th active text selection
 201    @param [in] selectionIndex
 202     Index of selection (0-based).
 203    @param [out] startOffset
 204     0 based offset of first selected character
 205    @param [out] endOffset
 206     0 based offset of one past the last selected character.
 207   */
 208   [propget] HRESULT selection
 209     (
 210      [in] long selectionIndex, ///< index of selection (0-based)
 211      [out] long *startOffset,
 212      [out, retval] long *endOffset
 213     );
 214
 215   /** @brief Returns the substring between the two given indices.
 216
 217    The substring starts with the character at startOffset (inclusive) and up to
 218     the character at endOffset (exclusive), if startOffset is less or equal
 219     endOffste.  If endOffset is lower than startOffset, the result is the same
 220     as a call with the two arguments being exchanged.
 221
 222    The whole text can be requested by passing the indices zero and
 223     IAccessibleText::nCharacters. If both indices have the same value, an empty
 224         string is returned.
 225    @param [in] startOffset
 226     Index of the first character to include in the returned string. The valid range
 227     is 0..length.
 228    @param [in] endOffset
 229     Index of the last character to exclude in the returned string. The valid range
 230     is 0..length.
 231    @param [out] text
 232     Returns the substring starting with the character at startOffset (inclusive)
 233     and up to the character at endOffset (exclusive), if startOffset is less than
 234     or equal to endOffset.
 235
 236    Note: returned string may be longer than endOffset-startOffset bytes if text
 237    contains multi-byte characters.
 238   */
 239   [propget] HRESULT text
 240     (
 241      [in] long startOffset,
 242      [in] long endOffset,
 243      [out, retval] BSTR *text
 244     );
 245
 246   /** @brief Returns a text portion before the given position.
 247
 248    Returns the substring of the specified text type that is located before the
 249     given character and does not include it. The result of this method should be
 250     same as a result for IAccessibleText::textAtOffset with a suitably decreased
 251     index value.
 252
 253    For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete
 254     word that is closest to and located before offset is returned.
 255
 256    If the index is valid, but no suitable word (or other text type) is found, an
 257     empty text segment is returned.
 258    @param [in] offset
 259     Index of the character for which to return the text part before it.  The index
 260     character will not be part of the returned string. The valid range is 0..length.
 261    @param [in] boundaryType
 262     The type of the text portion to return.  See ::IA2TextBoundaryType for the
 263         complete list.
 264    @param [out] startOffset
 265     0 based offset of first character.
 266    @param [out] endOffset
 267     0 based offset of one past the last character.
 268    @param [out] text
 269     Returns the requested text portion.  This portion may be empty or invalid when
 270     no appropriate text portion is found or text type is invalid.
 271   */
 272   [propget] HRESULT textBeforeOffset
 273     (
 274      [in] long offset,
 275      [in] enum IA2TextBoundaryType boundaryType,
 276      [out] long *startOffset,
 277      [out] long *endOffset,
 278      [out, retval] BSTR *text
 279     );
 280
 281   /** @brief Returns a text portion after the given position.
 282
 283    Returns the substring of the specified text type that is located after the
 284     given character and does not include it. The result of this method should be
 285     same as a result for IAccessibleText::textAtOffset with a suitably decreased
 286     index value.
 287
 288    For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete
 289     word that is closest to and located before offset is returned.
 290
 291    If the index is valid, but no suitable word (or other text type) is found, an
 292     empty text segment is returned.
 293    @param [in] offset
 294     Index of the character for which to return the text part before it.  The index
 295     character will not be part of the returned string. The valid range is 0..length.
 296    @param [in] boundaryType
 297     The type of the text portion to return.  See ::IA2TextBoundaryType for the complete
 298     list.
 299    @param [out] startOffset
 300     0 based offset of first character.
 301    @param [out] endOffset
 302     0 based offset of one past the last character.
 303    @param [out] text
 304     Returns the requested text portion.  This portion may be empty or invalid when
 305     no appropriate text portion is found or text type is invalid.
 306   */
 307   [propget] HRESULT textAfterOffset
 308     (
 309      [in] long offset,
 310      [in] enum IA2TextBoundaryType boundaryType,
 311      [out] long *startOffset,
 312      [out] long *endOffset,
 313      [out, retval] BSTR *text
 314     );
 315
 316   /** @brief Returns a text portion that spans the given position.
 317
 318    Returns the substring of the specified text type that the specified offset. The
 319     result of this method should be same as a result for
 320     IAccessibleText::textAtOffset with a suitably decreased index value.
 321
 322    For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete
 323     word that is closest to and located before offset is returned.
 324
 325    If the index is valid, but no suitable word (or other text type) is found, an
 326     empty text segment is returned.
 327    @param [in] offset
 328     Index of the character for which to return the text part before it.  The index
 329     character will not be part of the returned string. The valid range is 0..length.
 330    @param [in] boundaryType
 331     The type of the text portion to return.  See ::IA2TextBoundaryType for the complete
 332     list.
 333    @param [out] startOffset
 334     0 based offset of first character.
 335    @param [out] endOffset
 336     0 based offset of one past the last character.
 337    @param [out] text
 338     Returns the requested text portion.  This portion may be empty or invalid when
 339     no appropriate text portion is found or text type is invalid.
 340   */
 341   [propget] HRESULT textAtOffset
 342     (
 343      [in] long offset,
 344      [in] enum IA2TextBoundaryType boundaryType,
 345      [out] long *startOffset,
 346      [out] long *endOffset,
 347      [out, retval] BSTR *text
 348     );
 349
 350   /** @brief Unselects a range of text.
 351    @param [in] selectionIndex
 352     Index of selection to remove (0-based).
 353   */
 354   HRESULT removeSelection
 355     (
 356      [in] long selectionIndex
 357     );
 358
 359   /** @brief Sets the position of the caret.
 360
 361    The caret is the position between two characters.  Its position/offset
 362     is that of the character to the right of it.
 363
 364    Setting the caret position may or may not alter the current selection.  A
 365     change of the selection is notified to the accessibility event listeners with
 366     an ::IA2_EVENT_TEXT_SELECTION_CHANGED event.
 367
 368    When the new caret position differs from the old one (which, of course, is the
 369     standard case) this is notified to the accessibility event listeners with an
 370     ::IA2_EVENT_TEXT_CARET_MOVED event.
 371    @param [in] offset
 372     The new index of the caret.  This caret is actually placed to the left side of
 373     the character with that index.  An index of 0 places the caret so that the next
 374     insertion goes before the first character.  An index of IAccessibleText::nCharacters
 375         leads to insertion after the last character.
 376   */
 377   HRESULT setCaretOffset
 378     (
 379      [in] long offset
 380     );
 381
 382   /** @brief Changes the bounds of an existing selection.
 383    @param [in] selectionIndex
 384     Index of selection to change (0-based)
 385    @param [in] startOffset
 386     New starting offset (0-based)
 387    @param [in] endOffset
 388     New ending offset (0-based) - the offset of the character just past the last character of the selection.
 389   */
 390   HRESULT setSelection
 391     (
 392      [in] long selectionIndex,
 393      [in] long startOffset,
 394      [in] long endOffset
 395     );
 396
 397   /** @brief Returns total number of characters.
 398
 399    Note: This may be different than the total number of bytes required to store the
 400     text, if the text contains multi-byte characters.
 401    @param [out] nCharacters
 402   */
 403   [propget] HRESULT nCharacters
 404     (
 405      [out, retval] long *nCharacters
 406     );
 407
 408   /** @brief Makes a specific part of string visible on screen.
 409    @param [in] startIndex
 410     0-based character offset.
 411    @param [in] endIndex
 412     0-based character offset - the offset of the character just past the last character of the string.
 413    @param [in] scrollType
 414     Defines where the object should be placed on the screen.
 415   */
 416   HRESULT scrollSubstringTo
 417     (
 418      [in] long startIndex,
 419      [in] long endIndex,
 420          [in] enum IA2ScrollType scrollType
 421     );
 422
 423   /** @brief Moves the top left of a substring to a specified location.
 424
 425    Note: S_FALSE is returned if the object is already at the specified location.
 426    @param [in] startIndex
 427     0-based character offset.
 428    @param [in] endIndex
 429     0-based character offset - the offset of the character just past the last character of the string.
 430    @param [in] coordinateType
 431     Specifies whether the coordinates are relative to the screen or the parent object.
 432    @param [in] x
 433     Defines the x coordinate.
 434    @param [in] y
 435     Defines the y coordinate.
 436   */
 437   HRESULT scrollSubstringToPoint
 438     (
 439      [in] long startIndex,
 440      [in] long endIndex,
 441      [in] enum IA2CoordinateType coordinateType,
 442          [in] long x,
 443          [in] long y
 444     );
 445
 446   /** @brief Returns any inserted text.
 447
 448    Provided for use by the ::IA2_EVENT_TEXT_INSERTED and ::IA2_EVENT_TEXT_UPDATED
 449     event handlers.
 450    @param [out] newText
 451     The text that was just inserted.
 452   */
 453   [propget] HRESULT newText
 454     (
 455          [out, retval] IA2TextSegment *newText
 456         );
 457
 458   /** @brief Returns any removed text.
 459
 460    Provided for use by the IA2_EVENT_TEXT_REMOVED/UPDATED event handlers.
 461    @param [out] oldText
 462     The text that was just removed.
 463   */
 464   [propget] HRESULT oldText
 465     (
 466          [out, retval] IA2TextSegment *oldText
 467         );
 468
 469 }