offapi/com/sun/star/resource/XLocale.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_XLocale_idl__
  20 #define __com_sun_star_resource_XLocale_idl__
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23
  24 #include <com/sun/star/lang/Locale.idl>
  25
  26 #include <com/sun/star/resource/MissingResourceException.idl>
  27
  28
  29
  30  module com {  module sun {  module star {  module resource {
  31
  32 /** offers some operations on com::sun::star::lang::Locale
  33     structures.@see         XResourceBundle
  34         @see         Locale
  35  */
  36 published interface XLocale: com::sun::star::uno::XInterface
  37 {
  38     /** creates a locale from language, country, and variant.
  39
  40         <p>NOTE: ISO 639 is not a stable standard; some of the
  41         language codes it defines (specifically iw, ji, and in) have
  42         changed.  This constructor accepts both the old codes (iw, ji,
  43         and in) and the new codes (he, yi, and id), but all other API
  44         on XLocale will return only the <b>NEW</b> codes.
  45         </p>
  46         <p>Note: The Java class <code>Locale</code> returns the <strong>old</strong> codes.
  47
  48         </p>
  49      */
  50     com::sun::star::lang::Locale create( [in] string aLanguage,
  51              [in] string aCountry,
  52              [in] string aVariant );
  53
  54     /** the common method of getting the current default locale.
  55
  56         <p>It is used for the presentation (for menus, dialogs, etc.).
  57         It is, generally, set once when your applet or application is
  58         initialized, then never reset. (If you do reset the default
  59         locale, you probably want to reload your GUI, so that the
  60         change is reflected in your interface.)
  61         </p>
  62         <p>More advanced programs allow users to use different locales
  63         for different fields, for example, in a spreadsheet.
  64
  65         <br>Note that the initial setting will match the host system.</p>
  66      */
  67     com::sun::star::lang::Locale getDefault();
  68
  69     /** sets the default locale for the whole environment.
  70
  71         <p>It is normally set once at the beginning of an application,
  72         then never reset. <code>setDefault</code> does not reset the host
  73         locale.
  74
  75         </p>
  76      */
  77     void setDefault( [in] com::sun::star::lang::Locale newLocale );
  78
  79     /** @returns
  80                     a sequence of all locales which are available in the system.
  81      */
  82     sequence<com::sun::star::lang::Locale> getAvailableLocales();
  83
  84     /** @returns
  85                     a sequence of all ISO country codes known to the component.
  86      */
  87     sequence<string> getISOCountries();
  88
  89     /** @returns
  90                     a sequence of all ISO language codes known to the component.
  91      */
  92     sequence<string> getISOLanguages();
  93
  94     /** @returns
  95                     a sequence for language codes which are valid within the
  96                     given country.
  97      */
  98     sequence<string> getLanguagesForCountry( [in] string country );
  99
 100     /** @returns
 101                     the ISO language code for the specified locale.
 102      */
 103     string getISO3Language( [in] com::sun::star::lang::Locale locale )
 104             raises( com::sun::star::resource::MissingResourceException );
 105
 106     /** @returns
 107                     the ISO country code for the specified locale.
 108      */
 109     string getISO3Country( [in] com::sun::star::lang::Locale locale )
 110             raises( com::sun::star::resource::MissingResourceException );
 111
 112     /** @returns
 113                     language code for display of field to user. If the localized
 114                     name is not found, returns the ISO code. The desired user language
 115                     is from the default locale.
 116      */
 117     string getDisplayLanguage_Default( [in] com::sun::star::lang::Locale locale );
 118
 119
 120     /** @return
 121                     language code for display of field to user. If the localized
 122                     name is not found, returns the ISO codes.
 123
 124                 @param locale the locale.
 125
 126                 @param inLocale
 127                     specifies the desired user language.
 128      */
 129     string getDisplayLanguage( [in] com::sun::star::lang::Locale locale,
 130              [in] com::sun::star::lang::Locale inLocale );
 131
 132     /** @returns
 133                     country code for display of field to user. If the localized
 134                     name is not found, returns the ISO code. The desired user country
 135                     is from the default locale.
 136      */
 137     string getDisplayCountry_Default( [in] com::sun::star::lang::Locale locale );
 138
 139     /** @returns
 140                     country code for display of field to user. If the localized
 141                     name is not found, returns the ISO codes.
 142
 143                 @param locale the locale.
 144
 145                 @param inLocale
 146                     specifies the desired user country.
 147      */
 148     string getDisplayCountry( [in] com::sun::star::lang::Locale locale,
 149              [in] com::sun::star::lang::Locale inLocale );
 150
 151     /** @returns
 152                     variant code for display of field to user. The desired user variant
 153                     is from the default locale.
 154      */
 155     string getDisplayVariant_Default( [in] com::sun::star::lang::Locale locale );
 156
 157     /** @returns
 158                     variant code for display of field to user. If the localized
 159                     name is not found, returns the ISO codes.
 160
 161                 @param locale the locale.
 162
 163                 @param inLocale
 164                     specifies the desired user variant.
 165      */
 166     string getDisplayVariant( [in] com::sun::star::lang::Locale locale,
 167              [in] com::sun::star::lang::Locale inLocale );
 168
 169     /** @returns
 170                     a string to display the entire locale to user. If the localized
 171                     name is not found, uses the ISO codes. The default locale is used
 172                     for the presentation language.
 173
 174             @param locale the locale.
 175      */
 176     string getDisplayName_Default( [in] com::sun::star::lang::Locale locale );
 177
 178     /** @returns
 179                     a string to display the entire locale to user. If the localized
 180                     name is not found, uses the ISO codes.
 181
 182                 @param locale the locale.
 183
 184                 @param inLocale
 185                     specifies the desired user locale.
 186      */
 187     string getDisplayName( [in] com::sun::star::lang::Locale locale,
 188              [in] com::sun::star::lang::Locale inLocale );
 189
 190     /** @returns
 191                 `TRUE` if the com::sun::star::lang::Locale <var>l1</var> is equal to the
 192                 other one.
 193
 194                 <p>A locale is deemed equal to another locale with identical
 195                 language, country, and variant, and unequal to all other
 196                 objects.
 197      */
 198     boolean equals( [in] com::sun::star::lang::Locale l1,
 199              [in] com::sun::star::lang::Locale l2 );
 200
 201 };
 202
 203
 204 }; }; }; };
 205
 206 #endif
 207
 208 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */