summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/accessibility/XAccessibleText.idl
blob: 98af06445733b4d26c79515822b600def6336774 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
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: */