Version 5.2.6.1, tag libreoffice-5.2.6.1
[LibreOffice.git] / offapi / com / sun / star / linguistic2 / XHyphenator.idl
blob96d095f77dc789d819881dba5c91e03b0313c4ca
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
19 #ifndef __com_sun_star_linguistic2_XHyphenator_idl__
20 #define __com_sun_star_linguistic2_XHyphenator_idl__
23 #include <com/sun/star/lang/Locale.idl>
24 #include <com/sun/star/linguistic2/XSupportedLocales.idl>
25 #include <com/sun/star/linguistic2/XDictionaryList.idl>
26 #include <com/sun/star/linguistic2/XHyphenatedWord.idl>
27 #include <com/sun/star/linguistic2/XPossibleHyphens.idl>
28 #include <com/sun/star/beans/PropertyValues.idl>
29 #include <com/sun/star/lang/IllegalArgumentException.idl>
32 module com { module sun { module star { module linguistic2 {
34 /** provides functionality for hyphenation of single words.
36 <P>Its three main functionalities are to provide a suitable position for
37 breaking lines within a word, query about the existence of an alternative
38 spelling at a specific position of a word and provide a list of
39 possible hyphenation positions within a word.</P>
41 <P>A hyphenation position for a word with n characters is represented
42 by a value in the range from 0 to n-2, indicating the position
43 of the character after which the hyphenation is done. That is,
44 it is after the first and before the last character.</P>
46 <P>A valid hyphenation position is a hyphenation position that
47 fulfills all the restrictions implied by the properties
48 MinLeading, MinTrailing and MinWordLength.</P>
50 @see com::sun::star::linguistic2::LinguProperties
51 @see com::sun::star::linguistic2::XSupportedLocales
53 published interface XHyphenator : com::sun::star::linguistic2::XSupportedLocales
55 /** tries to find a valid hyphenation position relative
56 to the beginning of a word.
58 <P>Note: Some languages, for example Arabic, are written from right
59 to left.</P>
61 @returns
62 the XHyphenatedWord for the last valid hyphenation position
63 that is less than or equal to nMaxLeading - 1.
64 If there is no such valid hyphenation position, `NULL` is returned.
66 @param aWord
67 is the word to be hyphenated.
69 @param aLocale
70 defines the language to be used.
72 <P>If the language is not supported, an IllegalArgumentException
73 exception is raised.</P>
75 @param nMaxLeading
76 specifies the maximum number of characters to remain
77 before the hyphen in the hyphenated word.
79 <P>It has to be greater than or equal to 0.</P>
81 @param aProperties
82 provides property values to be used for this function call only.
83 It is usually empty in order to use the default values supplied
84 with the property set.
86 @see com::sun::star::linguistic2::XHyphenatedWord
87 @see com::sun::star::lang::Locale
89 com::sun::star::linguistic2::XHyphenatedWord hyphenate(
90 [in] string aWord,
91 [in] com::sun::star::lang::Locale aLocale,
92 [in] short nMaxLeading,
93 [in] com::sun::star::beans::PropertyValues aProperties )
94 raises( com::sun::star::lang::IllegalArgumentException );
96 /** checks whether hyphenation at a position in a word will result in
97 an alternative spelling or not.
99 <P>An alternative spelling position is a hyphen position where,
100 if hyphenation is done here, the writing of the word changes.
101 Example: "B&auml;cker" in German pre spelling-reform becomes
102 "B&auml;kker" if hyphenation is done after the "c".</P>
104 <P>The hyphenation position does not need to be a valid one to be an
105 alternative spelling position.</P>
107 @returns
108 the information about the alternative spelling found at the
109 specified position. Otherwise, if no alternative spelling was
110 found, `NULL` is returned.
112 @param aWord
113 is the original word to be looked at for having an alternative
114 spelling, if hyphenation is done at position nIndex.
116 @param aLocale
117 specifies the language to be used.
119 <P>If the language is not supported, an IllegalArgumentException
120 exception is raised.</P>
122 @param nIndex
123 is the position in the word to be looked at.
125 <P>If the length of the word is n, the value of this
126 parameter has to be in the range from 0 to n-2.</P>
128 @param aProperties
129 provides property values to be used for this function call only.
130 It is usually empty in order to use the default values supplied
131 with the property set.
133 @see com::sun::star::linguistic2::XHyphenatedWord
134 @see com::sun::star::lang::Locale
136 com::sun::star::linguistic2::XHyphenatedWord queryAlternativeSpelling(
137 [in] string aWord,
138 [in] com::sun::star::lang::Locale aLocale,
139 [in] short nIndex,
140 [in] com::sun::star::beans::PropertyValues aProperties )
141 raises( com::sun::star::lang::IllegalArgumentException );
143 /** returns information about all possible hyphenation positions of a word.
145 @returns
146 an com::sun::star::linguistic2::XPossibleHyphens
147 for the given word and language if there are any hyphenation
148 positions. `NULL` otherwise.
150 @param aWord
151 is the word for which information about the possible
152 hyphenation positions is to be retrieved.
154 @param aLocale
155 defines the language of the word.
157 <P>If the language is not supported, an IllegalArgumentException
158 exception is raised.</P>
160 @param aProperties
161 provides property values to be used for this function call only.
162 It is usually empty in order to use the default values supplied
163 with the property set.
165 @see com::sun::star::linguistic2::XPossibleHyphens
166 @see com::sun::star::lang::Locale
168 com::sun::star::linguistic2::XPossibleHyphens createPossibleHyphens(
169 [in] string aWord,
170 [in] com::sun::star::lang::Locale aLocale,
171 [in] com::sun::star::beans::PropertyValues aProperties )
172 raises( com::sun::star::lang::IllegalArgumentException );
177 }; }; }; };
179 #endif
181 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */