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