offapi/com/sun/star/resource/XStringResourceManager.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: XStringResourceManager.idl,v $
  10  * $Revision: 1.3 $
  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_resource_XStringResourceManager_idl__
  31 #define __com_sun_star_resource_XStringResourceManager_idl__
  32
  33 #ifndef __com_sun_star_resource_MissingResourceException_idl__
  34 #include <com/sun/star/resource/MissingResourceException.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_resource_XStringResourceResolver_idl__
  38 #include <com/sun/star/resource/XStringResourceResolver.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_container_ElementExistException_idl__
  42 #include <com/sun/star/container/ElementExistException.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_lang_Locale_idl__
  46 #include <com/sun/star/lang/Locale.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  50 #include <com/sun/star/lang/IllegalArgumentException.idl>
  51 #endif
  52
  53 #ifndef __com_sun_star_lang_NoSupportException_idl__
  54 #include <com/sun/star/lang/NoSupportException.idl>
  55 #endif
  56
  57
  58 //=============================================================================
  59
  60 module com { module sun { module star { module resource {
  61
  62 //=============================================================================
  63 /**
  64     Interface to manage a resource string table containing a set of
  65     strings for different locales.
  66
  67     The interface is derived from
  68     <type scope="com::sun::star::resource">XStringResourceResolver</type>
  69     that allows to access the string table but not to modify it. This
  70     interface also allows to modify the string table.
  71
  72     It's designed to be used in the context of creating a string table,
  73     e.g. from a string table editor or from a Dialog Editor designing
  74     localized dialogs.
  75
  76 */
  77 interface XStringResourceManager: com::sun::star::resource::XStringResourceResolver
  78 {
  79     /**
  80         Returns the resource's read only state
  81
  82         @return  <TRUE/> if the resource is read only, otherwise <FALSE/>
  83     */
  84     boolean isReadOnly();
  85
  86
  87     /** Sets the locale to be used
  88
  89         @param aLocale
  90             Specifies the current locale to be used.
  91
  92         @param FindClosestMatch
  93             <p>If true: If the exact locale that should be set is not available
  94             the method tries to find the closest match. E.g. if en_US is re-
  95             quired but not available, en would be the next choice. Finally
  96             the default locale will be used <TRUE/>.
  97
  98             <p>If false: If the exact locale that should be set is not available
  99             a <type scope="com::sun::star::lang">IllegalArgumentException</type>
 100             is thrown.
 101
 102             <p>If false: If the exact locale that should be set is not available
 103             a <type scope="com::sun::star::lang">IllegalArgumentException</type>
 104             is thrown.
 105     */
 106     void setCurrentLocale
 107     (
 108         [in] com::sun::star::lang::Locale locale,
 109         [in] boolean FindClosestMatch
 110     )
 111     raises( com::sun::star::lang::IllegalArgumentException );
 112
 113
 114     /** Sets the default locale to be used
 115
 116         @param aLocale
 117             Specifies the default locale to be used.
 118             If this locale is not available a
 119             <type scope="com::sun::star::lang">IllegalArgumentException</type>
 120             is thrown.
 121
 122         @throws <type scope="com::sun::star::lang">NoSupportException</type>
 123             if the resource is read only, see <member>isReadOnly</member>
 124     */
 125     void setDefaultLocale( [in] com::sun::star::lang::Locale locale )
 126         raises( com::sun::star::lang::IllegalArgumentException,
 127                 com::sun::star::lang::NoSupportException );
 128
 129
 130     /**
 131         Associates a String to a Resource ID for the current locale.
 132         If an entry for the Resource ID already exists, the string
 133         associated with it will be overwritten, otherwise a new
 134         entry will be created.
 135
 136         @param ResourceID
 137             ID to address the string inside the resource for the current locale.
 138
 139         @param Str
 140             String to be associated with the Resource ID.
 141
 142         @throws <type scope="com::sun::star::lang">NoSupportException</type>
 143             if the resource is read only, see <member>isReadOnly</member>
 144     */
 145     void setString
 146     (
 147         [in] string ResourceID,
 148         [in] string Str
 149     )
 150     raises( com::sun::star::lang::NoSupportException );
 151
 152
 153     /**
 154         Associates a String to a Resource ID for a specific locale.
 155         If an entry for the Resource ID already exists, the string
 156         associated with it will be overwritten, otherwise a new
 157         entry will be created.
 158
 159         It's not recommended to use this method to get the best
 160         performance as the implementation may be optimized for
 161         the use of the current locale.
 162
 163         @param ResourceID
 164             ID to address the string inside the resource.
 165
 166         @param Str
 167             String to be associated with the Resource ID.
 168
 169         @param locale
 170             The locale the string should be set for.
 171             The locale has to match exactly with one of the locales provided by
 172             <member>getLocales</member>. A closest match search is not supported.
 173
 174         @throws <type scope="com::sun::star::lang">NoSupportException</type>
 175             if the resource is read only, see <member>isReadOnly</member>
 176     */
 177     void setStringForLocale
 178     (
 179         [in] string ResourceID,
 180         [in] string Str,
 181         [in] com::sun::star::lang::Locale locale
 182     )
 183     raises( com::sun::star::lang::NoSupportException );
 184
 185
 186     /**
 187         Removes a Resource ID including the corresponding string for
 188         the current locale.
 189
 190         @param ResourceID
 191             The Resource ID to be removed for the current locale.
 192
 193         @throws
 194         <type scope="com::sun::star::resource">MissingResourceException</type>
 195         if the Resource ID is not valid.
 196
 197         @throws
 198         <type scope="com::sun::star::lang">NoSupportException</type>
 199         if the resource is read only, see <member>isReadOnly</member>
 200     */
 201     void removeId( [in] string ResourceID )
 202         raises( com::sun::star::resource::MissingResourceException,
 203                 com::sun::star::lang::NoSupportException );
 204
 205
 206     /**
 207         Removes a Resource ID including the corresponding string for
 208         s specific locale.
 209
 210         @param ResourceID
 211             The Resource ID to be removed.
 212
 213         @param locale
 214             The locale the Resource ID should be removed for.
 215             The locale has to match exactly with one of the locales provided by
 216             <member>getLocales</member>. A closest match search is not supported.
 217
 218         @throws
 219         <type scope="com::sun::star::resource">MissingResourceException</type>
 220         if the Resource ID is not valid.
 221
 222         @throws
 223         <type scope="com::sun::star::lang">NoSupportException</type>
 224         if the resource is read only, see <member>isReadOnly</member>
 225     */
 226     void removeIdForLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale )
 227         raises( com::sun::star::resource::MissingResourceException,
 228                 com::sun::star::lang::NoSupportException );
 229
 230
 231     /**
 232         Creates a new locale.
 233
 234         <p>For each existing ResourceID an empty string
 235         will be created. The first locale created will
 236         automatically be the first default locale.
 237         Otherwise strings for all already created IDs
 238         will be copied from the default locale.</p>
 239
 240         @throws
 241         <type scope="com::sun::star::container">ElementExistException</type>
 242         if the Locale already has been created.
 243
 244         @throws
 245         <type scope="com::sun::star::lang">IllegalArgumentException</type>
 246         if the Locale is not valid.
 247
 248         @throws
 249         <type scope="com::sun::star::lang">NoSupportException</type>
 250         if the resource is read only, see <member>isReadOnly</member>
 251     */
 252     void newLocale( [in] com::sun::star::lang::Locale locale )
 253         raises( com::sun::star::container::ElementExistException,
 254                 com::sun::star::lang::IllegalArgumentException,
 255                 com::sun::star::lang::NoSupportException );
 256
 257
 258     /**
 259         Removes a locale completely including the corresponding
 260         strings for each locale.
 261
 262         @throws
 263         <type scope="com::sun::star::lang">IllegalArgumentException</type>
 264         if the Locale to be removed is not supported.
 265
 266         @throws
 267         <type scope="com::sun::star::lang">NoSupportException</type>
 268         if the resource is read only, see <member>isReadOnly</member>
 269     */
 270     void removeLocale( [in] com::sun::star::lang::Locale locale )
 271         raises( com::sun::star::lang::IllegalArgumentException,
 272                 com::sun::star::lang::NoSupportException );
 273
 274
 275     /**
 276         Provides a numeric id that is unique within all Resource IDs
 277         used in the string table.
 278
 279         This method takes into account all Resource IDs starting with
 280         a decimal number and only evaluates the ID until the first non
 281         digit character is reached. This allows to extend unique IDs
 282         with individual identifiers without breaking the mechanism of
 283         this method.
 284
 285         Examples:
 286         ID "42" -> numeric id 42
 287         ID "0foo" -> numeric id 0
 288         ID "111.MyId.Something.Else" -> numeric id 111
 289         ID "No Digits" -> not considered for numeric id
 290
 291         The id returned will be 0 for an empty string table and it will
 292         be reset to 0 if all locales are removed. In all other cases
 293         this method returns the maximum numeric id used so far at the
 294         beginning of a Resource ID incremented by 1. When calling this
 295         method more than once always the same number will be returned
 296         until this number is really used at the beginning of a new
 297         Resource ID passed to <member>setString</member> or
 298         <member>setStringForLocale</member>.
 299
 300         As the numeric id is guaranteed to be unique for the complete
 301         string table all locales are taken into account. So using this
 302         methods will force the implementation to load all locale data
 303         that may not have been loaded so far.
 304
 305         @throws
 306         <type scope="com::sun::star::lang">NoSupportException</type>
 307         if the next available id exceeds the range of type long.
 308         So it's not recommended to use own Resource IDs starting
 309         with a decimal number near to the maximum long value if
 310         this methods should be used.
 311     */
 312     long getUniqueNumericId()
 313         raises( com::sun::star::lang::NoSupportException );
 314 };
 315
 316 //=============================================================================
 317
 318 }; }; }; };
 319
 320 #endif