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