xref: /AOO41X/main/offapi/com/sun/star/linguistic2/XHyphenator.idl (revision d1766043198e81d0bcfc626e12893e7b4d7e31ca)

/**************************************************************
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/


#ifndef __com_sun_star_linguistic2_XHyphenator_idl__
#define __com_sun_star_linguistic2_XHyphenator_idl__


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

#ifndef __com_sun_star_linguistic2_XSupportedLocales_idl__
#include <com/sun/star/linguistic2/XSupportedLocales.idl>
#endif

#ifndef __com_sun_star_linguistic2_XDictionaryList_idl__
#include <com/sun/star/linguistic2/XDictionaryList.idl>
#endif

#ifndef __com_sun_star_linguistic2_XHyphenatedWord_idl__
#include <com/sun/star/linguistic2/XHyphenatedWord.idl>
#endif

#ifndef __com_sun_star_linguistic2_XPossibleHyphens_idl__
#include <com/sun/star/linguistic2/XPossibleHyphens.idl>
#endif

#ifndef _COM_SUN_STAR_BEANS_PROPERTYVALUES_idl_
#include <com/sun/star/beans/PropertyValues.idl>
#endif

#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
#include <com/sun/star/lang/IllegalArgumentException.idl>
#endif


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

module com { module sun { module star { module linguistic2 {

//=============================================================================
/** provides functionality for hyphenation of single words.

	<P>Its three main functionalities are to provide a suitable position for
	breaking lines within a word, query about the existence of an alternative
	spelling at a specific position of a word and provide a list of
	possible hyphenation positions within a word.</P>

	<P>A hyphenation position for a word with n characters is represented
	by a value in the range from 0 to n-2, indicating the position
	of the character after which the hyphenation is done. That is,
	it is after the first and before the last character.</P>

	<P>A valid hyphenation position is a hyphenation position that
	fulfills all the restrictions implied by the properties
	MinLeading, MinTrailing and MinWordLength.</P>

    @see    <type scope="com::sun::star::linguistic2">LinguProperties</type>
    @see    <type scope="com::sun::star::linguistic2">XSupportedLocales</type>
*/
published interface XHyphenator : com::sun::star::linguistic2::XSupportedLocales
{
	//-------------------------------------------------------------------------
	/** tries to find a valid hyphenation position relative
		to the beginning of a word.

		<P>Note: Some languages, for example arabic, are written from right
		to left.</P>

		@returns
			the XHyphenatedWord for the last valid hyphenation position
	 		that is less than or equal to nMaxLeading - 1.
			If there is no such valid hyphenation position, <NULL/> is returned.

		@param  aWord
			is the word to be hyphenated.

		@param  aLocale
			defines the language to be used.

			<P>If the language is not supported, an IllegalArgumentException
			exception is raised.</P>

		@param  nMaxLeading
			specifies the maximum number of characters to remain
			before the hyphen in the hyphenated word.

			<P>It has to be greater than or equal to 0.</P>

		@param aProperties
			provides property values to be used for this function call only.
			It is usually empty in order to use the default values supplied
			with the property set.

        @see    <type scope="com::sun::star::linguistic2">XHyphenatedWord</type>
        @see    <type scope="com::sun::star::lang">Locale</type>
	*/
	com::sun::star::linguistic2::XHyphenatedWord hyphenate(
			[in] string aWord,
			[in] com::sun::star::lang::Locale aLocale,
			[in] short nMaxLeading,
			[in] com::sun::star::beans::PropertyValues aProperties )
		raises( com::sun::star::lang::IllegalArgumentException );

	//-------------------------------------------------------------------------
	/** checks whether hyphenation at a position in a word will result in
		an alternative spelling or not.

		<P>An alternative spelling position is a hyphen position where,
		if hyphenation is done here, the writing of the word changes.
		Example: "B&auml;cker" in German pre spelling-reform becomes
	 	"B&auml;kker" if hyphenation is done after the "c".</P>

		<P>The hyphenation position does not need to be a valid one to be an
		alternative spelling position.</P>

		@returns
			the information about the alternative spelling found at the
			specified position. Otherwise, if no alternative spelling was
			found, <NULL/> is returned.

		@param  aWord
			is the original word to be looked at for having an alternative
			spelling, if hyphenation is done at position nIndex.

		@param aLocale
			specifies the language to be used.

			<P>If the language is not supported, an IllegalArgumentException
			exception is raised.</P>

		@param  nIndex
			is the position in the word to be looked at.

			<P>If the length of the word is n, the value of this
			parameter has to be in the range from 0 to n-2.</P>

		@param aProperties
			provides property values to be used for this function call only.
			It is usually empty in order to use the default values supplied
			with the property set.

        @see    <type scope="com::sun::star::linguistic2">XHyphenatedWord</type>
        @see    <type scope="com::sun::star::lang">Locale</type>
	*/
	com::sun::star::linguistic2::XHyphenatedWord queryAlternativeSpelling(
			[in] string aWord,
			[in] com::sun::star::lang::Locale aLocale,
			[in] short nIndex,
			[in] com::sun::star::beans::PropertyValues aProperties )
		raises( com::sun::star::lang::IllegalArgumentException );

	//-------------------------------------------------------------------------
	/** returns information about all possible hyphenation positions of a word.

		@returns
			an <type scope="com::sun::star::linguistic2">XPossibleHyphens</type>
			for the given word and language if there are any hyphenation
			positions. <NULL/> otherwise.

		@param  aWord
			is the word for which information about the possible
	 		hyphenation positions is to be retrieved.

		@param  aLocale
			defines the language of the word.

			<P>If the language is not supported, an IllegalArgumentException
			exception is raised.</P>

		@param aProperties
			provides property values to be used for this function call only.
			It is usually empty in order to use the default values supplied
			with the property set.

        @see    <type scope="com::sun::star::linguistic2">XPossibleHyphens</type>
        @see    <type scope="com::sun::star::lang">Locale</type>
	*/
	com::sun::star::linguistic2::XPossibleHyphens createPossibleHyphens(
			[in] string aWord,
			[in] com::sun::star::lang::Locale aLocale,
			[in] com::sun::star::beans::PropertyValues aProperties )
		raises( com::sun::star::lang::IllegalArgumentException );

};

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

}; }; }; };

#endif