| /************************************************************** |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| #ifndef __com_sun_star_resource_XResourceBundle_idl__ |
| #define __com_sun_star_resource_XResourceBundle_idl__ |
| |
| #ifndef __com_sun_star_container_XNameAccess_idl__ |
| #include <com/sun/star/container/XNameAccess.idl> |
| #endif |
| |
| #ifndef __com_sun_star_lang_Locale_idl__ |
| #include <com/sun/star/lang/Locale.idl> |
| #endif |
| |
| |
| //============================================================================= |
| |
| module com { module sun { module star { module resource { |
| |
| //============================================================================= |
| /** Resource bundles contain locale-specific objects. |
| |
| <p>When your program needs a locale-specific resource, such as |
| <code>String</code> for example, your program can load it from the |
| resource bundle that is appropriate for the current user's locale. In |
| this way, you can write program code that is largely independent of |
| the user's locale, which isolates most, if not all, of the |
| locale-specific information in resource bundles. |
| |
| <p>This allows you to write programs that can: |
| |
| <UL type=SQUARE> |
| |
| <LI> be easily localized, or translated, into different |
| languages. |
| |
| <LI> handle multiple locales at once. |
| |
| <LI> be easily modified, later, to support even more locales. |
| |
| </UL> |
| |
| <P> One resource bundle is, conceptually, a set of related services |
| that supports <code>XResourceBundle</code>. Each related service of |
| <code>XResourceBundle</code> has the same base name plus an |
| additional component that identifies its locale. For example, suppose |
| your resource bundle is named <code>MyResources</code>. The first |
| service you are likely to implement is the default resource bundle, |
| which has the same name as its family--<code>MyResources</code>. You |
| can also provide as many related locale-specific services as you need. |
| |
| For example, perhaps you would provide a German one named |
| <code>MyResources_de</code>. |
| |
| <P> |
| Each related implementation of <code>XResourceBundle</code> contains |
| the same items, but the items have been translated for the locale |
| represented by that <code>XResourceBundle</code> implementation. For |
| example, both <code>MyResources</code> and <code>MyResources_de</code> |
| may have a <code>String</code> that is used on a button for |
| confirming operations. In <code>MyResources</code> the |
| <code>String</code> may contain <code>OK</code> and in |
| <code>MyResources_de</code> it may contain <code>Gut</code>. |
| |
| <P> |
| If there are different resources for different countries, you |
| can make specializations: for example, <code>MyResources_de_CH</code> |
| is the German language (de) in Switzerland (CH). If you only want to |
| modify some of the resources in the specialization, you can do so. |
| |
| <P> |
| When your program needs a locale-specific object, it loads |
| |
| the <code>XResourceBundle</code> implementation using the |
| <type>XResourceBundleLoader</type> service: |
| |
| <listing> |
| XResourceBundle myResources = xLoader.getBundle("MyResources", currentLocale); |
| </listing> |
| |
| <p>The first argument specifies the family name of the resource |
| bundle that contains the object in question. The second argument |
| indicates the desired locale. <code>getBundle</code> uses these two |
| arguments to construct the name of the <code>ResourceBundle</code> |
| subclass it should load according to the following specifications. |
| |
| <P>The resource bundle lookup searches for services with various |
| suffixes on the basis of (1) the desired locale and (2) the current |
| default locale as returned by Locale.getDefault(), and (3) the root |
| resource bundle (baseclass), in the following order from lower-level |
| (more specific) to parent-level (less specific): |
| <p> baseclass + "_" + language1 + "_" + country1 + "_" + variant1 |
| <BR> baseclass + "_" + language1 + "_" + country1 |
| <BR> baseclass + "_" + language1 |
| <BR> baseclass + "_" + language2 + "_" + country2 + "_" + variant2 |
| <BR> baseclass + "_" + language2 + "_" + country2 |
| <BR> baseclass + "_" + language2 |
| <BR> baseclass |
| |
| <P> For example, if the current default locale is <TT>en_US</TT>, the |
| locale that the caller is interested in is <TT>fr_CH</TT>, and the |
| resource bundle name is <TT>MyResources</TT>; resource bundle lookup |
| will search for the following services, in order: |
| <BR> <TT>MyResources_fr_CH |
| <BR> MyResources_fr |
| <BR> MyResources_en_US |
| <BR> MyResources_en |
| <BR> MyResources</TT> |
| |
| <P> The result of the lookup is a service, but that service may be |
| backed by a property file on disk. If a lookup fails, |
| <code>getBundle()</code> throws a |
| <code>MissingResourceException</code>. |
| |
| <P> The base service <strong>must</strong> be fully qualified (for |
| example, <code>myPackage::MyResources</code>, not just |
| <code>MyResources</code>). |
| |
| <P> Resource bundles contain key/value pairs. The keys uniquely |
| identify a locale-specific object in the bundle. Here is an |
| example of a <code>XResourceBundle</code> implementation that contains |
| two key/value pairs: |
| |
| <listing> |
| class MyResource extends com.sun.star.resource.XResourceBundle |
| { |
| // some queryInterface stuff |
| // ... |
| public final Object getDirectElement(String key) |
| { |
| if (key.equals("okKey")) return "Ok"; |
| if (key.equals("cancelKey")) return "Cancel"; |
| return null; |
| } |
| } |
| </listing> |
| |
| <p>Keys are always <code>String</code>s. In this example, the keys |
| are <code>OkKey</code> and <code>CancelKey</code>. In the above |
| example, the values are also <code>String</code>s--<code>OK</code> |
| and <code>Cancel</code>--but they do not have to be. The values can |
| be any type of object. |
| |
| <P> You retrieve an object from resource bundle using the appropriate |
| get method. Because <code>OkKey</code> and <code>CancelKey</code> |
| are both strings, you use <code>getByName</code> to retrieve them: |
| |
| <listing> |
| button1 = new Button(myResourceBundle.getByName("OkKey").getString()); |
| button2 = new Button(myResourceBundle.getByName("CancelKey").getString()); |
| </listing> |
| |
| <p>The get methods all require the key as an argument and return |
| the object if found. If the object is not found, the get methods |
| throw a <type scope="com::sun::star::container">NoSuchElementException</type>. |
| |
| <P> <STRONG>NOTE:</STRONG> You should always supply a base service |
| with no suffixes. This will be the class of "last resort" if a |
| locale is requested that does not exist. In fact, you must provide |
| <I>all</I> of the services in any given inheritance chain for which |
| you provide a resource. For example, if you provide |
| <TT>MyResources_fr_BE</TT>, you must provide <I>both</I> |
| <TT>MyResources</TT> <I>and</I> <TT>MyResources_fr</TT>, or the |
| resource bundle lookup will not work right. |
| |
| <P>You do not have to restrict yourself to using a single family of |
| <code>ResourceBundle</code>s. For example, you could have a set of |
| bundles for exception messages, <code>ExceptionResources</code> |
| (<code>ExceptionResources_fr</code>, <code>ExceptionResources_de</code>, ...), |
| and one for widgets, <code>WidgetResource</code> (<code>WidgetResources_fr</code>, |
| <code>WidgetResources_de</code>, ...); breaking up the resources however you like. |
| |
| @see MissingResourceException |
| @see Locale |
| @version 0.1 26 May 1999 |
| @author Mark Davis |
| @author Markus Meyer |
| @deprecated draft |
| */ |
| published interface XResourceBundle: com::sun::star::container::XNameAccess |
| { |
| //------------------------------------------------------------------------- |
| /** contains the parent bundle of this bundle. |
| |
| <p>The parent bundle is searched by the method |
| <method scope="com::sun::star::container">XNameAccess::getByName</method> |
| when this bundle does not contain a particular resource. |
| */ |
| [attribute] XResourceBundle Parent; |
| |
| //------------------------------------------------------------------------- |
| /** @returns |
| the locale for this resource bundle. |
| |
| <p>This function can be used to determine whether the |
| resource bundle that is returned really corresponds to the |
| requested locale or is a fallback. |
| |
| */ |
| com::sun::star::lang::Locale getLocale(); |
| |
| //------------------------------------------------------------------------- |
| /** @returns |
| an object from a resource bundle or NULL if no resource |
| exists. |
| |
| <p>It does not look in the parents. |
| |
| @param key |
| specifies the element. |
| */ |
| any getDirectElement( [in] string key ); |
| |
| }; |
| |
| //============================================================================= |
| |
| }; }; }; }; |
| |
| #endif |