offapi/com/sun/star/linguistic2/XDictionaryList.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XDictionaryList.idl,v $
  10  * $Revision: 1.13 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_linguistic2_XDictionaryList_idl__
  31 #define __com_sun_star_linguistic2_XDictionaryList_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_linguistic2_XDictionary_idl__
  38 #include <com/sun/star/linguistic2/XDictionary.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_linguistic2_XDictionaryListEventListener_idl__
  42 #include <com/sun/star/linguistic2/XDictionaryListEventListener.idl>
  43 #endif
  44
  45 //=============================================================================
  46
  47 module com { module sun { module star { module linguistic2 {
  48
  49 //=============================================================================
  50 /** is used to manage and maintain a list of dictionaries.
  51
  52     <P>A dictionary-list may be given to a spellchecker or hyphenator
  53     service implementation on their creation in order to supply a set
  54     of dictionaries and additional information to be used for
  55     those purposes.</P>
  56
  57     @see    <type scope="com::sun::star::linguistic2">XDictionary</type>
  58     @see    <type scope="com::sun::star::uno">XInterface</type>
  59 */
  60 published interface XDictionaryList : com::sun::star::uno::XInterface
  61 {
  62     //-------------------------------------------------------------------------
  63     /**
  64         @returns
  65             the number of dictionaries in the list.
  66     */
  67     short getCount();
  68
  69     //-------------------------------------------------------------------------
  70     /**
  71         @returns
  72              a sequence with an entry for every dictionary
  73             in the list.
  74
  75         @see    <type scope="com::sun::star::linguistic2">XDictionary</type>
  76     */
  77     sequence<com::sun::star::linguistic2::XDictionary> getDictionaries();
  78
  79     //-------------------------------------------------------------------------
  80     /** searches the list for a dictionary with a given name.
  81
  82          @returns
  83             the XDictionary with the specified name. If no such
  84             dictionary exists, <NULL/> will be returned.
  85
  86         @param  aDictionaryName
  87             specifies the name of the dictionary to look for.
  88
  89         @see    <type scope="com::sun::star::linguistic2">XDictionary</type>
  90     */
  91     com::sun::star::linguistic2::XDictionary getDictionaryByName(
  92             [in] string aDictionaryName );
  93
  94     //-------------------------------------------------------------------------
  95     /** adds a dictionary to the list.
  96
  97         <P>Additionally, the dictionary-list will add itself to the list of dictionary
  98          event listeners of that dictionary.</P>
  99
 100         @returns
 101              <TRUE/> if the dictionary was added successfully,
 102             <FALSE/> otherwise.
 103
 104         @param  xDictionary
 105             the dictionary to be added.
 106
 107         @see    <type scope="com::sun::star::linguistic2">XDictionary</type>
 108     */
 109     boolean addDictionary(
 110             [in] com::sun::star::linguistic2::XDictionary xDictionary );
 111
 112     //-------------------------------------------------------------------------
 113     /** removes a single dictionary from the list.
 114
 115         <P>If the dictionary is still active, it will be deactivated
 116         first. The dictionary-list will remove itself from the list of
 117         dictionary event listeners of the dictionary.</P>
 118
 119         @returns
 120              <TRUE/> if the dictionary was removed successfully, <FALSE/>
 121              otherwise.
 122
 123         @param  xDictionary
 124             dictionary to be removed from the list of dictionaries.
 125
 126         @see    <type scope="com::sun::star::linguistic2">XDictionary</type>
 127     */
 128     boolean removeDictionary(
 129             [in] com::sun::star::linguistic2::XDictionary xDictionary );
 130
 131     //-------------------------------------------------------------------------
 132     /** adds an entry to the list of dictionary-list event listeners.
 133
 134         <P>On dictionary-list events, each entry in the listener list will
 135          be notified via a call to
 136         <member scope="com::sun::star::linguistic2">XDictionaryListEventListener::processDictionaryListEvent</member>.</P>
 137
 138         @returns
 139             <TRUE/> if the entry was made, <FALSE/> otherwise.
 140             If <member scope="com::sun::star::lang">XEventListener::disposing</member>
 141             was called before, it will always fail.
 142
 143         @param  xListener
 144             the object to be notified of dictionary-list events.
 145
 146         @param  bReceiveVerbose
 147             <TRUE/> if the listener requires more detailed event
 148             notification than usual.
 149
 150         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEventListener</type>
 151         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEvent</type>
 152     */
 153     boolean addDictionaryListEventListener(
 154         [in] com::sun::star::linguistic2::XDictionaryListEventListener xListener,
 155         [in] boolean bReceiveVerbose );
 156
 157     //-------------------------------------------------------------------------
 158     /** removes an entry from the list of dictionary-list event listeners.
 159
 160         @returns
 161             <TRUE/> if the object to be removed was found and removed,
 162             <FALSE/> otherwise.
 163
 164         @param  xListener
 165             the object to be removed from the listener list.
 166
 167         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEventListener</type>
 168         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEvent</type>
 169     */
 170     boolean removeDictionaryListEventListener(
 171         [in] com::sun::star::linguistic2::XDictionaryListEventListener xListener );
 172
 173     //-------------------------------------------------------------------------
 174     /** increases request level for event buffering by one.
 175
 176          <P>The request level for event buffering is an integer
 177          counter that is initially set to 0.
 178         As long as the request level is not 0, events will be buffered
 179          until the next flushing of the buffer.</P>
 180
 181         @returns
 182              the current request level for event buffering.
 183
 184         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEvent</type>
 185         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEventListener</type>
 186         @see    <member scope="com::sun::star::linguistic2">XDictionaryList::endCollectEvents</member>
 187         @see    <member scope="com::sun::star::linguistic2">XDictionaryList::flushEvents</member>
 188     */
 189     short beginCollectEvents();
 190
 191     //-------------------------------------------------------------------------
 192     /** flushes the event buffer and decreases the request level for
 193          event buffering by one.
 194
 195          <P>There should be one matching endCollectEvents call for every
 196          beginCollectEvents call. Usually you will group these around
 197          some code where you do not wish to get notfied of every single
 198          event.</P>
 199
 200         @returns
 201              the current request level for event buffering.
 202
 203         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEvent</type>
 204         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEventListener</type>
 205         @see    <member scope="com::sun::star::linguistic2">XDictionaryList::beginCollectEvents</member>
 206         @see    <member scope="com::sun::star::linguistic2">XDictionaryList::flushEvents</member>
 207     */
 208     short endCollectEvents();
 209
 210     //-------------------------------------------------------------------------
 211     /** notifies the listeners of all buffered events and then clears
 212          that buffer.
 213
 214         @returns
 215              the current request level for event buffering.
 216
 217         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEvent</type>
 218         @see    <type scope="com::sun::star::linguistic2">XDictionaryListEventListener</type>
 219         @see    <member scope="com::sun::star::linguistic2">XDictionaryList::beginCollectEvents</member>
 220         @see    <member scope="com::sun::star::linguistic2">XDictionaryList::endCollectEvents</member>
 221     */
 222     short flushEvents();
 223
 224     //-------------------------------------------------------------------------
 225     /** creates a new dictionary.
 226
 227         @returns
 228             an empty dictionary with the given name, language and type.
 229              <NULL/> on failure.
 230
 231         @param  aName
 232             is the name of the dictionary (should be unique).
 233
 234         @param  aLocale
 235             defines the language of the dictionary.
 236              Use an empty aLocale for dictionaries which may contain
 237             entries of all languages.
 238
 239         @param  eDicType
 240             specifies the type of the dictionary.
 241
 242          @param aURL
 243             is the URL of the location where the dictionary is persistent,
 244             if the XStorable interface is supported.
 245             It may be empty, which means the dictionary will not be persistent.
 246
 247         @see    <type scope="com::sun::star::linguistic2">XDictionary</type>
 248         @see    <type scope="com::sun::star::lang">Locale</type>
 249         @see    <type scope="com::sun::star::linguistic2">DictionaryType</type>
 250     */
 251     com::sun::star::linguistic2::XDictionary createDictionary(
 252             [in] string aName,
 253             [in] com::sun::star::lang::Locale aLocale,
 254             [in] com::sun::star::linguistic2::DictionaryType eDicType,
 255             [in] string aURL );
 256
 257 };
 258
 259 //=============================================================================
 260
 261 }; }; }; };
 262
 263 #endif
 264