1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27
28#ifndef __com_sun_star_accessibility_XAccessibleMultiLineText_idl__
29#define __com_sun_star_accessibility_XAccessibleMultiLineText_idl__
30
31#ifndef __com_sun_star_accessibility_XAccessibleText_idl__
32#include <com/sun/star/accessibility/XAccessibleText.idl>
33#endif
34#ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
35#include <com/sun/star/lang/IndexOutOfBoundsException.idl>
36#endif
37#ifndef __com_sun_star_beans_PropertyValue_idl__
38#include <com/sun/star/beans/PropertyValue.idl>
39#endif
40
41module com { module sun { module star { module accessibility {
42
43/** Implement this interface to give provide a mapping between text index
44    and line numbers.
45
46    <p>This interface is typically used in conjunction with the
47    <type>XAccessibleText</type> interface and extents it with a notion
48    of line numbers</p>
49
50    @since OOo 3.0
51*/
52
53/// not yet published
54interface XAccessibleMultiLineText
55    : ::com::sun::star::accessibility::XAccessibleText
56{
57    /** Returns the line number at the specified index.
58
59        <p>For a text object that is spread over multiple lines, this method
60        provides a mapping from a text index to the corresponding line number.
61        </p>
62
63        @param nIndex
64            Index for which the line number should be returned.
65            The valid range is 0..length.
66
67        @return
68            Returns the line number of the specified text index.
69
70        @throws ::com::sun::star::lang::IndexOutOfBoundsException
71            if the index is invalid.
72    */
73    long getLineNumberAtIndex([in] long nIndex)
74        raises (::com::sun::star::lang::IndexOutOfBoundsException);
75
76    /** Retuns the text of the specified line.
77
78        <p>Returns the substring of text that makes up the specified line
79        number.</p>
80
81        <p>The number of lines can be obtained by calling
82        <member>XAccessibleMultiLineText::getLineNumberAtIndex</member>
83        with the index of the last character. In a loop, the last line
84        has been reached when <member>TextSegment::SegmentEnd</member>
85        of the returned value is equal to the index of the last
86        character of the text.</p>
87
88        @param nLineNo
89            The number of the line to return the substring from.
90            The valid range is 0..getLineNumberAtIndex(getCharacterCount()).
91
92        @return
93            Returns the requested text portion.  This portion may be empty
94            or invalid when no appropriate text portion is found.
95
96        @throws ::com::sun::star::lang::IndexOutOfBoundsException
97            if the line number is invalid
98    */
99
100    TextSegment getTextAtLineNumber([in] long nLineNo)
101        raises (::com::sun::star::lang::IndexOutOfBoundsException);
102
103    /** Returns the text of the line in which the caret is located.
104
105        <p>The substring returned will most of the time be identical to
106        calling <member>XAccessibleText::getTextAtIndex</member> with
107        the index returned by <member>XAccessibleText::getCaretPosition</member>
108        and type  <const scope="AccessibleTextType">LINE</type> beside the
109        following special case:</p>
110
111        <p>Some text implementations place the caret at the end of the current
112        line when the <b>End</b> key gets pressed. Since the index of this position
113        is identical to the one of the first character of the following line,
114        <member>XAccessibleMultiLineText::getLineNumberAtIndex</member> will
115        return the line following the current one in this case.</p>
116
117        @return
118            Returns the requested text portion. This portion may be empty
119            or invalid if the paragraph object does not have a valid caret
120            position.
121    */
122
123    TextSegment getTextAtLineWithCaret();
124
125    /** Returns the number of the line in which the caret is located.
126
127        <p>The line number returned will most of the time be identical to
128        calling <member>XAccessibleMultiLineText::getLineNumberAtIndex</member>
129        with the index returned by <member>XAccessibleText::getCaretPosition</member>
130        beside the following special case:</p>
131
132        <p>Some text implementations place the caret at the end of the current
133        line when the <b>End</b> key gets pressed. Since the index of this position
134        is identical to the one of the first character of the following line,
135        <member>XAccessibleMultiLineText::getLineNumberAtIndex</member> will
136        return the line following the current one in this case.</p>
137
138        @return
139            Returns the index of the line in which the caret is located or -1
140            if the paragraph does not have a valid caret position.
141    */
142
143    long getNumberOfLineWithCaret();
144};
145
146}; }; }; };
147
148#endif
149