forked from amazingfate/loongoffice
499 lines
20 KiB
Plaintext
499 lines
20 KiB
Plaintext
/* -*- 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
|
|
*/
|
|
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 a 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);
|
|
|
|
};
|
|
|
|
}; }; }; };
|
|
|
|
#endif
|
|
|
|
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|