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

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