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 useful 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 roughly 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        @param 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