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 28 #ifndef _RTL_LOCALE_HXX_ 29 #define _RTL_LOCALE_HXX_ 30 31 #include <rtl/locale.h> 32 #include <rtl/ustring.hxx> 33 34 #ifdef __cplusplus 35 36 namespace rtl 37 { 38 39 /** 40 A <code>OLocale</code> object represents a specific geographical, political, 41 or cultural region. An operation that requires a <code>OLocale</code> to perform 42 its task is called <em>locale-sensitive</em> and uses the <code>OLocale</code> 43 to tailor information for the user. For example, displaying a number 44 is a locale-sensitive operation--the number should be formatted 45 according to the customs/conventions of the user's native country, 46 region, or culture. 47 48 <P> 49 You create a <code>OLocale</code> object using one of the two constructors in 50 this class: 51 <blockquote> 52 <pre> 53 OLocale(String language, String country) 54 OLocale(String language, String country, String variant) 55 </pre> 56 </blockquote> 57 The first argument to both constructors is a valid <STRONG>ISO 58 Language Code.</STRONG> These codes are the lower-case two-letter 59 codes as defined by ISO-639. 60 You can find a full list of these codes at a number of sites, such as: 61 <BR><a href ="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt"> 62 <code>http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</code></a> 63 64 <P> 65 The second argument to both constructors is a valid <STRONG>ISO Country 66 Code.</STRONG> These codes are the upper-case two-letter codes 67 as defined by ISO-3166. 68 You can find a full list of these codes at a number of sites, such as: 69 <BR><a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html"> 70 <code>http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html</code></a> 71 72 <P> 73 The second constructor requires a third argument--the <STRONG>Variant.</STRONG> 74 The Variant codes are vendor and browser-specific. 75 For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX. 76 Where there are two variants, separate them with an underscore, and 77 put the most important one first. For 78 example, a Traditional Spanish collation might be referenced, with 79 "ES", "ES", "Traditional_WIN". 80 81 <P> 82 Because a <code>OLocale</code> object is just an identifier for a region, 83 no validity check is performed when you construct a <code>OLocale</code>. 84 If you want to see whether particular resources are available for the 85 <code>OLocale</code> you construct, you must query those resources. For 86 example, ask the <code>NumberFormat</code> for the locales it supports 87 using its <code>getAvailableLocales</code> method. 88 <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular 89 locale, you get back the best available match, not necessarily 90 precisely what you asked for. For more information, look at 91 <a href="java.util.ResourceBundle.html"><code>ResourceBundle</code></a>. 92 93 <P> 94 The <code>OLocale</code> class provides a number of convenient constants 95 that you can use to create <code>OLocale</code> objects for commonly used 96 locales. For example, the following creates a <code>OLocale</code> object 97 for the United States: 98 <blockquote> 99 <pre> 100 OLocale.US 101 </pre> 102 </blockquote> 103 104 <P> 105 Once you've created a <code>OLocale</code> you can query it for information about 106 itself. Use <code>getCountry</code> to get the ISO Country Code and 107 <code>getLanguage</code> to get the ISO Language Code. You can 108 use <code>getDisplayCountry</code> to get the 109 name of the country suitable for displaying to the user. Similarly, 110 you can use <code>getDisplayLanguage</code> to get the name of 111 the language suitable for displaying to the user. Interestingly, 112 the <code>getDisplayXXX</code> methods are themselves locale-sensitive 113 and have two versions: one that uses the default locale and one 114 that uses the locale specified as an argument. 115 116 <P> 117 The JDK provides a number of classes that perform locale-sensitive 118 operations. For example, the <code>NumberFormat</code> class formats 119 numbers, currency, or percentages in a locale-sensitive manner. Classes 120 such as <code>NumberFormat</code> have a number of convenience methods 121 for creating a default object of that type. For example, the 122 <code>NumberFormat</code> class provides these three convenience methods 123 for creating a default <code>NumberFormat</code> object: 124 <blockquote> 125 <pre> 126 NumberFormat.getInstance() 127 NumberFormat.getCurrencyInstance() 128 NumberFormat.getPercentInstance() 129 </pre> 130 </blockquote> 131 These methods have two variants; one with an explicit locale 132 and one without; the latter using the default locale. 133 <blockquote> 134 <pre> 135 NumberFormat.getInstance(myLocale) 136 NumberFormat.getCurrencyInstance(myLocale) 137 NumberFormat.getPercentInstance(myLocale) 138 </pre> 139 </blockquote> 140 A <code>OLocale</code> is the mechanism for identifying the kind of object 141 (<code>NumberFormat</code>) that you would like to get. The locale is 142 <STRONG>just</STRONG> a mechanism for identifying objects, 143 <STRONG>not</STRONG> a container for the objects themselves. 144 145 <P> 146 Each class that performs locale-sensitive operations allows you 147 to get all the available objects of that type. You can sift 148 through these objects by language, country, or variant, 149 and use the display names to present a menu to the user. 150 For example, you can create a menu of all the collation objects 151 suitable for a given language. Such classes must implement these 152 three class methods: 153 <blockquote> 154 <pre> 155 public static OLocale[] getAvailableLocales() 156 public static String getDisplayName(OLocale objectLocale, 157 OLocale displayLocale) 158 public static final String getDisplayName(OLocale objectLocale) 159 // getDisplayName will throw MissingResourceException if the locale 160 // is not one of the available locales. 161 </pre> 162 </blockquote> 163 */ 164 class OLocale 165 { 166 public: 167 OLocale( rtl_Locale * locale ) 168 : pData( locale ) {} 169 170 OLocale( const OLocale & obj) 171 : pData(obj.pData) {} 172 173 OLocale & operator = ( const OLocale & obj) 174 { 175 pData = obj.pData; 176 return *this; 177 } 178 179 /** 180 Construct a locale from language, country, variant. 181 @param language lowercase two-letter ISO-639 code. 182 @param country uppercase two-letter ISO-3166 code. 183 @param variant vendor and browser specific code. See class description. 184 */ 185 static OLocale registerLocale( const OUString & language, const OUString & country, 186 const OUString & variant ) 187 { 188 return rtl_locale_register( language, country, variant ); 189 } 190 191 /** 192 Construct a locale from language, country. 193 @param language lowercase two-letter ISO-639 code. 194 @param country uppercase two-letter ISO-3166 code. 195 */ 196 static OLocale registerLocale( const OUString & language, const OUString & country ) 197 { 198 return rtl_locale_register( language, country, NULL ); 199 } 200 201 /** @deprecated 202 */ 203 static OLocale getDefault() { return rtl_locale_getDefault(); } 204 205 /** @deprecated 206 */ 207 static void setDefault( const OUString & language, const OUString & country, 208 const OUString & variant ) 209 { rtl_locale_setDefault(language, country, variant); } 210 211 /** 212 Getter for programmatic name of field, 213 an lowercased two-letter ISO-639 code. 214 */ 215 OUString getLanguage() const { return pData->Language; } 216 217 /** 218 Getter for programmatic name of field, 219 an uppercased two-letter ISO-3166 code. 220 */ 221 OUString getCountry() const { return pData->Country; } 222 223 /** 224 Getter for programmatic name of field. 225 */ 226 OUString getVariant() const { return pData->Variant; } 227 228 229 /** 230 Returns the hash code of the locale This. 231 */ 232 sal_Int32 hashCode() const { return pData->HashCode; } 233 234 sal_Bool operator == (const OLocale & obj ) const 235 { 236 return pData == obj.pData; 237 } 238 239 rtl_Locale * getData() const { return pData; } 240 241 private: 242 /** 243 Must be the first member in this class. OUString access this member with 244 *(rtl_Locale **)&locale. 245 */ 246 rtl_Locale * pData; 247 248 OLocale() 249 : pData(rtl_locale_getDefault()) {} 250 /* 251 OLocale( const OLocale & obj) 252 : pData(obj.pData) {} 253 254 OLocale & operator = ( const OLocale & obj) 255 { pData = obj.pData; 256 return *this; 257 } 258 */ 259 }; 260 261 } 262 263 #endif /* __cplusplus */ 264 #endif /* _RTL_LOCALE_HXX_ */ 265 266 267