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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_i18n_XBreakIterator_idl__
  20 #define __com_sun_star_i18n_XBreakIterator_idl__
  21
  22 #include <com/sun/star/lang/Locale.idl>
  23 #include <com/sun/star/i18n/LineBreakUserOptions.idl>
  24 #include <com/sun/star/i18n/LineBreakHyphenationOptions.idl>
  25 #include <com/sun/star/i18n/LineBreakResults.idl>
  26 #include <com/sun/star/i18n/Boundary.idl>
  27
  28
  29 module com {  module sun {  module star {  module i18n {
  30
  31
  32 /**
  33     contains the base routines for iteration in Unicode string. Iterates over
  34     characters, words, sentences and line breaks.
  35
  36     <p> Assumption: StartPos is inclusive and EndPos is exclusive. </p>
  37  */
  38
  39 published interface XBreakIterator: com::sun::star::uno::XInterface
  40 {
  41     /** Traverses specified number of characters/cells in Text from
  42         <em>nStartPos</em> forwards.
  43         CharacterIteratorMode can be cell based or
  44         character based. A cell is made of more than one character.
  45
  46         @param aText
  47             The input text.
  48
  49         @param nStartPos
  50             The start index in aText.
  51
  52         @param aLocale
  53             The locale of the character preceding <em>nStartPos</em>.
  54
  55         @param nCharacterIteratorMode
  56             A constant from CharacterIteratorMode
  57
  58         @param nCount
  59             Number of characters to traverse, it should not be less than 0.
  60             If you want to traverse in the opposite direction use
  61             XBreakIterator::previousCharacters() instead.
  62
  63         @param nDone
  64             Out parameter to receive the number of cells/Unicode characters
  65             traversed.
  66      */
  67     long nextCharacters( [in] string aText, [in] long nStartPos,
  68                      [in] ::com::sun::star::lang::Locale aLocale,
  69                      [in] short nCharacterIteratorMode,
  70                      [in] long nCount, [out] long nDone );
  71
  72     /** Traverses specified number of characters/cells in Text from
  73         <em>nStartPos</em> backwards.
  74         CharacterIteratorMode can be cell based or
  75         character based. A cell is made of more than one character.
  76
  77         @param aText
  78             The input text.
  79
  80         @param nStartPos
  81             The start index in aText.
  82
  83         @param aLocale
  84             The locale of the character preceding <em>nStartPos</em>.
  85
  86         @param nCharacterIteratorMode
  87             A constant from CharacterIteratorMode
  88
  89         @param nCount
  90             Number of characters to traverse, it should not be less than 0.
  91             If you want to traverse in the opposite direction use
  92             XBreakIterator::nextCharacters() instead.
  93
  94         @param nDone
  95             Out parameter to receive the number of cells/Unicode characters
  96             traversed.
  97
  98      */
  99     long previousCharacters( [in] string aText, [in] long nStartPos,
 100                      [in] ::com::sun::star::lang::Locale aLocale,
 101                      [in] short nCharacterIteratorMode,
 102                      [in] long nCount, [out] long nDone );
 103
 104     /** Traverses one word in Text from <em>nStartPos</em> forwards.
 105
 106         @param aText
 107             The input text.
 108
 109         @param nStartPos
 110             The start index in aText.
 111
 112         @param aLocale
 113             The locale of the character preceding <em>nStartPos</em>.
 114
 115         @param nWordType
 116             One of WordType, specifies the type of
 117             traveling.
 118
 119         @returns
 120             The Boundary of the found word. Normally used for
 121             CTRL-Right.
 122      */
 123     Boundary nextWord( [in] string aText, [in] long nStartPos,
 124                    [in] ::com::sun::star::lang::Locale aLocale,
 125                    [in] short nWordType);
 126
 127     /** Traverses one word in Text from <em>nStartPos</em> backwards.
 128
 129         @param aText
 130             The input text.
 131
 132         @param nStartPos
 133             The start index in aText.
 134
 135         @param aLocale
 136             The locale of the character preceding <em>nStartPos</em>.
 137
 138             <p> If the previous character is a space character and
 139             <em>nWordType</em> indicates spaces should be skipped, and
 140             if the first non-space character is an Asian character,
 141             then, since Asian word break needs language specific
 142             wordbreak dictionaries, the method will return -1 in
 143             Boundary::endPos() and the position after the
 144             Asian character (i.e. the space character) in
 145             Boundary::startPos(). The caller then has to
 146             call this method again with a correct <em>aLocale</em>
 147             referring to the Asian character, which is then the previous
 148             character of the space character where <em>nStartPos</em>
 149             points to. </p>
 150
 151             <p> <b>Note</b> that the OpenOffice.org 1.0 / StarOffice 6.0
 152             / StarSuite 6.0 i18n framework doesn't behave like this and
 153             mixed Western/CJK text may lead to wrong word iteration.
 154             This is fixed in later versions. </p>
 155
 156         @param nWordType
 157             One of WordType, specifies the type of
 158             traveling.
 159
 160         @returns
 161             The Boundary of the found word. Normally used for
 162             CTRL-Left.
 163     */
 164     Boundary previousWord( [in] string aText, [in] long nStartPos,
 165                        [in] ::com::sun::star::lang::Locale aLocale,
 166                        [in] short nWordType);
 167
 168     /** Identifies StartPos and EndPos of current word.
 169
 170         <p> If <em>nPos</em> is the boundary of a word, it is StartPos
 171         of one word and EndPos of previous word. In this situation, the
 172         outcome of the algorithm can be indeterminate. In this situation
 173         the <em>bPreferForward</em> flag is used. If bPreferForward ==
 174         `FALSE`, <em>nPos</em> is considered to be the end of the word
 175         and we look backwards for beginning of word, otherwise
 176         <em>nPos</em> is considered to be the start of the next word and
 177         we look forwards for the end of the word. </p>
 178
 179         @param aText
 180             The input text.
 181
 182         @param nPos
 183             The start index in aText.
 184
 185         @param aLocale
 186             The locale of the character preceding <em>nStartPos</em>.
 187
 188         @param nWordType
 189             One of WordType.
 190
 191         @param bPreferForward
 192             If `TRUE`, nPos should be considered the start of the next
 193             word and search proceeds forwards.
 194             If `FALSE`, nPos should be considered the end of the
 195             current word, and search proceeds backwards.
 196
 197         @returns
 198             The Boundary of the current word.
 199     */
 200     Boundary getWordBoundary( [in] string aText, [in] long nPos,
 201                       [in] ::com::sun::star::lang::Locale aLocale,
 202                       [in] short nWordType,
 203                       [in] boolean bPreferForward );
 204
 205     /** @deprecated
 206         Get the WordType of the word that starts at
 207         position <em>nPos</em>.
 208
 209         <p> This method is mis-defined, since WordType
 210         is not an attribute of a word, but a way to break words,
 211         like excluding or including tail spaces for spell checker
 212         or cursor traveling. It returns 0 always.
 213         </p>
 214      */
 215     short getWordType( [in] string aText, [in] long nPos,
 216                    [in] ::com::sun::star::lang::Locale aLocale);
 217
 218     /** If a word starts at position <em>nPos</em>.
 219
 220         <p> It is possible that both of this method
 221         and following method <em>isEndWord</em> all return
 222         `TRUE`, since StartPos of a word is inclusive
 223         while EndPos of a word is exclusive.
 224         </p>
 225
 226      */
 227     boolean isBeginWord( [in] string aText, [in] long nPos,
 228                      [in] ::com::sun::star::lang::Locale aLocale,
 229                      [in] short nWordType);
 230
 231     /** If a word ends at position <em>nPos</em>.
 232      */
 233     boolean isEndWord( [in] string aText, [in] long nPos,
 234                    [in] ::com::sun::star::lang::Locale aLocale,
 235                    [in] short nWordType);
 236
 237     /** Traverses in Text from <em>nStartPos</em> to the start of a
 238         sentence.
 239
 240         @param aText
 241             The input text.
 242
 243         @param nStartPos
 244             The start index in aText.
 245
 246         @param aLocale
 247             The locale of the character preceding <em>nStartPos</em>.
 248
 249         @returns
 250             The position where the sentence starts.
 251      */
 252     long beginOfSentence( [in] string aText, [in] long nStartPos,
 253                       [in] ::com::sun::star::lang::Locale aLocale );
 254
 255     /** Traverses in Text from <em>nStartPos</em> to the end of a
 256         sentence.
 257
 258         @param aText
 259             The input text.
 260
 261         @param nStartPos
 262             The start index in aText.
 263
 264         @param aLocale
 265             The locale of the character preceding <em>nStartPos</em>.
 266
 267         @returns
 268             The position where the sentence ends.
 269      */
 270     long endOfSentence( [in] string aText, [in] long nStartPos,
 271                     [in] ::com::sun::star::lang::Locale aLocale );
 272
 273     /** Calculate the line break position in the Text from the specified
 274         <em>nStartPos</em>.
 275
 276         @param aText
 277             The input text.
 278
 279         @param nStartPos
 280             The start index in aText.
 281
 282         @param aLocale
 283             The locale of the character preceding <em>nStartPos</em>.
 284
 285         @param nMinBreakPos
 286             Defines a minimum break position for hyphenated line break.
 287             When the position for hyphenated line break is less than
 288             <em>nMinBreakPos</em>, break position in
 289             LineBreakResults is set to -1.
 290
 291         @param aHyphOptions
 292             Defines if the hyphenator is to be used.
 293
 294         @param aUserOptions
 295             Defines how to handle hanging punctuations and forbidden
 296             characters at the start/end of a line.
 297
 298         @returns
 299             The LineBreakResults contain the break
 300             position of the line, BreakType and
 301             com::sun::star::linguistic2::XHyphenatedWord
 302      */
 303     LineBreakResults getLineBreak( [in] string aText, [in] long nStartPos,
 304                     [in] ::com::sun::star::lang::Locale aLocale,
 305                     [in] long nMinBreakPos,
 306                     [in] LineBreakHyphenationOptions aHyphOptions,
 307                     [in] LineBreakUserOptions aUserOptions );
 308
 309     /** Traverses in Text from <em>nStartPos</em> to the beginning of
 310         the specified script type.
 311
 312         @param aText
 313             The input text.
 314
 315         @param nStartPos
 316             The start index in aText.
 317
 318         @param nScriptType
 319             One of ScriptType.
 320
 321         @returns
 322             The position where the script type starts.
 323      */
 324     long beginOfScript( [in] string aText, [in] long nStartPos,
 325                     [in] short nScriptType );
 326
 327     /** Traverses in Text from <em>nStartPos</em> to the end of the
 328         specified script type.
 329
 330         @param aText
 331             The input text.
 332
 333         @param nStartPos
 334             The start index in aText.
 335
 336         @param nScriptType
 337             One of ScriptType.
 338
 339         @returns
 340             The position where the script type ends.
 341      */
 342     long endOfScript( [in] string aText, [in] long nStartPos,
 343                   [in] short nScriptType );
 344
 345     /** Traverses in Text from <em>nStartPos</em> to the next start of
 346         the specified script type.
 347
 348         @param aText
 349             The input text.
 350
 351         @param nStartPos
 352             The start index in aText.
 353
 354         @param nScriptType
 355             One of ScriptType.
 356
 357         @returns
 358             The position where the next script type starts.
 359      */
 360     long nextScript( [in] string aText, [in] long nStartPos,
 361                  [in] short nScriptType );
 362
 363     /** Traverses in Text from <em>nStartPos</em> to the previous start
 364         of the specified script type.
 365
 366         @param aText
 367             The input text.
 368
 369         @param nStartPos
 370             The start index in aText.
 371
 372         @param nScriptType
 373             One of ScriptType.
 374
 375         @returns
 376             The position where the previous script type starts.
 377      */
 378     long previousScript( [in] string aText, [in] long nStartPos,
 379                       [in] short nScriptType );
 380
 381     /** Get the script type of the character at position <em>nPos</em>.
 382
 383         @param aText
 384             The input text.
 385
 386         @param nPos
 387             The index in aText.
 388
 389         @returns
 390             One of ScriptType.
 391      */
 392     short   getScriptType( [in] string aText, [in] long nPos);
 393
 394     /** Traverses in Text from <em>nStartPos</em> to the beginning of
 395         the specified character type.
 396
 397         @param aText
 398             The input text.
 399
 400         @param nStartPos
 401             The start index in aText.
 402
 403         @param aLocale
 404             The locale of the character preceding <em>nStartPos</em>.
 405
 406         @param nCharType
 407             One of CharType
 408
 409         @returns
 410             The position where the character type starts
 411      */
 412     long beginOfCharBlock( [in] string aText, [in] long nStartPos,
 413                        [in] ::com::sun::star::lang::Locale aLocale,
 414                        [in] short nCharType );
 415
 416     /** Traverses in Text from <em>nStartPos</em> to the end of the
 417         specified character type.
 418
 419         @param aText
 420             The input text.
 421
 422         @param nStartPos
 423             The start index in aText.
 424
 425         @param aLocale
 426             The locale of the character preceding <em>nStartPos</em>.
 427
 428         @param nCharType
 429             One of CharType
 430
 431         @returns
 432             The position where the character type ends.
 433      */
 434     long endOfCharBlock( [in] string aText, [in] long nStartPos,
 435                      [in] ::com::sun::star::lang::Locale aLocale,
 436                      [in] short nCharType );
 437
 438     /** Traverses in Text from <em>nStartPos</em> to the next start of
 439         the specified character type.
 440
 441         @param aText
 442             The input text.
 443
 444         @param nStartPos
 445             The start index in aText.
 446
 447         @param aLocale
 448             The locale of the character preceding <em>nStartPos</em>.
 449
 450         @param nCharType
 451             One of CharType
 452
 453         @returns
 454             The position where the next character type starts.
 455      */
 456     long nextCharBlock( [in] string aText, [in] long nStartPos,
 457                     [in] ::com::sun::star::lang::Locale aLocale,
 458                     [in] short nCharType );
 459
 460     /** Traverses in Text from <em>nStartPos</em> to the previous start
 461         of the specified character type.
 462
 463         @param aText
 464             The input text.
 465
 466         @param nStartPos
 467             The start index in aText.
 468
 469         @param aLocale
 470             The locale of the character preceding <em>nStartPos</em>.
 471
 472         @param nCharType
 473             One of CharType
 474
 475         @returns
 476             The position where the previous character type starts.
 477      */
 478     long previousCharBlock ( [in] string aText, [in] long nStartPos,
 479                      [in] ::com::sun::star::lang::Locale aLocale,
 480                      [in] short nCharType );
 481 };
 482
 483 }; }; }; };
 484
 485 #endif
 486
 487 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */