offapi/com/sun/star/accessibility/XAccessibleText.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 module com { module sun { module star { module accessibility {
  21
  22 /** Implement this interface to give read-only access to a text.
  23
  24     <p>The XAccessibleText interface should be implemented by
  25     all UNO components that present textual information on the display like
  26     buttons, text entry fields, or text portions of the document window.
  27     The interface provides access to the text's content, attributes, and
  28     spatial location.  However, text can not be modified with this
  29     interface.  That is the task of the XAccessibleEditableText
  30     interface.</p>
  31
  32     <p>The text length, i.e. the number of characters in the text, is
  33     returned by XAccessibleText::getCharacterCount().
  34     All methods that operate on particular characters (e.g.
  35     XAccessibleText::getCharacterAt()) use character
  36     indices from 0 to length-1. All methods that operate on character
  37     positions (e.g. XAccessibleText::getTextRange())
  38     use indices from 0 to length.</p>
  39
  40     <p>Please note that accessible text does not necessarily support
  41     selection.  In this case it should behave as if there where no
  42     selection.  An empty selection is used for example to express the
  43     current cursor position.</p>
  44
  45     @since OOo 1.1.2
  46 */
  47 interface XAccessibleText : ::com::sun::star::uno::XInterface
  48 {
  49     /** Return the position of the caret.
  50
  51         <p>Returns the offset of the caret.  The caret is often called text
  52         cursor.  The caret is actually the position between two characters.
  53         Its position/offset is that of the character to the right of it.</p>
  54
  55         @return
  56             The returned offset is relative to the text represented by this
  57             object.
  58     */
  59     long getCaretPosition ();
  60
  61     /** Set the position of the caret.
  62
  63         <p>The caret is often called text cursor.  The caret is actually the
  64         position between two characters.  Its position/offset is that of the
  65         character to the right of it.</p>
  66
  67         <p>Setting the caret position may or may not alter the current
  68         selection.  A change of the selection is notified to the
  69         accessibility event listeners with an
  70         AccessibleEventId::ACCESSIBLE_SELECTION_EVENT.</p>
  71
  72         <p>When the new caret position differs from the old one (which, of
  73         course, is the standard case) this is notified to the accessibility
  74         event listeners with an
  75         AccessibleEventId::ACCESSIBLE_CARET_EVENT.</p>
  76
  77         @param nIndex
  78             The new index of the caret.  This caret is actually placed to
  79             the left side of the character with that index.  An index of 0
  80             places the caret so that the next insertion goes before the
  81             first character.  An index of getCharacterCount()
  82             leads to insertion after the last character.
  83
  84         @return
  85             Returns `TRUE` if the caret has been moved and `FALSE`
  86             otherwise.  A `TRUE` value does not necessarily mean that the
  87             caret has been positioned exactly at the required position.
  88             If that position lies inside a read-only area the caret is
  89             positioned before or behind it.  Listen to the caret event to
  90             determine the new position.
  91
  92         @throws ::com::sun::star::lang::IndexOutOfBoundsException
  93             if the index is not valid.
  94     */
  95     boolean setCaretPosition ([in] long nIndex)
  96         raises (::com::sun::star::lang::IndexOutOfBoundsException);
  97
  98     /** Return the character at the specified position.
  99
 100         <p>Returns the character at the given index.</p>
 101
 102         @param nIndex
 103             The index of the character to return.
 104             The valid range is 0..length-1.
 105
 106         @return
 107             the character at the index nIndex.
 108
 109         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 110             if the index is invalid
 111     */
 112     char getCharacter ([in] long nIndex)
 113         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 114
 115     /** Get the attribute set for the specified position.
 116
 117         <p>Returns a set of attributes that are associated for the character
 118         at the given index.  To prevent the method from returning possibly
 119         large sets of attributes that the caller is not interested in the
 120         caller has to provide a list of attributes that he wants to be
 121         returned.</p>
 122
 123         @param nIndex
 124             The index of the character for which to return its attributes.
 125             The valid range is 0..length-1.
 126
 127         @param aRequestedAttributes
 128             This string sequence defines the set of attributes that the
 129             caller is interested in.  When there are attributes defined that
 130             are not listed in the sequence then they are not returned.  When
 131             there are requested attributes that are not defined for the
 132             character then they are ignored, too.
 133
 134             <p>An empty sequence signals the callers interest in all the
 135             attributes.  This is useful in two cases: a) Simply as a way to
 136             avoid passing a potentially large array to the called object or
 137             b) when the caller does not know what attributes the called
 138             objects supports but is interested in all of them
 139             nevertheless.</p>
 140
 141         @return
 142             Returns the explicitly or implicitly (empty
 143             aRequestedAttributes argument) requested attributes
 144             of the specified character.  Each attribute is represented by a
 145             ::com::sun::star::beans::PropertyValue
 146             object.  The returned list of attribute descriptions contains
 147             all attributes that are both members of the sequence of
 148             requested attributes and are defined for the character at the
 149             specified index.
 150
 151         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 152             if the index is invalid
 153
 154         @see CharacterProperties
 155     */
 156     sequence<::com::sun::star::beans::PropertyValue>
 157         getCharacterAttributes (
 158             [in] long nIndex,
 159             [in] sequence<string> aRequestedAttributes)
 160         raises (::com::sun::star::lang::IndexOutOfBoundsException,
 161                 ::com::sun::star::beans::UnknownPropertyException);
 162
 163
 164     /** Return the bounding box of the specified position.
 165
 166         <p>Returns the bounding box of the indexed character.</p>
 167
 168         <p>The virtual character after the last character of the represented
 169         text, i.e. the one at position length is a special case. It
 170         represents the current input position and will therefore typically
 171         be queried by AT more often than other positions.  Because it does
 172         not represent an existing character its bounding box is defined in
 173         relation to preceding characters.  It should be roughly equivalent to
 174         the bounding box of some character when inserted at the end of the
 175         text.  Its height typically being the maximal height of all the
 176         characters in the text or the height of the preceding character, its
 177         width being at least one pixel so that the bounding box is not
 178         degenerate.<br>
 179         Note that the index "length" is not always valid.  Whether it is
 180         or not is implementation dependent.  It typically is when text is
 181         editable or otherwise when on the screen the caret can be placed
 182         behind the text.  You can be sure that the index is valid after you
 183         have received an AccessibleEventId::CARET event
 184         for this index.</p>
 185         @param nIndex
 186             Index of the character for which to return its bounding box.
 187             The valid range is 0..length.
 188
 189         @return
 190             The bounding box of the referenced character.  The bounding box
 191             of the virtual character at position length has to have
 192             non-empty dimensions.
 193
 194         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 195             if the index is invalid
 196     */
 197     ::com::sun::star::awt::Rectangle getCharacterBounds ([in] long nIndex)
 198         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 199
 200
 201     /** Return the number of characters in the represented text.
 202
 203         <p>Returns the number of characters in the text represented by this
 204         object or, in other words, the text length.</p>
 205
 206         @return
 207             Returns the number of characters of this object's text.  A zero
 208             value indicates an empty text.
 209     */
 210     long getCharacterCount ();
 211
 212
 213     /** Return the text position for the specified screen position.
 214
 215         <p>Given a point in local coordinates, i.e. relative to the
 216         coordinate system of the object, return the zero-based index of
 217         the character under that point.  The same functionality could be
 218         achieved by using the bounding boxes for each character as returned
 219         by XAccessibleText::getCharacterBounds(). The method
 220         XAccessibleText::getIndexAtPoint(), however, can be
 221         implemented in a more efficient way.</p>
 222
 223         @param aPoint
 224             The position for which to look up the index of the character
 225             that is rendered on to the display at that point.
 226
 227         @return
 228             Index of the character under the given point or -1 if the point
 229             is invalid or there is no character under the point.
 230     */
 231     long getIndexAtPoint ([in] ::com::sun::star::awt::Point aPoint);
 232
 233     /** Return the selected text.
 234
 235         <p>Returns the portion of the text that is selected.</p>
 236
 237         @return
 238             The returned text is the selected portion of the object's text.
 239             If no text is selected when this method is called or when
 240             selection is not supported an empty string is returned.
 241     */
 242     string getSelectedText ();
 243
 244     /** Return the position of the start of the selection.
 245
 246         <p>Returns the index of the start of the selected text.</p>
 247
 248         @return
 249             If there is no selection or selection is not supported the
 250             position of selection start and end will be the same undefined
 251             value.
 252     */
 253     long getSelectionStart ();
 254
 255     /** Return the position of the end of the selection.
 256
 257         <p>Returns the index of the end of the selected text.</p>
 258
 259         @return
 260             If there is no selection or selection is not supported the
 261             position of selection start and end will be the same undefined
 262             value.
 263     */
 264     long getSelectionEnd ();
 265
 266     /** Set a new selection.
 267
 268         <p>Sets the selected text portion according to the given indices.
 269         The old selection is replaced by the new selection.</p>
 270
 271         <p>The selection encompasses the same string of text that
 272         XAccessibleText::getTextRange() would have
 273         selected. See there for details.</p>
 274
 275         <p>Setting the selection may or may not change the caret position.
 276         Typically the caret is moved to the position after the second
 277         argument.  When the caret is moved this is notified to the
 278         accessibility event listeners with an
 279         AccessibleEventId::ACCESSIBLE_CARET_EVENT.</p>
 280
 281         @param nStartIndex
 282             The first character of the new selection.
 283             The valid range is 0..length.
 284
 285         @param nEndIndex
 286             The position after the last character of the new selection.
 287             The valid range is 0..length.
 288
 289         @return
 290             Returns `TRUE` if the selection has been set successfully and
 291             `FALSE` otherwise or when selection is not supported.
 292
 293         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 294             if the indices are invalid
 295     */
 296     boolean setSelection ([in] long nStartIndex, [in] long nEndIndex)
 297         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 298
 299     /** Return the whole text.
 300
 301         <p>Returns the complete text.  This is equivalent to a call to
 302         XAccessibleText::getTextRange() with the arguments
 303         zero and <code>getCharacterCount()-1</code>.</p>
 304
 305         @return
 306             Returns a string that contains the complete text.
 307     */
 308     string getText ();
 309
 310     /** Return the specified text range.
 311
 312         <p>Returns the substring between the two given indices.</p>
 313
 314         <p>The substring starts with the character at nStartIndex
 315         (inclusive) and up to the character at nEndIndex (exclusive),
 316         if nStartIndex is less or equal nEndIndex.  If nEndIndex is
 317         lower than nStartIndex, the result is the same as a call with
 318         the two arguments being exchanged.</p>
 319
 320         <p>The whole text can be requested by passing the indices zero and
 321         <code>getCharacterCount()</code>.  If both indices have the same
 322         value, an empty string is returned.</p>
 323
 324         @param nStartIndex
 325             Index of the first character to include in the returned string.
 326             The valid range is 0..length.
 327
 328         @param nEndIndex
 329             Index of the last character to exclude in the returned string.
 330             The valid range is 0..length.
 331
 332         @return
 333             Returns the substring starting with the character at nStartIndex
 334             (inclusive) and up to the character at nEndIndex (exclusive), if
 335             nStartIndex is less than or equal to nEndIndex.
 336
 337         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 338             if the indices are invalid
 339     */
 340     string getTextRange ([in] long nStartIndex, [in] long nEndIndex)
 341         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 342
 343     /** Get a text portion around the given position.
 344
 345         <p>Returns the substring of the specified text type that contains
 346         the character at the given index, if any.  For example, given the
 347         text type AccessibleTextType::WORD, the word
 348         which contains the character at position nIndex is returned, or an
 349         empty string if no word is found at the that position.</p>
 350
 351         @param nIndex
 352             Index of the character whose containing text portion is to be
 353             returned.
 354             The valid range is 0..length.
 355
 356         @param nTextType
 357             The type of the text portion to return.  See
 358             AccessibleTextType for the complete list.
 359
 360         @return
 361             Returns the requested text portion.  This portion may be empty
 362             or invalid when no appropriate text portion is found or text
 363             type is invalid.
 364
 365         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 366             if the index is invalid
 367         @throws ::com::sun::star::lang::IllegalArgumentException
 368             if the given text type is not valid.
 369     */
 370     TextSegment getTextAtIndex([in] long nIndex, [in] short nTextType)
 371         raises (::com::sun::star::lang::IndexOutOfBoundsException,
 372             ::com::sun::star::lang::IllegalArgumentException);
 373
 374     /** Get a text portion before the given position.
 375
 376         <p>Returns the substring of the specified text type that is
 377         located before the given character and does not include
 378         it. The result of this method should be same as a result for
 379         XAccessibleText::getTextAtIndex() with a
 380         suitably decreased index value.</p>
 381
 382         <p>For example, if text type is
 383         AccessibleTextType::WORD, then the complete word
 384         that is closest to and located before nIndex is returned.</p>
 385
 386         <p>If the index is valid, but no suitable word (or other text
 387         type) is found, an empty text segment is returned.</p>
 388
 389         @param nIndex
 390             Index of the character for which to return the text part before
 391             it.  The index character will not be part of the returned
 392             string.
 393             The valid range is 0..length.
 394
 395         @param nTextType
 396             The type of the text portion to return.  See
 397             AccessibleTextType for the complete list.
 398
 399         @return
 400             Returns the requested text portion.  This portion may be empty
 401             or invalid when no appropriate text portion is found or text
 402             type is invalid.
 403
 404         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 405             if the index is invalid.
 406         @throws ::com::sun::star::lang::IllegalArgumentException
 407             if the given text type is not valid.
 408     */
 409     TextSegment getTextBeforeIndex([in] long nIndex, [in] short nTextType)
 410         raises (::com::sun::star::lang::IndexOutOfBoundsException,
 411             ::com::sun::star::lang::IllegalArgumentException);
 412
 413     /** Get a text portion behind the given position.
 414
 415         <p>Returns the substring of the specified text type that is
 416         located after the given character and does not include
 417         it. The result of this method should be same as a result for
 418         XAccessibleText::getTextAtIndex() with a
 419         suitably increased index value.</p>
 420
 421         <p>For example, if text type is
 422         AccessibleTextType::WORD, then the complete word
 423         that is closest to and located behind nIndex is returned.</p>
 424
 425         <p>If the index is valid, but no suitable word (or other text
 426         type) is found, an empty string is returned.</p>
 427
 428         @param nIndex
 429             Index of the character for which to return the text part after
 430             it.  The index character will not be part of the returned string.
 431             The valid range is 0..length.
 432
 433         @param nTextType
 434             The type of the text portion to return.  See
 435             AccessibleTextType for the complete list.
 436
 437         @return
 438             Returns the requested text portion.  This portion may be empty
 439             or invalid when no appropriate text portion is found or text
 440             type is invalid.
 441
 442         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 443             if the index is invalid
 444         @throws ::com::sun::star::lang::IllegalArgumentException
 445             if the given text type is not valid.
 446     */
 447     TextSegment getTextBehindIndex([in] long nIndex, [in] short nTextType)
 448         raises (::com::sun::star::lang::IndexOutOfBoundsException,
 449             ::com::sun::star::lang::IllegalArgumentException);
 450
 451     /** Copy the specified text into the clipboard.
 452
 453         <p>Copy the specified text into the clipboard.  The text that is
 454         copied is the same text that would have been selected by the
 455         XAccessibleText::getTextRange() method. </p>
 456
 457         <p>The other clipboard related methods
 458         XAccessibleEditableText::cutText() and
 459         XAccessibleEditableText::deleteText() can be found in
 460         the XAccessibleEditableText because of their
 461         destructive nature.</p>
 462
 463         @param nStartIndex
 464             Start index of the text to copied into the clipboard.
 465             The valid range is 0..length.
 466
 467         @param nEndIndex
 468             End index of the text to copied into the clipboard.
 469             The valid range is 0..length.
 470
 471         @return
 472             Returns `TRUE` if the specified text has been copied
 473             successfully into the clipboard.
 474
 475         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 476             if the indices are invalid
 477     */
 478     boolean copyText ([in] long nStartIndex, [in] long nEndIndex)
 479         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 480
 481     /** Scroll the specified text to make it visible on screen.
 482
 483         @param nStartIndex
 484             Start index of the text to scroll.
 485             The valid range is 0..length.
 486
 487         @param nEndIndex
 488             End index of the text to scroll.
 489             The valid range is nStartIndex..length.
 490
 491         @param aScrollType
 492             Type of scroll to perform.  See AccessibleScrollType for the
 493             complete list.
 494
 495         @return
 496             Returns `TRUE` if the specified text has been scrolled
 497             successfully.
 498
 499         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 500             if the indices are invalid
 501
 502         @since LibreOffice 7.0
 503     */
 504     boolean
 505         scrollSubstringTo ([in] long nStartIndex, [in] long nEndIndex,
 506             [in] AccessibleScrollType aScrollType)
 507         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 508 };
 509
 510 }; }; }; };
 511
 512 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */