/*************************************************************************
 *
 *  $RCSfile: XBreakIterator.idl,v $
 *
 *  $Revision: 1.8.4.2 $
 *
 *  last change: $Author: mi $ $Date: 2003/01/21 17:44:41 $
 *
 *  The Contents of this file are made available subject to the terms of
 *  either of the following licenses
 *
 *         - GNU Lesser General Public License Version 2.1
 *         - Sun Industry Standards Source License Version 1.1
 *
 *  Sun Microsystems Inc., October, 2000
 *
 *  GNU Lesser General Public License Version 2.1
 *  =============================================
 *  Copyright 2000 by Sun Microsystems, Inc.
 *  901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License version 2.1, as published by the Free Software Foundation.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *  MA  02111-1307  USA
 *
 *
 *  Sun Industry Standards Source License Version 1.1
 *  =================================================
 *  The contents of this file are subject to the Sun Industry Standards
 *  Source License Version 1.1 (the "License"); You may not use this file
 *  except in compliance with the License. You may obtain a copy of the
 *  License at http://www.openoffice.org/license.html.
 *
 *  Software provided under this License is provided on an "AS IS" basis,
 *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
 *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
 *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
 *  See the License for the specific provisions governing your rights and
 *  obligations concerning the Software.
 *
 *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
 *
 *  Copyright: 2000 by Sun Microsystems, Inc.
 *
 *  All Rights Reserved.
 *
 *  Contributor(s): _______________________________________
 *
 *
 ************************************************************************/
#ifndef __com_sun_star_i18n_XBreakIterator_idl__
#define __com_sun_star_i18n_XBreakIterator_idl__

#ifndef __com_sun_star_lang_Locale_idl__
#include <com/sun/star/lang/Locale.idl>
#endif

#ifndef __com_sun_star_i18n_LineBreakUserOptions_idl__
#include <com/sun/star/i18n/LineBreakUserOptions.idl>
#endif

#ifndef __com_sun_star_i18n_LineBreakHyphenationOptions_idl__
#include <com/sun/star/i18n/LineBreakHyphenationOptions.idl>
#endif

#ifndef __com_sun_star_i18n_LineBreakResults_idl__
#include <com/sun/star/i18n/LineBreakResults.idl>
#endif

#ifndef __com_sun_star_i18n_Boundary_idl__
#include <com/sun/star/i18n/Boundary.idl>
#endif

//============================================================================

module com {  module sun {  module star {  module i18n {

//============================================================================

/** 
    contains the base routines for iteration in Unicode string. Iterates over
    characters, words, sentences and line breaks.

    <p> Assumption: StartPos is inclusive and EndPos is exclusive. </p>
 */

interface XBreakIterator: com::sun::star::uno::XInterface
{
    //------------------------------------------------------------------------
    /** Traverses specified number of characters in Text from
        <em>nStartPos</em> to the right.
        <type>CharacterIteratorMode</type> can be cell based or
        character based. A cell is made of more than one character.

        @param nCount
            Number of characters to traverse, it should not be less than 0.
            If you want to traverse in the opposite direction use
            <member>XBreakIterator::previousCharacters()</member> instead.
     */
    long nextCharacters( [in] string aText, [in] long nStartPos,
                     [in] ::com::sun::star::lang::Locale aLocale,
                     [in] short nCharacterIteratorMode,
                     [in] long nCount, [out] long nDone );

    //------------------------------------------------------------------------
    /** Traverses specified number of characters in Text from
        <em>nStartPos</em> to the left.
        <type>CharacterIteratorMode</type> can be cell based or
        character based. A cell is made of more than one character.

        @param nCount
            Number of characters to traverse, it should not be less than 0.
            If you want to traverse in the opposite direction use
            <member>XBreakIterator::nextCharacters()</member> instead.
     */
    long previousCharacters( [in] string aText, [in] long nStartPos,
                     [in] ::com::sun::star::lang::Locale aLocale,
                     [in] short nCharacterIteratorMode,
                     [in] long nCount, [out] long nDone );

    //------------------------------------------------------------------------
    /** Traverses one word in Text from <em>nStartPos</em> to the right.

        @param nWordType
            One of <type>WordType</type>, specifies the type of
            travelling.

        @returns
            The Boundary of the found word. Normally used for
            CTRL-Right.
     */
    Boundary nextWord( [in] string aText, [in] long nStartPos,
                   [in] ::com::sun::star::lang::Locale aLocale,
                   [in] short nWordType);

    //------------------------------------------------------------------------
    /** Traverses one word in Text from <em>nStartPos</em> to the left.

        @param aLocale
            The locale of the character preceding <em>nStartPos</em>.

            <p> If the previous character is a space character and
            <em>nWordType</em> indicates spaces should be skipped, and
            if the first non-space character is an Asian character,
            then, since Asian word break needs language specific
            wordbreak dictionaries, the method will return -1 in
            <member>Boundary::endPos</member> and the position after the
            Asian character (i.e. the space character) in
            <member>Boundary::startPos</member>. The caller then has to
            call this method again with a correct <em>aLocale</em>
            referring to the Asian character, which is then the previous
            character of the space character where <em>nStartPos</em>
            points to. </p>

            <p> <b>Note</b> that the OpenOffice.org 1.0 / StarOffice 6.0
            / StarSuite 6.0 i18n framework doesn't behave like this and
            mixed Western/CJK text may lead to wrong word iteration.
            This is fixed in later versions. </p>

        @param nWordType
            One of <type>WordType</type>, specifies the type of
            travelling.

        @returns
            The Boundary of the found word. Normally used for
            CTRL-Left.
    */
    Boundary previousWord( [in] string aText, [in] long nStartPos,
                       [in] ::com::sun::star::lang::Locale aLocale,
                       [in] short nWordType);

    //------------------------------------------------------------------------
    /** Identifies StartPos and EndPos of current word.

        <p> If <em>nPos</em> is the boundary of a word, it is StartPos
        of one word and EndPos of previous word. In this situation, the
        outcome of the algorithm can be indeterminate. In this situation
        the <em>bPreferForward</em> flag is used. If bPreferForward ==
        <FALSE/>, <em>nPos</em> is considered to be the end of the word
        and we look for beginning of word on left, otherwise
        <em>nPos</em> is considered to be the start of the next word and
        we look right for the end of the word. </p>

        @param nWordType
            One of <type>WordType</type>.

        @returns
            The Boundary of the current word.
    */
    Boundary getWordBoundary( [in] string aText, [in] long nPos,
                      [in] ::com::sun::star::lang::Locale aLocale,
                      [in] short nWordType,
                      [in] boolean bPreferForward );

    //------------------------------------------------------------------------
    /** Get the <type>WordType</type> of the word that starts at
        position <em>nPos</em>.
     */
    short getWordType( [in] string aText, [in] long nPos,
                   [in] ::com::sun::star::lang::Locale aLocale);

    //------------------------------------------------------------------------
    /** If a word starts at position <em>nPos</em>.
     */
    boolean isBeginWord( [in] string aText, [in] long nPos,
                     [in] ::com::sun::star::lang::Locale aLocale,
                     [in] short nWordType);

    //------------------------------------------------------------------------
    /** If a word ends at position <em>nPos</em>.
     */
    boolean isEndWord( [in] string aText, [in] long nPos,
                   [in] ::com::sun::star::lang::Locale aLocale,
                   [in] short nWordType);

    //------------------------------------------------------------------------
    /** Traverses in Text from <em>nStartPos</em> to the start of a
        sentence.

        @returns
            The position where the sentence starts.
     */
    long beginOfSentence( [in] string aText, [in] long nStartPos,
                      [in] ::com::sun::star::lang::Locale aLocale );

    //------------------------------------------------------------------------
    /** Traverses in Text from <em>nStartPos</em> to the end of a
        sentence.

        @returns
            The position where the sentence ends.
     */
    long endOfSentence( [in] string aText, [in] long nStartPos,
                    [in] ::com::sun::star::lang::Locale aLocale );

    //------------------------------------------------------------------------
    /** Calculate the linebreak position in the Text from the specified
        <em>nStartPos</em>.

        @param nMinBreakPos
            TODO

        @param aHyphOptions
            Defines if the hyphenator is to be used.

        @param aUserOptions
            Defines how to handle hanging punctuations, the forbidden
            character at the start/end of a line.

        @returns
            The LineBreakResults contain the break position of the word
            and which kind of break it is.
     */
    LineBreakResults getLineBreak( [in] string aText, [in] long nStartPos,
                    [in] ::com::sun::star::lang::Locale aLocale,
                    [in] long nMinBreakPos,
                    [in] LineBreakHyphenationOptions aHyphOptions,
                    [in] LineBreakUserOptions aUserOptions );

    //------------------------------------------------------------------------
    /** Get the position where the specified script starts, starting to
        look from <em>nStartPos</em> to the left.

        @param nScriptType
            One of <type>ScriptType</type>.
     */
    long beginOfScript( [in] string aText, [in] long nStartPos,
                    [in] short nScriptType );

    //------------------------------------------------------------------------
    /** Get the position where the specified script starts, starting to
        look from <em>nStartPos</em> to the right.

        @param nScriptType
            One of <type>ScriptType</type>.
     */
    long endOfScript( [in] string aText, [in] long nStartPos,
                  [in] short nScriptType );

    //------------------------------------------------------------------------
    /** Get the position where the next specified script starts,
        starting to look from <em>nStartPos</em> to the right.

        @param nScriptType
            One of <type>ScriptType</type>.
     */
    long nextScript( [in] string aText, [in] long nStartPos,
                 [in] short nScriptType );

    //------------------------------------------------------------------------
    /** Get the position where the next specified script starts,
        starting to look from <em>nStartPos</em> to the left.

        @param nScriptType
            One of <type>ScriptType</type>.
     */
    long previousScript( [in] string aText, [in] long nStartPos,
                      [in] short nScriptType );

    //------------------------------------------------------------------------
    /** Get the script type of the character at position <em>nPos</em>.

        @returns
            One of <type>ScriptType</type>.
     */
    short   getScriptType( [in] string aText, [in] long nPos);

    //------------------------------------------------------------------------
    /** Traverses in Text from <em>nStartPos</em> to the beginning of
        the specified character type.

        @param nCharType
            One of <type>CharType</type>

        @returns
            The position where the character type starts
     */
    long beginOfCharBlock( [in] string aText, [in] long nStartPos,
                       [in] ::com::sun::star::lang::Locale aLocale,
                       [in] short nCharType );

    //------------------------------------------------------------------------
    /** Traverses in Text from <em>nStartPos</em> to the end of the
        specified character type.

        @param nCharType
            One of <type>CharType</type>

        @returns
            The position where the character type ends.
     */
    long endOfCharBlock( [in] string aText, [in] long nStartPos,
                     [in] ::com::sun::star::lang::Locale aLocale,
                     [in] short nCharType );

    //------------------------------------------------------------------------
    /** Traverses in Text from <em>nStartPos</em> to the next start of
        the specified character type.

        @param nCharType
            One of <type>CharType</type>

        @returns
            The position where the next character type starts.
     */
    long nextCharBlock( [in] string aText, [in] long nStartPos,
                    [in] ::com::sun::star::lang::Locale aLocale,
                    [in] short nCharType );

    //------------------------------------------------------------------------
    /** Traverses in Text from <em>nStartPos</em> to the previous start
        of the specified character type.

        @param nCharType
            One of <type>CharType</type>

        @returns
            The position where the previous character type starts.
     */
    long previousCharBlock ( [in] string aText, [in] long nStartPos,
                     [in] ::com::sun::star::lang::Locale aLocale,
                     [in] short nCharType );
};

//============================================================================
}; }; }; };
//============================================================================
#endif
