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