Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: intl.h | |
e54c96f1 | 3 | // Purpose: interface of wxLocale |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
f045c7f5 FM |
9 | /** |
10 | This is the layout direction stored in wxLanguageInfo and returned by | |
51c0d02b FM |
11 | wxApp::GetLayoutDirection(), wxWindow::GetLayoutDirection(), |
12 | wxDC::GetLayoutDirection() for RTL (right-to-left) languages support. | |
f045c7f5 FM |
13 | */ |
14 | enum wxLayoutDirection | |
15 | { | |
16 | wxLayout_Default, | |
17 | wxLayout_LeftToRight, | |
18 | wxLayout_RightToLeft | |
19 | }; | |
20 | ||
969daeea | 21 | /** |
fc79419b FM |
22 | Encapsulates a ::wxLanguage indentifier together with OS-specific information |
23 | related to that language. | |
1058f652 MB |
24 | |
25 | @beginWxPerlOnly | |
26 | In wxPerl @c Wx::LanguageInfo has only one method: | |
27 | - Wx::LanguageInfo->new(language, canonicalName, WinLang, WinSubLang, Description) | |
28 | @endWxPerlOnly | |
969daeea FM |
29 | */ |
30 | struct WXDLLIMPEXP_BASE wxLanguageInfo | |
31 | { | |
89a7e1ff | 32 | /// ::wxLanguage id. |
fc79419b FM |
33 | /// It should be greater than @c wxLANGUAGE_USER_DEFINED when defining your own |
34 | /// language info structure. | |
969daeea | 35 | int Language; |
9a6fda22 FM |
36 | |
37 | /// Canonical name of the language, e.g. @c fr_FR. | |
38 | wxString CanonicalName; | |
39 | ||
40 | //@{ | |
41 | /** | |
42 | Win32 language identifiers (LANG_xxxx, SUBLANG_xxxx). | |
43 | ||
44 | @onlyfor{wxmsw} | |
45 | */ | |
46 | wxUint32 WinLang, WinSublang; | |
47 | //@} | |
48 | ||
49 | /// Human-readable name of the language. | |
50 | wxString Description; | |
51 | ||
52 | /// The layout direction used for this language. | |
969daeea FM |
53 | wxLayoutDirection LayoutDirection; |
54 | ||
969daeea | 55 | /// Return the LCID corresponding to this language. |
9a6fda22 | 56 | /// @onlyfor{wxmsw} |
969daeea | 57 | wxUint32 GetLCID() const; |
969daeea FM |
58 | |
59 | /// Return the locale name corresponding to this language usable with | |
9a6fda22 | 60 | /// @c setlocale() on the current system. |
969daeea FM |
61 | wxString GetLocaleName() const; |
62 | }; | |
63 | ||
64 | ||
fc79419b | 65 | /** |
89a7e1ff VZ |
66 | The category of locale settings. |
67 | ||
68 | @see wxLocale::GetInfo() | |
fc79419b FM |
69 | */ |
70 | enum wxLocaleCategory | |
71 | { | |
89a7e1ff | 72 | /// Number formatting. |
fc79419b FM |
73 | wxLOCALE_CAT_NUMBER, |
74 | ||
89a7e1ff | 75 | /// Date/time formatting. |
fc79419b FM |
76 | wxLOCALE_CAT_DATE, |
77 | ||
89a7e1ff | 78 | /// Monetary values formatting. |
fc79419b FM |
79 | wxLOCALE_CAT_MONEY, |
80 | ||
89a7e1ff VZ |
81 | /** |
82 | Default category for the wxLocaleInfo value. | |
83 | ||
84 | This category can be used for values which only make sense for a single | |
85 | category, e.g. wxLOCALE_SHORT_DATE_FMT which can only be used with | |
86 | wxLOCALE_CAT_DATE. As this is the default value of the second parameter | |
87 | of wxLocale::GetInfo(), wxLOCALE_CAT_DATE can be omitted when asking | |
88 | for wxLOCALE_SHORT_DATE_FMT value. | |
89 | ||
90 | @since 2.9.0 | |
91 | */ | |
92 | wxLOCALE_CAT_DEFAULT | |
fc79419b FM |
93 | }; |
94 | ||
95 | /** | |
96 | The values understood by wxLocale::GetInfo(). | |
ea0022d3 FM |
97 | |
98 | Note that for the @c wxLOCALE_*_FMT constants (the date and time formats), | |
99 | the strings returned by wxLocale::GetInfo() use strftime() or, | |
100 | equivalently, wxDateTime::Format() format. If the relevant format | |
101 | couldn't be determined, an empty string is returned -- there is no | |
102 | fallback value so that the application could determine the best course | |
103 | of actions itself in such case. | |
104 | ||
105 | All of these values are used with @c wxLOCALE_CAT_DATE in wxLocale::GetInfo() or, | |
106 | more typically, with @c wxLOCALE_CAT_DEFAULT as they only apply to a single category. | |
fc79419b FM |
107 | */ |
108 | enum wxLocaleInfo | |
109 | { | |
89a7e1ff VZ |
110 | /** |
111 | The thousands separator. | |
112 | ||
113 | This value can be used with either wxLOCALE_CAT_NUMBER or | |
114 | wxLOCALE_CAT_MONEY categories. | |
115 | */ | |
fc79419b FM |
116 | wxLOCALE_THOUSANDS_SEP, |
117 | ||
89a7e1ff VZ |
118 | /** |
119 | The character used as decimal point. | |
120 | ||
121 | This value can be used with either wxLOCALE_CAT_NUMBER or | |
122 | wxLOCALE_CAT_MONEY categories. | |
123 | */ | |
124 | wxLOCALE_DECIMAL_POINT, | |
125 | ||
89a7e1ff VZ |
126 | /** |
127 | Short date format. | |
128 | ||
129 | Notice that short and long date formats may be the same under POSIX | |
ea0022d3 | 130 | systems currently but may, and typically are, different under MSW or OS X. |
89a7e1ff VZ |
131 | |
132 | @since 2.9.0 | |
133 | */ | |
134 | wxLOCALE_SHORT_DATE_FMT, | |
135 | ||
136 | /** | |
137 | Long date format. | |
138 | ||
139 | @since 2.9.0 | |
140 | */ | |
141 | wxLOCALE_LONG_DATE_FMT, | |
142 | ||
143 | /** | |
144 | Date and time format. | |
145 | ||
146 | @since 2.9.0 | |
147 | */ | |
148 | wxLOCALE_DATE_TIME_FMT, | |
149 | ||
150 | /** | |
151 | Time format. | |
152 | ||
153 | @since 2.9.0 | |
154 | */ | |
155 | wxLOCALE_TIME_FMT | |
fc79419b FM |
156 | }; |
157 | ||
158 | ||
23324ae1 FM |
159 | /** |
160 | @class wxLocale | |
7c913512 | 161 | |
23324ae1 FM |
162 | wxLocale class encapsulates all language-dependent settings and is a |
163 | generalization of the C locale concept. | |
7c913512 | 164 | |
18e065b4 VS |
165 | In wxWidgets this class manages current locale. It also initializes and |
166 | activates wxTranslations object that manages message catalogs. | |
7c913512 | 167 | |
969daeea FM |
168 | For a list of the supported languages, please see ::wxLanguage enum values. |
169 | These constants may be used to specify the language in wxLocale::Init and | |
170 | are returned by wxLocale::GetSystemLanguage. | |
171 | ||
172 | @beginWxPerlOnly | |
173 | In wxPerl you can't use the '_' function name, so | |
7c913512 FM |
174 | the @c Wx::Locale module can export the @c gettext and |
175 | @c gettext_noop under any given name. | |
176 | ||
23324ae1 | 177 | @code |
969daeea | 178 | # this imports gettext ( equivalent to Wx::GetTranslation |
23324ae1 FM |
179 | # and gettext_noop ( a noop ) |
180 | # into your module | |
181 | use Wx::Locale qw(:default); | |
7c913512 | 182 | |
23324ae1 | 183 | # .... |
7c913512 | 184 | |
23324ae1 | 185 | # use the functions |
cdbcf4c2 | 186 | print gettext( "Panic!" ); |
7c913512 | 187 | |
cdbcf4c2 | 188 | button = Wx::Button-new( window, -1, gettext( "Label" ) ); |
23324ae1 | 189 | @endcode |
7c913512 | 190 | |
23324ae1 FM |
191 | If you need to translate a lot of strings, then adding gettext( ) around |
192 | each one is a long task ( that is why _( ) was introduced ), so just choose | |
193 | a shorter name for gettext: | |
7c913512 | 194 | |
23324ae1 | 195 | @code |
23324ae1 FM |
196 | use Wx::Locale 'gettext' = 't', |
197 | 'gettext_noop' = 'gettext_noop'; | |
7c913512 | 198 | |
23324ae1 | 199 | # ... |
7c913512 | 200 | |
23324ae1 | 201 | # use the functions |
cdbcf4c2 | 202 | print t( "Panic!!" ); |
7c913512 | 203 | |
23324ae1 FM |
204 | # ... |
205 | @endcode | |
969daeea | 206 | @endWxPerlOnly |
7c913512 | 207 | |
23324ae1 | 208 | @library{wxbase} |
3c99e2fd | 209 | @category{cfg} |
7c913512 | 210 | |
18e065b4 | 211 | @see @ref overview_i18n, @ref page_samples_internat, wxXLocale, wxTranslations |
23324ae1 | 212 | */ |
7c913512 | 213 | class wxLocale |
23324ae1 FM |
214 | { |
215 | public: | |
969daeea FM |
216 | /** |
217 | This is the default constructor and it does nothing to initialize the object: | |
218 | Init() must be used to do that. | |
219 | */ | |
220 | wxLocale(); | |
221 | ||
222 | /** | |
223 | See Init() for parameters description. | |
224 | */ | |
3acf8a8d | 225 | wxLocale(int language, int flags = wxLOCALE_LOAD_DEFAULT); |
969daeea | 226 | |
23324ae1 FM |
227 | /** |
228 | See Init() for parameters description. | |
969daeea | 229 | |
23324ae1 FM |
230 | The call of this function has several global side effects which you should |
231 | understand: first of all, the application locale is changed - note that this | |
232 | will affect many of standard C library functions such as printf() or strftime(). | |
233 | Second, this wxLocale object becomes the new current global locale for the | |
969daeea | 234 | application and so all subsequent calls to ::wxGetTranslation() will try to |
23324ae1 FM |
235 | translate the messages using the message catalogs for this locale. |
236 | */ | |
7c913512 | 237 | wxLocale(const wxString& name, |
96b77d60 | 238 | const wxString& shortName = wxEmptyString, |
7c913512 | 239 | const wxString& locale = wxEmptyString, |
3acf8a8d | 240 | bool bLoadDefault = true); |
23324ae1 FM |
241 | |
242 | /** | |
243 | The destructor, like the constructor, also has global side effects: the | |
969daeea | 244 | previously set locale is restored and so the changes described in |
23324ae1 FM |
245 | Init() documentation are rolled back. |
246 | */ | |
adaaa686 | 247 | virtual ~wxLocale(); |
23324ae1 | 248 | |
23324ae1 | 249 | /** |
18e065b4 | 250 | Calls wxTranslations::AddCatalog(const wxString&). |
23324ae1 FM |
251 | */ |
252 | bool AddCatalog(const wxString& domain); | |
a0a4c5aa FM |
253 | |
254 | /** | |
18e065b4 VS |
255 | Calls wxTranslations::AddCatalog(const wxString&, wxLanguage). |
256 | */ | |
257 | bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage); | |
a0a4c5aa | 258 | |
18e065b4 VS |
259 | /** |
260 | Calls wxTranslations::AddCatalog(const wxString&, wxLanguage, const wxString&). | |
a0a4c5aa | 261 | */ |
969daeea | 262 | bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage, |
7c913512 | 263 | const wxString& msgIdCharset); |
23324ae1 FM |
264 | |
265 | /** | |
18e065b4 | 266 | Calls wxFileTranslationsLoader::AddCatalogLookupPathPrefix(). |
23324ae1 | 267 | */ |
adaaa686 | 268 | static void AddCatalogLookupPathPrefix(const wxString& prefix); |
23324ae1 FM |
269 | |
270 | /** | |
969daeea FM |
271 | Adds custom, user-defined language to the database of known languages. |
272 | This database is used in conjunction with the first form of Init(). | |
23324ae1 FM |
273 | */ |
274 | static void AddLanguage(const wxLanguageInfo& info); | |
275 | ||
276 | /** | |
277 | This function may be used to find the language description structure for the | |
278 | given locale, specified either as a two letter ISO language code (for example, | |
279 | "pt"), a language code followed by the country code ("pt_BR") or a full, human | |
280 | readable, language description ("Portuguese-Brazil"). | |
969daeea | 281 | |
23324ae1 | 282 | Returns the information for the given language or @NULL if this language |
969daeea FM |
283 | is unknown. Note that even if the returned pointer is valid, the caller |
284 | should @e not delete it. | |
3c4f71cc | 285 | |
4cc4bfaf | 286 | @see GetLanguageInfo() |
23324ae1 | 287 | */ |
382f12e4 | 288 | static const wxLanguageInfo* FindLanguageInfo(const wxString& locale); |
23324ae1 FM |
289 | |
290 | /** | |
291 | Returns the canonical form of current locale name. Canonical form is the | |
292 | one that is used on UNIX systems: it is a two- or five-letter string in xx or | |
293 | xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of | |
294 | the country. Examples are "en", "en_GB", "en_US" or "fr_FR". | |
23324ae1 | 295 | This form is internally used when looking up message catalogs. |
23324ae1 FM |
296 | Compare GetSysName(). |
297 | */ | |
328f5751 | 298 | wxString GetCanonicalName() const; |
23324ae1 FM |
299 | |
300 | /** | |
18e065b4 | 301 | Calls wxTranslations::GetHeaderValue(). |
23324ae1 FM |
302 | */ |
303 | wxString GetHeaderValue(const wxString& header, | |
328f5751 | 304 | const wxString& domain = wxEmptyString) const; |
23324ae1 FM |
305 | |
306 | /** | |
d5c8403a | 307 | Returns the ::wxLanguage constant of current language. |
969daeea | 308 | |
23324ae1 | 309 | Note that you can call this function only if you used the form of |
d5c8403a | 310 | Init() that takes ::wxLanguage argument. |
23324ae1 | 311 | */ |
328f5751 | 312 | int GetLanguage() const; |
23324ae1 FM |
313 | |
314 | /** | |
969daeea FM |
315 | Returns a pointer to wxLanguageInfo structure containing information about |
316 | the given language or @NULL if this language is unknown. Note that even if | |
317 | the returned pointer is valid, the caller should @e not delete it. | |
318 | ||
319 | See AddLanguage() for the wxLanguageInfo description. | |
320 | As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed | |
321 | as an argument to this function and in this case the result of | |
322 | GetSystemLanguage() is used. | |
23324ae1 | 323 | */ |
57bf907d | 324 | static const wxLanguageInfo* GetLanguageInfo(int lang); |
23324ae1 FM |
325 | |
326 | /** | |
327 | Returns English name of the given language or empty string if this | |
328 | language is unknown. | |
969daeea FM |
329 | |
330 | See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT. | |
23324ae1 | 331 | */ |
57bf907d | 332 | static wxString GetLanguageName(int lang); |
23324ae1 | 333 | |
18e065b4 VS |
334 | /** |
335 | Returns canonical name (see GetCanonicalName()) of the given language | |
336 | or empty string if this language is unknown. | |
337 | ||
338 | See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT. | |
339 | ||
340 | @since 2.9.1 | |
341 | */ | |
342 | static wxString GetLanguageCanonicalName(int lang); | |
343 | ||
23324ae1 | 344 | /** |
969daeea FM |
345 | Returns the locale name as passed to the constructor or Init(). |
346 | ||
347 | This is a full, human-readable name, e.g. "English" or "French". | |
23324ae1 | 348 | */ |
969daeea | 349 | const wxString& GetLocale() const; |
23324ae1 FM |
350 | |
351 | /** | |
352 | Returns the current short name for the locale (as given to the constructor or | |
353 | the Init() function). | |
354 | */ | |
969daeea | 355 | const wxString& GetName() const; |
23324ae1 | 356 | |
23324ae1 | 357 | /** |
18e065b4 | 358 | Calls wxTranslations::GetString(const wxString&, const wxString&) const. |
969daeea | 359 | */ |
fadc2df6 FM |
360 | virtual const wxString& GetString(const wxString& origString, |
361 | const wxString& domain = wxEmptyString) const; | |
969daeea FM |
362 | |
363 | /** | |
dfbb5eff | 364 | Calls wxTranslations::GetString(const wxString&, const wxString&, unsigned, const wxString&) const. |
23324ae1 | 365 | */ |
7323ff1a | 366 | virtual const wxString& GetString(const wxString& origString, |
dfbb5eff | 367 | const wxString& origString2, unsigned n, |
7323ff1a | 368 | const wxString& domain = wxEmptyString) const; |
23324ae1 FM |
369 | |
370 | /** | |
371 | Returns current platform-specific locale name as passed to setlocale(). | |
23324ae1 FM |
372 | Compare GetCanonicalName(). |
373 | */ | |
328f5751 | 374 | wxString GetSysName() const; |
23324ae1 FM |
375 | |
376 | /** | |
377 | Tries to detect the user's default font encoding. | |
969daeea FM |
378 | Returns wxFontEncoding() value or @c wxFONTENCODING_SYSTEM if it |
379 | couldn't be determined. | |
23324ae1 | 380 | */ |
57bf907d | 381 | static wxFontEncoding GetSystemEncoding(); |
23324ae1 FM |
382 | |
383 | /** | |
969daeea FM |
384 | Tries to detect the name of the user's default font encoding. |
385 | This string isn't particularly useful for the application as its form is | |
386 | platform-dependent and so you should probably use GetSystemEncoding() instead. | |
387 | ||
23324ae1 FM |
388 | Returns a user-readable string value or an empty string if it couldn't be |
389 | determined. | |
390 | */ | |
57bf907d | 391 | static wxString GetSystemEncodingName(); |
23324ae1 FM |
392 | |
393 | /** | |
394 | Tries to detect the user's default language setting. | |
89a7e1ff | 395 | |
fc79419b | 396 | Returns the ::wxLanguage value or @c wxLANGUAGE_UNKNOWN if the language-guessing |
969daeea | 397 | algorithm failed. |
23324ae1 | 398 | */ |
57bf907d | 399 | static int GetSystemLanguage(); |
23324ae1 | 400 | |
fc79419b FM |
401 | /** |
402 | Get the values of the given locale-dependent datum. | |
403 | ||
89a7e1ff VZ |
404 | This function returns the value of the locale-specific option specified |
405 | by the given @a index. | |
406 | ||
407 | @param index | |
408 | One of the elements of wxLocaleInfo enum. | |
409 | @param cat | |
410 | The category to use with the given index or wxLOCALE_CAT_DEFAULT if | |
411 | the index can only apply to a single category. | |
412 | @return | |
413 | The option value or empty string if the function failed. | |
fc79419b | 414 | */ |
89a7e1ff VZ |
415 | static wxString GetInfo(wxLocaleInfo index, |
416 | wxLocaleCategory cat = wxLOCALE_CAT_DEFAULT); | |
fc79419b | 417 | |
23324ae1 | 418 | /** |
969daeea FM |
419 | Initializes the wxLocale instance. |
420 | ||
421 | The call of this function has several global side effects which you should | |
422 | understand: first of all, the application locale is changed - note that | |
423 | this will affect many of standard C library functions such as printf() | |
424 | or strftime(). | |
425 | Second, this wxLocale object becomes the new current global locale for | |
426 | the application and so all subsequent calls to wxGetTranslation() will | |
427 | try to translate the messages using the message catalogs for this locale. | |
3c4f71cc | 428 | |
7c913512 | 429 | @param language |
d5c8403a | 430 | ::wxLanguage identifier of the locale. |
969daeea FM |
431 | @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's |
432 | default language (see GetSystemLanguage()). | |
7c913512 | 433 | @param flags |
4cc4bfaf | 434 | Combination of the following: |
969daeea FM |
435 | - wxLOCALE_LOAD_DEFAULT: Load the message catalog for the given locale |
436 | containing the translations of standard wxWidgets messages | |
437 | automatically. | |
f30bd8f2 | 438 | - wxLOCALE_DONT_LOAD_DEFAULT: Negation of wxLOCALE_LOAD_DEFAULT. |
89bb3f02 FM |
439 | |
440 | @return @true on success or @false if the given locale couldn't be set. | |
441 | */ | |
442 | bool Init(int language = wxLANGUAGE_DEFAULT, | |
3acf8a8d | 443 | int flags = wxLOCALE_LOAD_DEFAULT); |
89bb3f02 FM |
444 | |
445 | /** | |
446 | @deprecated | |
447 | This form is deprecated, use the other one unless you know what you are doing. | |
448 | ||
4cc4bfaf FM |
449 | @param name |
450 | The name of the locale. Only used in diagnostic messages. | |
451 | @param short | |
452 | The standard 2 letter locale abbreviation; it is used as the | |
453 | directory prefix when looking for the message catalog files. | |
454 | @param locale | |
969daeea FM |
455 | The parameter for the call to setlocale(). |
456 | Note that it is platform-specific. | |
4cc4bfaf | 457 | @param bLoadDefault |
969daeea FM |
458 | May be set to @false to prevent loading of the message catalog for the |
459 | given locale containing the translations of standard wxWidgets messages. | |
4cc4bfaf | 460 | This parameter would be rarely used in normal circumstances. |
969daeea | 461 | */ |
96b77d60 | 462 | bool Init(const wxString& name, const wxString& shortName = wxEmptyString, |
3acf8a8d | 463 | const wxString& locale = wxEmptyString, bool bLoadDefault = true); |
23324ae1 FM |
464 | |
465 | /** | |
466 | Check whether the operating system and/or C run time environment supports | |
467 | this locale. For example in Windows 2000 and Windows XP, support for many | |
468 | locales is not installed by default. Returns @true if the locale is | |
469 | supported. | |
d5c8403a FM |
470 | |
471 | The argument @a lang is the ::wxLanguage identifier. To obtain this for a | |
472 | given a two letter ISO language code, use FindLanguageInfo() to obtain its | |
473 | wxLanguageInfo structure. | |
474 | See AddLanguage() for the wxLanguageInfo description. | |
3c4f71cc | 475 | |
1e24c2af | 476 | @since 2.7.1. |
23324ae1 FM |
477 | */ |
478 | static bool IsAvailable(int lang); | |
479 | ||
18e065b4 VS |
480 | /** |
481 | Calls wxTranslations::IsLoaded(). | |
482 | */ | |
483 | bool IsLoaded(const wxString& domain) const; | |
484 | ||
485 | /** | |
486 | Returns @true if the locale could be set successfully. | |
487 | */ | |
488 | bool IsOk() const; | |
489 | }; |