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 57module 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*/ 84published 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 520