offapi/com/sun/star/resource/XResourceBundle.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_resource_XResourceBundle_idl__
  20 #define __com_sun_star_resource_XResourceBundle_idl__
  21
  22 #include <com/sun/star/container/XNameAccess.idl>
  23 #include <com/sun/star/lang/Locale.idl>
  24
  25
  26
  27 module com { module sun { module star { module resource {
  28
  29 /** Resource bundles contain locale-specific objects.
  30
  31     <p>When your program needs a locale-specific resource, such as
  32     <code>String</code> for example, your program can load it from the
  33     resource bundle that is appropriate for the current user's locale. In
  34     this way, you can write program code that is largely independent of
  35     the user's locale, which isolates most, if not all, of the
  36     locale-specific information in resource bundles.
  37
  38     <p>This allows you to write programs that can:
  39
  40     <UL type=SQUARE>
  41
  42     <LI> be easily localized, or translated, into different
  43     languages.
  44
  45     <LI> handle multiple locales at once.
  46
  47     <LI> be easily modified, later, to support even more locales.
  48
  49     </UL>
  50
  51     <P> One resource bundle is, conceptually, a set of related services
  52     that supports <code>XResourceBundle</code>. Each related service of
  53     <code>XResourceBundle</code> has the same base name plus an
  54     additional component that identifies its locale. For example, suppose
  55     your resource bundle is named <code>MyResources</code>. The first
  56     service you are likely to implement is the default resource bundle,
  57     which has the same name as its family--<code>MyResources</code>. You
  58     can also provide as many related locale-specific services as you need.
  59
  60     For example, perhaps you would provide a German one named
  61     <code>MyResources_de</code>.
  62
  63     <P>
  64     Each related implementation of <code>XResourceBundle</code> contains
  65     the same items, but the items have been translated for the locale
  66     represented by that <code>XResourceBundle</code> implementation. For
  67     example, both <code>MyResources</code> and <code>MyResources_de</code>
  68     may have a <code>String</code> that is used on a button for
  69     confirming operations. In <code>MyResources</code> the
  70     <code>String</code> may contain <code>OK</code> and in
  71     <code>MyResources_de</code> it may contain <code>Gut</code>.
  72
  73     <P>
  74     If there are different resources for different countries, you
  75     can make specializations: for example, <code>MyResources_de_CH</code>
  76     is the German language (de) in Switzerland (CH). If you only want to
  77     modify some of the resources in the specialization, you can do so.
  78
  79     <P>
  80     When your program needs a locale-specific object, it loads
  81
  82     the <code>XResourceBundle</code> implementation using the
  83     XResourceBundleLoader service:
  84
  85     @code{.java}
  86     XResourceBundle myResources = xLoader.getBundle("MyResources", currentLocale);
  87     @endcode
  88
  89     <p>The first argument specifies the family name of the resource
  90     bundle that contains the object in question. The second argument
  91     indicates the desired locale. <code>getBundle</code> uses these two
  92     arguments to construct the name of the <code>ResourceBundle</code>
  93     subclass it should load according to the following specifications.
  94
  95     <P>The resource bundle lookup searches for services with various
  96     suffixes on the basis of (1) the desired locale and (2) the current
  97     default locale as returned by Locale.getDefault(), and (3) the root
  98     resource bundle (baseclass), in the following order from lower-level
  99     (more specific) to parent-level (less specific):
 100     <p> baseclass + "_" + language1 + "_" + country1 + "_" + variant1
 101     <BR> baseclass + "_" + language1 + "_" + country1
 102     <BR> baseclass + "_" + language1
 103     <BR> baseclass + "_" + language2 + "_" + country2 + "_" + variant2
 104     <BR> baseclass + "_" + language2 + "_" + country2
 105     <BR> baseclass + "_" + language2
 106     <BR> baseclass
 107
 108     <P> For example, if the current default locale is <TT>en_US</TT>, the
 109     locale that the caller is interested in is <TT>fr_CH</TT>, and the
 110     resource bundle name is <TT>MyResources</TT>; resource bundle lookup
 111     will search for the following services, in order:
 112     <BR> <TT>MyResources_fr_CH
 113     <BR> MyResources_fr
 114     <BR> MyResources_en_US
 115     <BR> MyResources_en
 116     <BR> MyResources</TT>
 117
 118     <P> The result of the lookup is a service, but that service may be
 119     backed by a property file on disk. If a lookup fails,
 120     <code>getBundle()</code> throws a
 121     <code>MissingResourceException</code>.
 122
 123     <P> The base service <strong>must</strong> be fully qualified (for
 124     example, <code>myPackage::MyResources</code>, not just
 125     <code>MyResources</code>).
 126
 127     <P> Resource bundles contain key/value pairs. The keys uniquely
 128     identify a locale-specific object in the bundle. Here is an
 129     example of a <code>XResourceBundle</code> implementation that contains
 130     two key/value pairs:
 131
 132     @code{.java}
 133     class MyResource extends com.sun.star.resource.XResourceBundle
 134     {
 135         // some queryInterface stuff
 136
 137         public final Object getDirectElement(String key)
 138         {
 139             if (key.equals("okKey")) return "Ok";
 140             if (key.equals("cancelKey")) return "Cancel";
 141             return null;
 142         }
 143     }
 144     @endcode
 145
 146     <p>Keys are always <code>String</code>s. In this example, the keys
 147     are <code>OkKey</code> and <code>CancelKey</code>. In the above
 148     example, the values are also <code>String</code>s--<code>OK</code>
 149     and <code>Cancel</code>--but they do not have to be. The values can
 150     be any type of object.
 151
 152     <P> You retrieve an object from resource bundle using the appropriate
 153     get method. Because <code>OkKey</code> and <code>CancelKey</code>
 154     are both strings, you use <code>getByName</code> to retrieve them:
 155
 156     @code{.java}
 157     button1 = new Button(myResourceBundle.getByName("OkKey").getString());
 158     button2 = new Button(myResourceBundle.getByName("CancelKey").getString());
 159     @endcode
 160
 161     <p>The get methods all require the key as an argument and return
 162     the object if found. If the object is not found, the get methods
 163     throw a com::sun::star::container::NoSuchElementException.
 164
 165     <P> <STRONG>NOTE:</STRONG> You should always supply a base service
 166     with no suffixes. This will be the class of "last resort" if a
 167     locale is requested that does not exist. In fact, you must provide
 168     <I>all</I> of the services in any given inheritance chain for which
 169     you provide a resource.  For example, if you provide
 170     <TT>MyResources_fr_BE</TT>, you must provide <I>both</I>
 171     <TT>MyResources</TT> <I>and</I> <TT>MyResources_fr</TT>, or the
 172     resource bundle lookup will not work right.
 173
 174     <P>You do not have to restrict yourself to using a single family of
 175     <code>ResourceBundle</code>s. For example, you could have a set of
 176     bundles for exception messages, <code>ExceptionResources</code>
 177     (<code>ExceptionResources_fr</code>, <code>ExceptionResources_de</code>, ...),
 178     and one for widgets, <code>WidgetResource</code> (<code>WidgetResources_fr</code>,
 179     <code>WidgetResources_de</code>, ...); breaking up the resources however you like.
 180
 181     @see        MissingResourceException
 182     @see         Locale
 183     @version     0.1 26 May 1999
 184     @author      Mark Davis
 185     @author      Markus Meyer
 186     @deprecated draft
 187 */
 188 published interface XResourceBundle: com::sun::star::container::XNameAccess
 189 {
 190     /** contains the parent bundle of this bundle.
 191
 192         <p>The parent bundle is searched by the method
 193         com::sun::star::container::XNameAccess::getByName()
 194         when this bundle does not contain a particular resource.
 195      */
 196     [attribute] XResourceBundle Parent;
 197
 198     /** @returns
 199         the locale for this resource bundle.
 200
 201         <p>This function can be used to determine whether the
 202         resource bundle that is returned really corresponds to the
 203         requested locale or is a fallback.
 204
 205     */
 206     com::sun::star::lang::Locale getLocale();
 207
 208     /** @returns
 209         an object from a resource bundle or NULL if no resource
 210         exists.
 211
 212         <p>It does not look in the parents.
 213
 214         @param key
 215             specifies the element.
 216     */
 217     any getDirectElement( [in] string key );
 218
 219 };
 220
 221
 222 }; }; }; };
 223
 224 #endif
 225
 226 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */