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#ifndef __com_sun_star_i18n_XBreakIterator_idl__
28#define __com_sun_star_i18n_XBreakIterator_idl__
29
30#ifndef __com_sun_star_lang_Locale_idl__
31#include <com/sun/star/lang/Locale.idl>
32#endif
33
34#ifndef __com_sun_star_i18n_LineBreakUserOptions_idl__
35#include <com/sun/star/i18n/LineBreakUserOptions.idl>
36#endif
37
38#ifndef __com_sun_star_i18n_LineBreakHyphenationOptions_idl__
39#include <com/sun/star/i18n/LineBreakHyphenationOptions.idl>
40#endif
41
42#ifndef __com_sun_star_i18n_LineBreakResults_idl__
43#include <com/sun/star/i18n/LineBreakResults.idl>
44#endif
45
46#ifndef __com_sun_star_i18n_Boundary_idl__
47#include <com/sun/star/i18n/Boundary.idl>
48#endif
49
50//============================================================================
51
52module com {  module sun {  module star {  module i18n {
53
54//============================================================================
55
56/**
57    contains the base routines for iteration in Unicode string. Iterates over
58    characters, words, sentences and line breaks.
59
60    <p> Assumption: StartPos is inclusive and EndPos is exclusive. </p>
61 */
62
63published interface XBreakIterator: com::sun::star::uno::XInterface
64{
65    //------------------------------------------------------------------------
66    /** Traverses specified number of characters/cells in Text from
67        <em>nStartPos</em> forwards.
68        <type>CharacterIteratorMode</type> can be cell based or
69        character based. A cell is made of more than one character.
70
71        @param nCount
72            Number of characters to traverse, it should not be less than 0.
73            If you want to traverse in the opposite direction use
74            <member>XBreakIterator::previousCharacters()</member> instead.
75     */
76    long nextCharacters( [in] string aText, [in] long nStartPos,
77                     [in] ::com::sun::star::lang::Locale aLocale,
78                     [in] short nCharacterIteratorMode,
79                     [in] long nCount, [out] long nDone );
80
81    //------------------------------------------------------------------------
82    /** Traverses specified number of characters/cells in Text from
83        <em>nStartPos</em> backwards.
84        <type>CharacterIteratorMode</type> can be cell based or
85        character based. A cell is made of more than one character.
86
87        @param nCount
88            Number of characters to traverse, it should not be less than 0.
89            If you want to traverse in the opposite direction use
90            <member>XBreakIterator::nextCharacters()</member> instead.
91     */
92    long previousCharacters( [in] string aText, [in] long nStartPos,
93                     [in] ::com::sun::star::lang::Locale aLocale,
94                     [in] short nCharacterIteratorMode,
95                     [in] long nCount, [out] long nDone );
96
97    //------------------------------------------------------------------------
98    /** Traverses one word in Text from <em>nStartPos</em> forwards.
99
100        @param nWordType
101            One of <type>WordType</type>, specifies the type of
102            travelling.
103
104        @returns
105            The <type>Boundary</type> of the found word. Normally used for
106            CTRL-Right.
107     */
108    Boundary nextWord( [in] string aText, [in] long nStartPos,
109                   [in] ::com::sun::star::lang::Locale aLocale,
110                   [in] short nWordType);
111
112    //------------------------------------------------------------------------
113    /** Traverses one word in Text from <em>nStartPos</em> backwards.
114
115        @param aLocale
116            The locale of the character preceding <em>nStartPos</em>.
117
118            <p> If the previous character is a space character and
119            <em>nWordType</em> indicates spaces should be skipped, and
120            if the first non-space character is an Asian character,
121            then, since Asian word break needs language specific
122            wordbreak dictionaries, the method will return -1 in
123            <member>Boundary::endPos</member> and the position after the
124            Asian character (i.e. the space character) in
125            <member>Boundary::startPos</member>. The caller then has to
126            call this method again with a correct <em>aLocale</em>
127            referring to the Asian character, which is then the previous
128            character of the space character where <em>nStartPos</em>
129            points to. </p>
130
131            <p> <b>Note</b> that the OpenOffice.org 1.0 / StarOffice 6.0
132            / StarSuite 6.0 i18n framework doesn't behave like this and
133            mixed Western/CJK text may lead to wrong word iteration.
134            This is fixed in later versions. </p>
135
136        @param nWordType
137            One of <type>WordType</type>, specifies the type of
138            travelling.
139
140        @returns
141            The <type>Boundary</type> of the found word. Normally used for
142            CTRL-Left.
143    */
144    Boundary previousWord( [in] string aText, [in] long nStartPos,
145                       [in] ::com::sun::star::lang::Locale aLocale,
146                       [in] short nWordType);
147
148    //------------------------------------------------------------------------
149    /** Identifies StartPos and EndPos of current word.
150
151        <p> If <em>nPos</em> is the boundary of a word, it is StartPos
152        of one word and EndPos of previous word. In this situation, the
153        outcome of the algorithm can be indeterminate. In this situation
154        the <em>bPreferForward</em> flag is used. If bPreferForward ==
155        <FALSE/>, <em>nPos</em> is considered to be the end of the word
156        and we look backwards for beginning of word, otherwise
157        <em>nPos</em> is considered to be the start of the next word and
158        we look forwards for the end of the word. </p>
159
160        @param nWordType
161            One of <type>WordType</type>.
162
163        @returns
164            The Boundary of the current word.
165    */
166    Boundary getWordBoundary( [in] string aText, [in] long nPos,
167                      [in] ::com::sun::star::lang::Locale aLocale,
168                      [in] short nWordType,
169                      [in] boolean bPreferForward );
170
171    //------------------------------------------------------------------------
172    /** @deprecated
173        Get the <type>WordType</type> of the word that starts at
174        position <em>nPos</em>.
175
176        <p> This method is mis-defined, since <type>WordType</type>
177        is not an attribute of a word, but a way to break words,
178        like excluding or including tail spaces for spellchecker
179        or cursor traveling. It returns 0 always.
180        </p>
181     */
182    short getWordType( [in] string aText, [in] long nPos,
183                   [in] ::com::sun::star::lang::Locale aLocale);
184
185    //------------------------------------------------------------------------
186    /** If a word starts at position <em>nPos</em>.
187
188        <p> It is possible that both of this method
189        and following method <em>isEndWord</em> all return
190        <TRUE/>, since StartPos of a word is inclusive
191        while EndPos of a word is exclusive.
192        </p>
193
194     */
195    boolean isBeginWord( [in] string aText, [in] long nPos,
196                     [in] ::com::sun::star::lang::Locale aLocale,
197                     [in] short nWordType);
198
199    //------------------------------------------------------------------------
200    /** If a word ends at position <em>nPos</em>.
201     */
202    boolean isEndWord( [in] string aText, [in] long nPos,
203                   [in] ::com::sun::star::lang::Locale aLocale,
204                   [in] short nWordType);
205
206    //------------------------------------------------------------------------
207    /** Traverses in Text from <em>nStartPos</em> to the start of a
208        sentence.
209
210        @returns
211            The position where the sentence starts.
212     */
213    long beginOfSentence( [in] string aText, [in] long nStartPos,
214                      [in] ::com::sun::star::lang::Locale aLocale );
215
216    //------------------------------------------------------------------------
217    /** Traverses in Text from <em>nStartPos</em> to the end of a
218        sentence.
219
220        @returns
221            The position where the sentence ends.
222     */
223    long endOfSentence( [in] string aText, [in] long nStartPos,
224                    [in] ::com::sun::star::lang::Locale aLocale );
225
226    //------------------------------------------------------------------------
227    /** Calculate the line break position in the Text from the specified
228        <em>nStartPos</em>.
229
230        @param nMinBreakPos
231            Defines a minimum break position for hyphenated line break.
232            When the position for hyphenated line break is less than
233            <em>nMinBreakPos</em>, break position in
234            <type>LineBreakResults</type> is set to -1.
235
236        @param aHyphOptions
237            Defines if the hyphenator is to be used.
238
239        @param aUserOptions
240            Defines how to handle hanging punctuations and forbidden
241            characters at the start/end of a line.
242
243        @returns
244            The <type>LineBreakResults</type> contain the break
245            position of the line, <type>BreakType</type> and
246            <type scope="com::sun::star::linguistic2">XHyphenatedWord</type>
247     */
248    LineBreakResults getLineBreak( [in] string aText, [in] long nStartPos,
249                    [in] ::com::sun::star::lang::Locale aLocale,
250                    [in] long nMinBreakPos,
251                    [in] LineBreakHyphenationOptions aHyphOptions,
252                    [in] LineBreakUserOptions aUserOptions );
253
254    //------------------------------------------------------------------------
255    /** Traverses in Text from <em>nStartPos</em> to the beginning of
256        the specified script type.
257
258        @param nScriptType
259            One of <type>ScriptType</type>.
260
261        @returns
262            The position where the script type starts.
263     */
264    long beginOfScript( [in] string aText, [in] long nStartPos,
265                    [in] short nScriptType );
266
267    //------------------------------------------------------------------------
268    /** Traverses in Text from <em>nStartPos</em> to the end of the
269        specified script type.
270
271        @param nScriptType
272            One of <type>ScriptType</type>.
273
274        @returns
275            The position where the script type ends.
276     */
277    long endOfScript( [in] string aText, [in] long nStartPos,
278                  [in] short nScriptType );
279
280    //------------------------------------------------------------------------
281    /** Traverses in Text from <em>nStartPos</em> to the next start of
282        the specified script type.
283
284        @param nScriptType
285            One of <type>ScriptType</type>.
286
287        @returns
288            The position where the next script type starts.
289     */
290    long nextScript( [in] string aText, [in] long nStartPos,
291                 [in] short nScriptType );
292
293    //------------------------------------------------------------------------
294    /** Traverses in Text from <em>nStartPos</em> to the previous start
295        of the specified script type.
296
297        @param nScriptType
298            One of <type>ScriptType</type>.
299
300        @returns
301            The position where the previous script type starts.
302     */
303    long previousScript( [in] string aText, [in] long nStartPos,
304                      [in] short nScriptType );
305
306    //------------------------------------------------------------------------
307    /** Get the script type of the character at position <em>nPos</em>.
308
309        @returns
310            One of <type>ScriptType</type>.
311     */
312    short   getScriptType( [in] string aText, [in] long nPos);
313
314    //------------------------------------------------------------------------
315    /** Traverses in Text from <em>nStartPos</em> to the beginning of
316        the specified character type.
317
318        @param nCharType
319            One of <type>CharType</type>
320
321        @returns
322            The position where the character type starts
323     */
324    long beginOfCharBlock( [in] string aText, [in] long nStartPos,
325                       [in] ::com::sun::star::lang::Locale aLocale,
326                       [in] short nCharType );
327
328    //------------------------------------------------------------------------
329    /** Traverses in Text from <em>nStartPos</em> to the end of the
330        specified character type.
331
332        @param nCharType
333            One of <type>CharType</type>
334
335        @returns
336            The position where the character type ends.
337     */
338    long endOfCharBlock( [in] string aText, [in] long nStartPos,
339                     [in] ::com::sun::star::lang::Locale aLocale,
340                     [in] short nCharType );
341
342    //------------------------------------------------------------------------
343    /** Traverses in Text from <em>nStartPos</em> to the next start of
344        the specified character type.
345
346        @param nCharType
347            One of <type>CharType</type>
348
349        @returns
350            The position where the next character type starts.
351     */
352    long nextCharBlock( [in] string aText, [in] long nStartPos,
353                    [in] ::com::sun::star::lang::Locale aLocale,
354                    [in] short nCharType );
355
356    //------------------------------------------------------------------------
357    /** Traverses in Text from <em>nStartPos</em> to the previous start
358        of the specified character type.
359
360        @param nCharType
361            One of <type>CharType</type>
362
363        @returns
364            The position where the previous character type starts.
365     */
366    long previousCharBlock ( [in] string aText, [in] long nStartPos,
367                     [in] ::com::sun::star::lang::Locale aLocale,
368                     [in] short nCharType );
369};
370
371//============================================================================
372}; }; }; };
373
374#endif
375