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