offapi/com/sun/star/linguistic2/XHyphenator.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_linguistic2_XHyphenator_idl__
  28 #define __com_sun_star_linguistic2_XHyphenator_idl__
  29
  30
  31 #ifndef __com_sun_star_lang_Localeidl__
  32 #include <com/sun/star/lang/Locale.idl>
  33 #endif
  34
  35 #ifndef __com_sun_star_linguistic2_XSupportedLocales_idl__
  36 #include <com/sun/star/linguistic2/XSupportedLocales.idl>
  37 #endif
  38
  39 #ifndef __com_sun_star_linguistic2_XDictionaryList_idl__
  40 #include <com/sun/star/linguistic2/XDictionaryList.idl>
  41 #endif
  42
  43 #ifndef __com_sun_star_linguistic2_XHyphenatedWord_idl__
  44 #include <com/sun/star/linguistic2/XHyphenatedWord.idl>
  45 #endif
  46
  47 #ifndef __com_sun_star_linguistic2_XPossibleHyphens_idl__
  48 #include <com/sun/star/linguistic2/XPossibleHyphens.idl>
  49 #endif
  50
  51 #ifndef _COM_SUN_STAR_BEANS_PROPERTYVALUES_idl_
  52 #include <com/sun/star/beans/PropertyValues.idl>
  53 #endif
  54
  55 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  56 #include <com/sun/star/lang/IllegalArgumentException.idl>
  57 #endif
  58
  59
  60 //=============================================================================
  61
  62 module com { module sun { module star { module linguistic2 {
  63
  64 //=============================================================================
  65 /** provides functionality for hyphenation of single words.
  66
  67     <P>Its three main functionalities are to provide a suitable position for
  68     breaking lines within a word, query about the existence of an alternative
  69     spelling at a specific position of a word and provide a list of
  70     possible hyphenation positions within a word.</P>
  71
  72     <P>A hyphenation position for a word with n characters is represented
  73     by a value in the range from 0 to n-2, indicating the position
  74     of the character after which the hyphenation is done. That is,
  75     it is after the first and before the last character.</P>
  76
  77     <P>A valid hyphenation position is a hyphenation position that
  78     fulfills all the restrictions implied by the properties
  79     MinLeading, MinTrailing and MinWordLength.</P>
  80
  81     @see    <type scope="com::sun::star::linguistic2">LinguProperties</type>
  82     @see    <type scope="com::sun::star::linguistic2">XSupportedLocales</type>
  83 */
  84 published interface XHyphenator : com::sun::star::linguistic2::XSupportedLocales
  85 {
  86     //-------------------------------------------------------------------------
  87     /** tries to find a valid hyphenation position relative
  88         to the beginning of a word.
  89
  90         <P>Note: Some languages, for example arabic, are written from right
  91         to left.</P>
  92
  93         @returns
  94             the XHyphenatedWord for the last valid hyphenation position
  95              that is less than or equal to nMaxLeading - 1.
  96             If there is no such valid hyphenation position, <NULL/> is returned.
  97
  98         @param  aWord
  99             is the word to be hyphenated.
 100
 101         @param  aLocale
 102             defines the language to be used.
 103
 104             <P>If the language is not supported, an IllegalArgumentException
 105             exception is raised.</P>
 106
 107         @param  nMaxLeading
 108             specifies the maximum number of characters to remain
 109             before the hyphen in the hyphenated word.
 110
 111             <P>It has to be greater than or equal to 0.</P>
 112
 113         @param aProperties
 114             provides property values to be used for this function call only.
 115             It is usually empty in order to use the default values supplied
 116             with the property set.
 117
 118         @see    <type scope="com::sun::star::linguistic2">XHyphenatedWord</type>
 119         @see    <type scope="com::sun::star::lang">Locale</type>
 120     */
 121     com::sun::star::linguistic2::XHyphenatedWord hyphenate(
 122             [in] string aWord,
 123             [in] com::sun::star::lang::Locale aLocale,
 124             [in] short nMaxLeading,
 125             [in] com::sun::star::beans::PropertyValues aProperties )
 126         raises( com::sun::star::lang::IllegalArgumentException );
 127
 128     //-------------------------------------------------------------------------
 129     /** checks whether hyphenation at a position in a word will result in
 130         an alternative spelling or not.
 131
 132         <P>An alternative spelling position is a hyphen position where,
 133         if hyphenation is done here, the writing of the word changes.
 134         Example: "B&auml;cker" in German pre spelling-reform becomes
 135          "B&auml;kker" if hyphenation is done after the "c".</P>
 136
 137         <P>The hyphenation position does not need to be a valid one to be an
 138         alternative spelling position.</P>
 139
 140         @returns
 141             the information about the alternative spelling found at the
 142             specified position. Otherwise, if no alternative spelling was
 143             found, <NULL/> is returned.
 144
 145         @param  aWord
 146             is the original word to be looked at for having an alternative
 147             spelling, if hyphenation is done at position nIndex.
 148
 149         @param aLocale
 150             specifies the language to be used.
 151
 152             <P>If the language is not supported, an IllegalArgumentException
 153             exception is raised.</P>
 154
 155         @param  nIndex
 156             is the position in the word to be looked at.
 157
 158             <P>If the length of the word is n, the value of this
 159             parameter has to be in the range from 0 to n-2.</P>
 160
 161         @param aProperties
 162             provides property values to be used for this function call only.
 163             It is usually empty in order to use the default values supplied
 164             with the property set.
 165
 166         @see    <type scope="com::sun::star::linguistic2">XHyphenatedWord</type>
 167         @see    <type scope="com::sun::star::lang">Locale</type>
 168     */
 169     com::sun::star::linguistic2::XHyphenatedWord queryAlternativeSpelling(
 170             [in] string aWord,
 171             [in] com::sun::star::lang::Locale aLocale,
 172             [in] short nIndex,
 173             [in] com::sun::star::beans::PropertyValues aProperties )
 174         raises( com::sun::star::lang::IllegalArgumentException );
 175
 176     //-------------------------------------------------------------------------
 177     /** returns information about all possible hyphenation positions of a word.
 178
 179         @returns
 180             an <type scope="com::sun::star::linguistic2">XPossibleHyphens</type>
 181             for the given word and language if there are any hyphenation
 182             positions. <NULL/> otherwise.
 183
 184         @param  aWord
 185             is the word for which information about the possible
 186              hyphenation positions is to be retrieved.
 187
 188         @param  aLocale
 189             defines the language of the word.
 190
 191             <P>If the language is not supported, an IllegalArgumentException
 192             exception is raised.</P>
 193
 194         @param aProperties
 195             provides property values to be used for this function call only.
 196             It is usually empty in order to use the default values supplied
 197             with the property set.
 198
 199         @see    <type scope="com::sun::star::linguistic2">XPossibleHyphens</type>
 200         @see    <type scope="com::sun::star::lang">Locale</type>
 201     */
 202     com::sun::star::linguistic2::XPossibleHyphens createPossibleHyphens(
 203             [in] string aWord,
 204             [in] com::sun::star::lang::Locale aLocale,
 205             [in] com::sun::star::beans::PropertyValues aProperties )
 206         raises( com::sun::star::lang::IllegalArgumentException );
 207
 208 };
 209
 210 //=============================================================================
 211
 212 }; }; }; };
 213
 214 #endif
 215