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

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