1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_resource_XStringResourceResolver_idl__
24#define __com_sun_star_resource_XStringResourceResolver_idl__
25
26#ifndef __com_sun_star_resource_MissingResourceException_idl__
27#include <com/sun/star/resource/MissingResourceException.idl>
28#endif
29
30#ifndef __com_sun_star_util_XModifyBroadcaster_idl__
31#include <com/sun/star/util/XModifyBroadcaster.idl>
32#endif
33
34#ifndef __com_sun_star_lang_Locale_idl__
35#include <com/sun/star/lang/Locale.idl>
36#endif
37
38
39//=============================================================================
40
41module com { module sun { module star { module resource {
42
43//=============================================================================
44/**
45    Interface to access strings in a resource.
46
47    The interface is derived from
48    <type scope="com::sun::star::util">XModifyBroadcaster</type>
49
50    All registered <type scope="com::sun::star::util">XModifyListener</type>
51    interfaces will be notified if either the current locale changes or if
52    a string is added, changed or removed. This usually will only happen if
53    the implementing object also supports the interface
54    <type scope="com::sun::star::resource">XStringResourceManager</type>
55    and is used in the design mode of a Dialog or String table editor.
56    But also changing the locale at runtime can be supported in this way.
57
58*/
59published interface XStringResourceResolver: com::sun::star::util::XModifyBroadcaster
60{
61    /**
62        Resolves the passed ResoureID for the current locale. This
63        locale is set during initalisation of the object implementing
64        this interface or - in case that also the interface
65        <type scope="com::sun::star::resource">XStringResourceManager</type>
66        is supported - by using the <code>XStringResourceManager::setLocale</code>
67        method.
68
69        @param ResourceID
70            ID to specify the string inside the resource.
71            The ID can - but not needs to - be a hierarchical
72            name like "foo.nothing.invalid".
73
74        @return  the localized string for the specified ID
75
76        @throws ::com::sun::star::resource::MissingResourceException
77            if no entry exists for the given ResourceID
78    */
79    string resolveString( [in] string ResourceID )
80        raises( com::sun::star::resource::MissingResourceException );
81
82
83    /** Resolves the passed ResoureID for a specific locale.
84
85        It's not recommended to use this method to get the best
86        performance as the implementation may be optimized for
87        the use of the current locale.
88
89        @param ResourceID
90            ID to specify the string inside the resource.
91            The ID can - but not needs to - be a hierarchical
92            name like "foo.nothing.invalid".
93
94        @param locale
95            The locale the string should be resolved for.
96            The locale has to match exactly with one of the locales provided by
97            <member>getLocales</member>. A closest match search is not supported.
98
99        @return  the localized string for the specified ID and Locale
100
101        @throws <type scope="com::sun::star::resource">MissingResourceException</type>
102            if no entry exists for the given ResourceID or locale
103    */
104    string resolveStringForLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale )
105        raises( com::sun::star::resource::MissingResourceException );
106
107
108    /**
109        Checks if the resource contains an entry for the given ResourceID
110        and current locale.
111
112        @param ResourceID
113            ID to specify the string inside the resource.
114
115        @return  <TRUE/> if an entry exists, otherwise <FALSE/>
116
117    */
118    boolean hasEntryForId( [in] string ResourceID );
119
120
121    /**
122        Checks if the resource contains an entry for the given ResourceID and locale.
123
124        It's not recommended to use this method to get the best
125        performance as the implementation may be optimized for
126        the use of the current locale.
127
128        @param ResourceID
129            ID to specify the string inside the resource.
130
131        @param locale
132            The locale the entry should be checked for.
133            The locale has to match exactly with one of the locales provided by
134            <member>getLocales</member>. A closest match search is not supported.
135
136        @return  <TRUE/> if an entry exists, otherwise <FALSE/>
137    */
138    boolean hasEntryForIdAndLocale( [in] string ResourceID, [in] com::sun::star::lang::Locale locale );
139
140
141    /**
142        Returns a sequence of all valid Resource IDs for the current locale
143
144        @return  a sequence of all valid Resource IDs
145    */
146    sequence<string> getResourceIDs();
147
148
149    /**
150        Returns a sequence of all valid Resource IDs for a specific locale
151
152        It's not recommended to use this method to get the best
153        performance as the implementation may be optimized for
154        the use of the current locale.
155
156        @param locale
157            The locale the ResourceIDs should be returned for.
158            The locale has to match exactly with one of the locales provided by
159            <member>getLocales</member>. A closest match search is not supported.
160
161        @return  a sequence of all valid Resource IDs
162    */
163    sequence<string> getResourceIDsForLocale( [in] com::sun::star::lang::Locale locale );
164
165
166    /** Returns the current locale specified in the accessed resource.
167
168        If no locale is available, the returned Locale structure
169        only contains empty strings.
170
171        @returns  the used locale
172    */
173    com::sun::star::lang::Locale getCurrentLocale();
174
175
176    /** Returns the default locale of the accessed resource. In many
177        cases this will be the locale of the Office initially used
178        to create the resource.
179
180        @return  the used locale
181    */
182    com::sun::star::lang::Locale getDefaultLocale();
183
184
185    /**
186        Returns a sequence of all supported locales
187
188        @return  a sequence of all supported locales
189    */
190    sequence<com::sun::star::lang::Locale> getLocales();
191};
192
193//=============================================================================
194
195}; }; }; };
196
197#endif
198