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