offapi/com/sun/star/i18n/XBreakIterator.idl

   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
  52 module 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
  63 published 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