diff options
Diffstat (limited to 'offapi/com/sun/star/accessibility/XAccessibleText.idl')
| -rw-r--r-- | offapi/com/sun/star/accessibility/XAccessibleText.idl | 527 |
1 files changed, 527 insertions, 0 deletions
diff --git a/offapi/com/sun/star/accessibility/XAccessibleText.idl b/offapi/com/sun/star/accessibility/XAccessibleText.idl new file mode 100644 index 000000000..98af06445 --- /dev/null +++ b/offapi/com/sun/star/accessibility/XAccessibleText.idl @@ -0,0 +1,527 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ + +#ifndef __com_sun_star_accessibility_XAccessibleText_idl__ +#define __com_sun_star_accessibility_XAccessibleText_idl__ + +#include <com/sun/star/accessibility/AccessibleTextType.idl> +#include <com/sun/star/uno/XInterface.idl> +#include <com/sun/star/awt/Point.idl> +#include <com/sun/star/awt/Rectangle.idl> +#include <com/sun/star/lang/IndexOutOfBoundsException.idl> +#include <com/sun/star/lang/IllegalArgumentException.idl> +#include <com/sun/star/beans/PropertyValue.idl> +#include <com/sun/star/beans/UnknownPropertyException.idl> +#include <com/sun/star/accessibility/TextSegment.idl> + +module com { module sun { module star { module accessibility { + +/** Implement this interface to give read-only access to a text. + + <p>The XAccessibleText interface should be implemented by + all UNO components that present textual information on the display like + buttons, text entry fields, or text portions of the document window. + The interface provides access to the text's content, attributes, and + spatial location. However, text can not be modified with this + interface. That is the task of the XAccessibleEditableText + interface.</p> + + <p>The text length, i.e. the number of characters in the text, is + returned by XAccessibleText::getCharacterCount(). + All methods that operate on particular characters (e.g. + XAccessibleText::getCharacterAt()) use character + indices from 0 to length-1. All methods that operate on character + positions (e.g. XAccessibleText::getTextRange()) + use indices from 0 to length.</p> + + <p>Please note that accessible text does not necessarily support + selection. In this case it should behave as if there where no + selection. An empty selection is used for example to express the + current cursor position.</p> + + @since OOo 1.1.2 +*/ +interface XAccessibleText : ::com::sun::star::uno::XInterface +{ + /** Return the position of the caret. + + <p>Returns the offset of the caret. The caret is often called text + cursor. The caret is actually the position between two characters. + Its position/offset is that of the character to the right of it.</p> + + @return + The returned offset is relative to the text represented by this + object. + */ + long getCaretPosition (); + + /** Set the position of the caret. + + <p>The caret is often called text cursor. The caret is actually the + position between two characters. Its position/offset is that of the + character to the right of it.</p> + + <p>Setting the caret position may or may not alter the current + selection. A change of the selection is notified to the + accessibility event listeners with an + AccessibleEventId::ACCESSIBLE_SELECTION_EVENT.</p> + + <p>When the new caret position differs from the old one (which, of + course, is the standard case) this is notified to the accessibility + event listeners with an + AccessibleEventId::ACCESSIBLE_CARET_EVENT.</p> + + @param nIndex + The new index of the caret. This caret is actually placed to + the left side of the character with that index. An index of 0 + places the caret so that the next insertion goes before the + first character. An index of getCharacterCount() + leads to insertion after the last character. + + @return + Returns `TRUE` if the caret has been moved and `FALSE` + otherwise. A `TRUE` value does not necessarily mean that the + caret has been positioned exactly at the required position. + If that position lies inside a read-only area the caret is + positioned before or behind it. Listen to the caret event to + determine the new position. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the index is not valid. + */ + boolean setCaretPosition ([in] long nIndex) + raises (::com::sun::star::lang::IndexOutOfBoundsException); + + /** Return the character at the specified position. + + <p>Returns the character at the given index.</p> + + @param nIndex + The index of the character to return. + The valid range is 0..length-1. + + @return + the character at the index nIndex. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the index is invalid + */ + char getCharacter ([in] long nIndex) + raises (::com::sun::star::lang::IndexOutOfBoundsException); + + /** Get the attribute set for the specified position. + + <p>Returns a set of attributes that are associated for the character + at the given index. To prevent the method from returning possibly + large sets of attributes that the caller is not interested in the + caller has to provide a list of attributes that he wants to be + returned.</p> + + @param nIndex + The index of the character for which to return its attributes. + The valid range is 0..length-1. + + @param aRequestedAttributes + This string sequence defines the set of attributes that the + caller is interested in. When there are attributes defined that + are not listed in the sequence then they are not returned. When + there are requested attributes that are not defined for the + character then they are ignored, too. + + <p>An empty sequence signals the callers interest in all the + attributes. This is useful in two cases: a) Simply as a way to + avoid passing a potentially large array to the called object or + b) when the caller does not know what attributes the called + objects supports but is interested in all of them + nevertheless.</p> + + @return + Returns the explicitly or implicitly (empty + aRequestedAttributes argument) requested attributes + of the specified character. Each attribute is represented by a + ::com::sun::star::beans::PropertyValue + object. The returned list of attribute descriptions contains + all attributes that are both members of the sequence of + requested attributes and are defined for the character at the + specified index. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the index is invalid + + @see CharacterProperties + */ + sequence<::com::sun::star::beans::PropertyValue> + getCharacterAttributes ( + [in] long nIndex, + [in] sequence<string> aRequestedAttributes) + raises (::com::sun::star::lang::IndexOutOfBoundsException, + ::com::sun::star::beans::UnknownPropertyException); + + + /** Return the bounding box of the specified position. + + <p>Returns the bounding box of the indexed character.</p> + + <p>The virtual character after the last character of the represented + text, i.e. the one at position length is a special case. It + represents the current input position and will therefore typically + be queried by AT more often than other positions. Because it does + not represent an existing character its bounding box is defined in + relation to preceding characters. It should be roughly equivalent to + the bounding box of some character when inserted at the end of the + text. Its height typically being the maximal height of all the + characters in the text or the height of the preceding character, its + width being at least one pixel so that the bounding box is not + degenerate.<br> + Note that the index "length" is not always valid. Whether it is + or not is implementation dependent. It typically is when text is + editable or otherwise when on the screen the caret can be placed + behind the text. You can be sure that the index is valid after you + have received an AccessibleEventId::CARET event + for this index.</p> + @param nIndex + Index of the character for which to return its bounding box. + The valid range is 0..length. + + @return + The bounding box of the referenced character. The bounding box + of the virtual character at position length has to have + non-empty dimensions. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the index is invalid + */ + ::com::sun::star::awt::Rectangle getCharacterBounds ([in] long nIndex) + raises (::com::sun::star::lang::IndexOutOfBoundsException); + + + /** Return the number of characters in the represented text. + + <p>Returns the number of characters in the text represented by this + object or, in other words, the text length.</p> + + @return + Returns the number of characters of this object's text. A zero + value indicates an empty text. + */ + long getCharacterCount (); + + + /** Return the text position for the specified screen position. + + <p>Given a point in local coordinates, i.e. relative to the + coordinate system of the object, return the zero-based index of + the character under that point. The same functionality could be + achieved by using the bounding boxes for each character as returned + by XAccessibleText::getCharacterBounds(). The method + XAccessibleText::getIndexAtPoint(), however, can be + implemented in a more efficient way.</p> + + @param aPoint + The position for which to look up the index of the character + that is rendered on to the display at that point. + + @return + Index of the character under the given point or -1 if the point + is invalid or there is no character under the point. + */ + long getIndexAtPoint ([in] ::com::sun::star::awt::Point aPoint); + + /** Return the selected text. + + <p>Returns the portion of the text that is selected.</p> + + @return + The returned text is the selected portion of the object's text. + If no text is selected when this method is called or when + selection is not supported an empty string is returned. + */ + string getSelectedText (); + + /** Return the position of the start of the selection. + + <p>Returns the index of the start of the selected text.</p> + + @return + If there is no selection or selection is not supported the + position of selection start and end will be the same undefined + value. + */ + long getSelectionStart (); + + /** Return the position of the end of the selection. + + <p>Returns the index of the end of the selected text.</p> + + @return + If there is no selection or selection is not supported the + position of selection start and end will be the same undefined + value. + */ + long getSelectionEnd (); + + /** Set a new selection. + + <p>Sets the selected text portion according to the given indices. + The old selection is replaced by the new selection.</p> + + <p>The selection encompasses the same string of text that + XAccessibleText::getTextRange() would have + selected. See there for details.</p> + + <p>Setting the selection may or may not change the caret position. + Typically the caret is moved to the position after the second + argument. When the caret is moved this is notified to the + accessibility event listeners with an + AccessibleEventId::ACCESSIBLE_CARET_EVENT.</p> + + @param nStartIndex + The first character of the new selection. + The valid range is 0..length. + + @param nEndIndex + The position after the last character of the new selection. + The valid range is 0..length. + + @return + Returns `TRUE` if the selection has been set successfully and + `FALSE` otherwise or when selection is not supported. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the indices are invalid + */ + boolean setSelection ([in] long nStartIndex, [in] long nEndIndex) + raises (::com::sun::star::lang::IndexOutOfBoundsException); + + /** Return the whole text. + + <p>Returns the complete text. This is equivalent to a call to + XAccessibleText::getTextRange() with the arguments + zero and <code>getCharacterCount()-1</code>.</p> + + @return + Returns a string that contains the complete text. + */ + string getText (); + + /** Return the specified text range. + + <p>Returns the substring between the two given indices.</p> + + <p>The substring starts with the character at nStartIndex + (inclusive) and up to the character at nEndIndex (exclusive), + if nStartIndex is less or equal nEndIndex. If nEndIndex is + lower than nStartIndex, the result is the same as a call with + the two arguments being exchanged.</p> + + <p>The whole text can be requested by passing the indices zero and + <code>getCharacterCount()</code>. If both indices have the same + value, an empty string is returned.</p> + + @param nStartIndex + Index of the first character to include in the returned string. + The valid range is 0..length. + + @param nEndIndex + Index of the last character to exclude in the returned string. + The valid range is 0..length. + + @return + Returns the substring starting with the character at nStartIndex + (inclusive) and up to the character at nEndIndex (exclusive), if + nStartIndex is less than or equal to nEndIndex. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the indices are invalid + */ + string getTextRange ([in] long nStartIndex, [in] long nEndIndex) + raises (::com::sun::star::lang::IndexOutOfBoundsException); + + /** Get a text portion around the given position. + + <p>Returns the substring of the specified text type that contains + the character at the given index, if any. For example, given the + text type AccessibleTextType::WORD, the word + which contains the character at position nIndex is returned, or an + empty string if no word is found at the that position.</p> + + @param nIndex + Index of the character whose containing text portion is to be + returned. + The valid range is 0..length. + + @param nTextType + The type of the text portion to return. See + AccessibleTextType for the complete list. + + @return + Returns the requested text portion. This portion may be empty + or invalid when no appropriate text portion is found or text + type is invalid. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the index is invalid + @throws ::com::sun::star::lang::IllegalArgumentException + if the given text type is not valid. + */ + TextSegment getTextAtIndex([in] long nIndex, [in] short nTextType) + raises (::com::sun::star::lang::IndexOutOfBoundsException, + ::com::sun::star::lang::IllegalArgumentException); + + /** Get a text portion before the given position. + + <p>Returns the substring of the specified text type that is + located before the given character and does not include + it. The result of this method should be same as a result for + XAccessibleText::getTextAtIndex() with a + suitably decreased index value.</p> + + <p>For example, if text type is + AccessibleTextType::WORD, then the complete word + that is closest to and located before nIndex is returned.</p> + + <p>If the index is valid, but no suitable word (or other text + type) is found, an empty text segment is returned.</p> + + @param nIndex + Index of the character for which to return the text part before + it. The index character will not be part of the returned + string. + The valid range is 0..length. + + @param nTextType + The type of the text portion to return. See + AccessibleTextType for the complete list. + + @return + Returns the requested text portion. This portion may be empty + or invalid when no appropriate text portion is found or text + type is invalid. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the index is invalid. + @throws ::com::sun::star::lang::IllegalArgumentException + if the given text type is not valid. + */ + TextSegment getTextBeforeIndex([in] long nIndex, [in] short nTextType) + raises (::com::sun::star::lang::IndexOutOfBoundsException, + ::com::sun::star::lang::IllegalArgumentException); + + /** Get a text portion behind the given position. + + <p>Returns the substring of the specified text type that is + located after the given character and does not include + it. The result of this method should be same as a result for + XAccessibleText::getTextAtIndex() with a + suitably increased index value.</p> + + <p>For example, if text type is + AccessibleTextType::WORD, then the complete word + that is closest to and located behind nIndex is returned.</p> + + <p>If the index is valid, but no suitable word (or other text + type) is found, an empty string is returned.</p> + + @param nIndex + Index of the character for which to return the text part after + it. The index character will be part of the returned string. + The valid range is 0..length. + + @param nTextType + The type of the text portion to return. See + AccessibleTextType for the complete list. + + @return + Returns the requested text portion. This portion may be empty + or invalid when no appropriate text portion is found or text + type is invalid. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the index is invalid + @throws ::com::sun::star::lang::IllegalArgumentException + if the given text type is not valid. + */ + TextSegment getTextBehindIndex([in] long nIndex, [in] short nTextType) + raises (::com::sun::star::lang::IndexOutOfBoundsException, + ::com::sun::star::lang::IllegalArgumentException); + + /** Copy the specified text into the clipboard. + + <p>Copy the specified text into the clipboard. The text that is + copied is the same text that would have been selected by the + XAccessibleText::getTextRange() method. </p> + + <p>The other clipboard related methods + XAccessibleEditableText::cutText() and + XAccessibleEditableText::deleteText() can be found in + the XAccessibleEditableText because of their + destructive nature.</p> + + @param nStartIndex + Start index of the text to copied into the clipboard. + The valid range is 0..length. + + @param nEndIndex + End index of the text to copied into the clipboard. + The valid range is 0..length. + + @return + Returns `TRUE` if the specified text has been copied + successfully into the clipboard. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the indices are invalid + */ + boolean copyText ([in] long nStartIndex, [in] long nEndIndex) + raises (::com::sun::star::lang::IndexOutOfBoundsException); + + /** Scroll the specified text to make it visible on screen. + + @param nStartIndex + Start index of the text to scroll. + The valid range is 0..length. + + @param nEndIndex + End index of the text to scroll. + The valid range is nStartIndex..length. + + @param aScrollType + Type of scroll to perform. See AccessibleScrollType for the + complete list. + + @return + Returns `TRUE` if the specified text has been scrolled + successfully. + + @throws ::com::sun::star::lang::IndexOutOfBoundsException + if the indices are invalid + + @since LibreOffice 7.0 + */ + boolean + scrollSubstringTo ([in] long nStartIndex, [in] long nEndIndex, + [in] AccessibleScrollType aScrollType) + raises (::com::sun::star::lang::IndexOutOfBoundsException); +}; + +}; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |