diff options
Diffstat (limited to 'offapi/com/sun/star/accessibility/XAccessibleText.idl')
-rw-r--r-- | offapi/com/sun/star/accessibility/XAccessibleText.idl | 519 |
1 files changed, 519 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 000000000000..7b1cf40ae837 --- /dev/null +++ b/offapi/com/sun/star/accessibility/XAccessibleText.idl @@ -0,0 +1,519 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_accessibility_XAccessibleText_idl__ +#define __com_sun_star_accessibility_XAccessibleText_idl__ + +#ifndef __com_sun_star_accessibility_AccessibleTextType_idl__ +#include <com/sun/star/accessibility/AccessibleTextType.idl> +#endif + +#ifndef __com_sun_star_uno_XInterface_idl__ +#include <com/sun/star/uno/XInterface.idl> +#endif +#ifndef __com_sun_star_awt_Point_idl__ +#include <com/sun/star/awt/Point.idl> +#endif +#ifndef __com_sun_star_awt_Rectangle_idl__ +#include <com/sun/star/awt/Rectangle.idl> +#endif +#ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__ +#include <com/sun/star/lang/IndexOutOfBoundsException.idl> +#endif +#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ +#include <com/sun/star/lang/IllegalArgumentException.idl> +#endif +#ifndef __com_sun_star_beans_PropertyValue_idl__ +#include <com/sun/star/beans/PropertyValue.idl> +#endif +#ifndef __com_sun_star_accessibility_TextSegment_idl__ +#include <com/sun/star/accessibility/TextSegment.idl> +#endif + +module com { module sun { module star { module accessibility { + +/** Implement this interface to give read-only access to a text. + + <p>The <type>XAccessibleText</type> 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 <type>XAccessibleEditableText</type> + interface.</p> + + <p>The text length, i.e. the number of characters in the text, is + returned by <member>XAccessibleText::getCharacterCount</member>. + All methods that operate on particular characters (e.g. + <member>XAccessibleText::getCharacterAt</member>) use character + indices from 0 to length-1. All methods that operate on character + positions (e.g. <member>XAccessibleText::getTextRange</member>) + 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 +*/ +published 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 + <const>AccessibleEventId::ACCESSIBLE_SELECTION_EVENT</const>.</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 + <const>AccessibleEventId::ACCESSIBLE_CARET_EVENT</const>.</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 <member>getCharacterCount</member> + 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 usefull 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 + <arg>aRequestedAttributes</arg> argument) requested attributes + of the specified character. Each attribute is represented by a + <type scope="::com::sun::star::beans">PropertyValue</type> + 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 + */ + sequence<::com::sun::star::beans::PropertyValue> + getCharacterAttributes ( + [in] long nIndex, + [in] sequence<string> aRequestedAttributes) + raises (::com::sun::star::lang::IndexOutOfBoundsException); + + + /** 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 rougly 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 a <const scope="AccessibleEventId">CARET</const> 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 <member>XAccessibleText::getCharacterBounds</member>. The method + <member>XAccessibleText::getIndexAtPoint</member>, 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 + <member>XAccessibleText::getTextRange</member> 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 + <const>AccessibleEventId::ACCESSIBLE_CARET_EVENT</const>.</p> + + @param nStartIndex + The first character of the new selection. + The valid range is 0..length. + + @parm 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 + <member>XAccessibleText::getTextRange</member> 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 <const scope="AccessibleTextType">WORD</type>, 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 + <type>AccessibleTextType</type> 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::InvalidArgumentException + 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 + <member>XAccessibleText::getTextAtIndex</member> with a + suitably decreased index value.</p> + + <p>For example, if text type is <const + scope="AccessibleTextType">WORD</type>, 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 + <type>AccessibleTextType</type> 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::InvalidArgumentException + 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 + <member>XAccessibleText::getTextAtIndex</member> with a + suitably increased index value.</p> + + <p>For example, if text type is <const + scope="AccessibleTextType">WORD</type>, 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 + <type>AccessibleTextType</type> 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::InvalidArgumentException + 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 + <member>XAccessibleText::getTextRange</member> method. </p> + + <p>The other clipboard related methods + <member>XAccessibleEditableText::cutText</member> and + <member>XAccessibleEditableText::deleteText</member> can be found in + the <type>XAccessibleEditableText</type> 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); + +}; + +}; }; }; }; + +#endif |