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_XStringResourceResolver_idl__
28#define __com_sun_star_resource_XStringResourceResolver_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_util_XModifyBroadcaster_idl__
35#include <com/sun/star/util/XModifyBroadcaster.idl>
36#endif
37
38#ifndef __com_sun_star_lang_Locale_idl__
39#include <com/sun/star/lang/Locale.idl>
40#endif
41
42
43//=============================================================================
44
45module com { module sun { module star { module resource {
46
47//=============================================================================
48/**
49    Interface to access strings in a resource.
50
51    The interface is derived from
52    <type scope="com::sun::star::util">XModifyBroadcaster</type>
53
54    All registered <type scope="com::sun::star::util">XModifyListener</type>
55    interfaces will be notified if either the current locale changes or if
56    a string is added, changed or removed. This usually will only happen if
57    the implementing object also supports the interface
58    <type scope="com::sun::star::resource">XStringResourceManager</type>
59    and is used in the design mode of a Dialog or String table editor.
60    But also changing the locale at runtime can be supported in this way.
61
62*/
63published interface XStringResourceResolver: com::sun::star::util::XModifyBroadcaster
64{
65    /**
66        Resolves the passed ResoureID for the current locale. This
67        locale is set during initalisation of the object implementing
68        this interface or - in case that also the interface
69        <type scope="com::sun::star::resource">XStringResourceManager</type>
70        is supported - by using the <code>XStringResourceManager::setLocale</code>
71        method.
72
73        @param ResourceID
74            ID to specify the string inside the resource.
75            The ID can - but not needs to - be a hierarchical
76            name like "foo.nothing.invalid".
77
78        @return  the localized string for the specified ID
79
80        @throws ::com::sun::star::resource::MissingResourceException
81            if no entry exists for the given ResourceID
82    */
83    string resolveString( [in] string ResourceID )
84        raises( com::sun::star::resource::MissingResourceException );
85
86
87    /** Resolves the passed ResoureID for a specific locale.
88
89        It's not recommended to use this method to get the best
90        performance as the implementation may be optimized for
91        the use of the current locale.
92
93        @param ResourceID
94            ID to specify the string inside the resource.
95            The ID can - but not needs to - be a hierarchical
96            name like "foo.nothing.invalid".
97
98        @param locale
99            The locale the string should be resolved for.
100            The locale has to match exactly with one of the locales provided by
101            <member>getLocales</member>. A closest match search is not supported.
102
103        @return  the localized string for the specified ID and Locale
104
105        @throws <type scope="com::sun::star::resource">MissingResourceException</type>
106            if no entry exists for the given ResourceID or locale
107    */
108    string resolveStringForLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale )
109        raises( com::sun::star::resource::MissingResourceException );
110
111
112    /**
113        Checks if the resource contains an entry for the given ResourceID
114        and current locale.
115
116        @param ResourceID
117            ID to specify the string inside the resource.
118
119        @return  <TRUE/> if an entry exists, otherwise <FALSE/>
120
121    */
122    boolean hasEntryForId( [in] string ResourceID );
123
124
125    /**
126        Checks if the resource contains an entry for the given ResourceID and locale.
127
128        It's not recommended to use this method to get the best
129        performance as the implementation may be optimized for
130        the use of the current locale.
131
132        @param ResourceID
133            ID to specify the string inside the resource.
134
135        @param locale
136            The locale the entry should be checked for.
137            The locale has to match exactly with one of the locales provided by
138            <member>getLocales</member>. A closest match search is not supported.
139
140        @return  <TRUE/> if an entry exists, otherwise <FALSE/>
141    */
142    boolean hasEntryForIdAndLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale );
143
144
145    /**
146        Returns a sequence of all valid Resource IDs for the current locale
147
148        @return  a sequence of all valid Resource IDs
149    */
150    sequence<string> getResourceIDs();
151
152
153    /**
154        Returns a sequence of all valid Resource IDs for a specific locale
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 locale
161            The locale the ResourceIDs should be returned for.
162            The locale has to match exactly with one of the locales provided by
163            <member>getLocales</member>. A closest match search is not supported.
164
165        @return  a sequence of all valid Resource IDs
166    */
167    sequence<string> getResourceIDsForLocale( [in] com::sun::star::lang::Locale locale );
168
169
170    /** Returns the current locale specified in the accessed resource.
171
172        If no locale is available, the returned Locale structure
173        only contains empty strings.
174
175        @returns  the used locale
176    */
177    com::sun::star::lang::Locale getCurrentLocale();
178
179
180    /** Returns the default locale of the accessed resource. In many
181        cases this will be the locale of the Office initially used
182        to create the resource.
183
184        @return  the used locale
185    */
186    com::sun::star::lang::Locale getDefaultLocale();
187
188
189    /**
190        Returns a sequence of all supported locales
191
192        @return  a sequence of all supported locales
193    */
194    sequence<com::sun::star::lang::Locale> getLocales();
195};
196
197//=============================================================================
198
199}; }; }; };
200
201#endif
202