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

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