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

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