]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/intl.h
make wxRearrangeDialog more customizable and add an example of customizing it to...
[wxWidgets.git] / interface / wx / intl.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: intl.h
e54c96f1 3// Purpose: interface of wxLocale
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
969daeea
FM
9
10// --- --- --- generated code begins here --- --- ---
11
12/**
13 The languages supported by wxLocale.
14
15 This enum is generated by misc/languages/genlang.py
16 When making changes, please put them into misc/languages/langtabl.txt
17*/
18enum wxLanguage
19{
20 /// User's default/preffered language as got from OS.
21 wxLANGUAGE_DEFAULT,
22
23 /// Unknown language, returned if wxLocale::GetSystemLanguage fails.
24 wxLANGUAGE_UNKNOWN,
25
26 wxLANGUAGE_ABKHAZIAN,
27 wxLANGUAGE_AFAR,
28 wxLANGUAGE_AFRIKAANS,
29 wxLANGUAGE_ALBANIAN,
30 wxLANGUAGE_AMHARIC,
31 wxLANGUAGE_ARABIC,
32 wxLANGUAGE_ARABIC_ALGERIA,
33 wxLANGUAGE_ARABIC_BAHRAIN,
34 wxLANGUAGE_ARABIC_EGYPT,
35 wxLANGUAGE_ARABIC_IRAQ,
36 wxLANGUAGE_ARABIC_JORDAN,
37 wxLANGUAGE_ARABIC_KUWAIT,
38 wxLANGUAGE_ARABIC_LEBANON,
39 wxLANGUAGE_ARABIC_LIBYA,
40 wxLANGUAGE_ARABIC_MOROCCO,
41 wxLANGUAGE_ARABIC_OMAN,
42 wxLANGUAGE_ARABIC_QATAR,
43 wxLANGUAGE_ARABIC_SAUDI_ARABIA,
44 wxLANGUAGE_ARABIC_SUDAN,
45 wxLANGUAGE_ARABIC_SYRIA,
46 wxLANGUAGE_ARABIC_TUNISIA,
47 wxLANGUAGE_ARABIC_UAE,
48 wxLANGUAGE_ARABIC_YEMEN,
49 wxLANGUAGE_ARMENIAN,
50 wxLANGUAGE_ASSAMESE,
51 wxLANGUAGE_AYMARA,
52 wxLANGUAGE_AZERI,
53 wxLANGUAGE_AZERI_CYRILLIC,
54 wxLANGUAGE_AZERI_LATIN,
55 wxLANGUAGE_BASHKIR,
56 wxLANGUAGE_BASQUE,
57 wxLANGUAGE_BELARUSIAN,
58 wxLANGUAGE_BENGALI,
59 wxLANGUAGE_BHUTANI,
60 wxLANGUAGE_BIHARI,
61 wxLANGUAGE_BISLAMA,
62 wxLANGUAGE_BRETON,
63 wxLANGUAGE_BULGARIAN,
64 wxLANGUAGE_BURMESE,
65 wxLANGUAGE_CAMBODIAN,
66 wxLANGUAGE_CATALAN,
67 wxLANGUAGE_CHINESE,
68 wxLANGUAGE_CHINESE_SIMPLIFIED,
69 wxLANGUAGE_CHINESE_TRADITIONAL,
70 wxLANGUAGE_CHINESE_HONGKONG,
71 wxLANGUAGE_CHINESE_MACAU,
72 wxLANGUAGE_CHINESE_SINGAPORE,
73 wxLANGUAGE_CHINESE_TAIWAN,
74 wxLANGUAGE_CORSICAN,
75 wxLANGUAGE_CROATIAN,
76 wxLANGUAGE_CZECH,
77 wxLANGUAGE_DANISH,
78 wxLANGUAGE_DUTCH,
79 wxLANGUAGE_DUTCH_BELGIAN,
80 wxLANGUAGE_ENGLISH,
81 wxLANGUAGE_ENGLISH_UK,
82 wxLANGUAGE_ENGLISH_US,
83 wxLANGUAGE_ENGLISH_AUSTRALIA,
84 wxLANGUAGE_ENGLISH_BELIZE,
85 wxLANGUAGE_ENGLISH_BOTSWANA,
86 wxLANGUAGE_ENGLISH_CANADA,
87 wxLANGUAGE_ENGLISH_CARIBBEAN,
88 wxLANGUAGE_ENGLISH_DENMARK,
89 wxLANGUAGE_ENGLISH_EIRE,
90 wxLANGUAGE_ENGLISH_JAMAICA,
91 wxLANGUAGE_ENGLISH_NEW_ZEALAND,
92 wxLANGUAGE_ENGLISH_PHILIPPINES,
93 wxLANGUAGE_ENGLISH_SOUTH_AFRICA,
94 wxLANGUAGE_ENGLISH_TRINIDAD,
95 wxLANGUAGE_ENGLISH_ZIMBABWE,
96 wxLANGUAGE_ESPERANTO,
97 wxLANGUAGE_ESTONIAN,
98 wxLANGUAGE_FAEROESE,
99 wxLANGUAGE_FARSI,
100 wxLANGUAGE_FIJI,
101 wxLANGUAGE_FINNISH,
102 wxLANGUAGE_FRENCH,
103 wxLANGUAGE_FRENCH_BELGIAN,
104 wxLANGUAGE_FRENCH_CANADIAN,
105 wxLANGUAGE_FRENCH_LUXEMBOURG,
106 wxLANGUAGE_FRENCH_MONACO,
107 wxLANGUAGE_FRENCH_SWISS,
108 wxLANGUAGE_FRISIAN,
109 wxLANGUAGE_GALICIAN,
110 wxLANGUAGE_GEORGIAN,
111 wxLANGUAGE_GERMAN,
112 wxLANGUAGE_GERMAN_AUSTRIAN,
113 wxLANGUAGE_GERMAN_BELGIUM,
114 wxLANGUAGE_GERMAN_LIECHTENSTEIN,
115 wxLANGUAGE_GERMAN_LUXEMBOURG,
116 wxLANGUAGE_GERMAN_SWISS,
117 wxLANGUAGE_GREEK,
118 wxLANGUAGE_GREENLANDIC,
119 wxLANGUAGE_GUARANI,
120 wxLANGUAGE_GUJARATI,
121 wxLANGUAGE_HAUSA,
122 wxLANGUAGE_HEBREW,
123 wxLANGUAGE_HINDI,
124 wxLANGUAGE_HUNGARIAN,
125 wxLANGUAGE_ICELANDIC,
126 wxLANGUAGE_INDONESIAN,
127 wxLANGUAGE_INTERLINGUA,
128 wxLANGUAGE_INTERLINGUE,
129 wxLANGUAGE_INUKTITUT,
130 wxLANGUAGE_INUPIAK,
131 wxLANGUAGE_IRISH,
132 wxLANGUAGE_ITALIAN,
133 wxLANGUAGE_ITALIAN_SWISS,
134 wxLANGUAGE_JAPANESE,
135 wxLANGUAGE_JAVANESE,
136 wxLANGUAGE_KANNADA,
137 wxLANGUAGE_KASHMIRI,
138 wxLANGUAGE_KASHMIRI_INDIA,
139 wxLANGUAGE_KAZAKH,
140 wxLANGUAGE_KERNEWEK,
141 wxLANGUAGE_KINYARWANDA,
142 wxLANGUAGE_KIRGHIZ,
143 wxLANGUAGE_KIRUNDI,
144 wxLANGUAGE_KONKANI,
145 wxLANGUAGE_KOREAN,
146 wxLANGUAGE_KURDISH,
147 wxLANGUAGE_LAOTHIAN,
148 wxLANGUAGE_LATIN,
149 wxLANGUAGE_LATVIAN,
150 wxLANGUAGE_LINGALA,
151 wxLANGUAGE_LITHUANIAN,
152 wxLANGUAGE_MACEDONIAN,
153 wxLANGUAGE_MALAGASY,
154 wxLANGUAGE_MALAY,
155 wxLANGUAGE_MALAYALAM,
156 wxLANGUAGE_MALAY_BRUNEI_DARUSSALAM,
157 wxLANGUAGE_MALAY_MALAYSIA,
158 wxLANGUAGE_MALTESE,
159 wxLANGUAGE_MANIPURI,
160 wxLANGUAGE_MAORI,
161 wxLANGUAGE_MARATHI,
162 wxLANGUAGE_MOLDAVIAN,
163 wxLANGUAGE_MONGOLIAN,
164 wxLANGUAGE_NAURU,
165 wxLANGUAGE_NEPALI,
166 wxLANGUAGE_NEPALI_INDIA,
167 wxLANGUAGE_NORWEGIAN_BOKMAL,
168 wxLANGUAGE_NORWEGIAN_NYNORSK,
169 wxLANGUAGE_OCCITAN,
170 wxLANGUAGE_ORIYA,
171 wxLANGUAGE_OROMO,
172 wxLANGUAGE_PASHTO,
173 wxLANGUAGE_POLISH,
174 wxLANGUAGE_PORTUGUESE,
175 wxLANGUAGE_PORTUGUESE_BRAZILIAN,
176 wxLANGUAGE_PUNJABI,
177 wxLANGUAGE_QUECHUA,
178 wxLANGUAGE_RHAETO_ROMANCE,
179 wxLANGUAGE_ROMANIAN,
180 wxLANGUAGE_RUSSIAN,
181 wxLANGUAGE_RUSSIAN_UKRAINE,
182 wxLANGUAGE_SAMI,
183 wxLANGUAGE_SAMOAN,
184 wxLANGUAGE_SANGHO,
185 wxLANGUAGE_SANSKRIT,
186 wxLANGUAGE_SCOTS_GAELIC,
187 wxLANGUAGE_SERBIAN,
188 wxLANGUAGE_SERBIAN_CYRILLIC,
189 wxLANGUAGE_SERBIAN_LATIN,
190 wxLANGUAGE_SERBO_CROATIAN,
191 wxLANGUAGE_SESOTHO,
192 wxLANGUAGE_SETSWANA,
193 wxLANGUAGE_SHONA,
194 wxLANGUAGE_SINDHI,
195 wxLANGUAGE_SINHALESE,
196 wxLANGUAGE_SISWATI,
197 wxLANGUAGE_SLOVAK,
198 wxLANGUAGE_SLOVENIAN,
199 wxLANGUAGE_SOMALI,
200 wxLANGUAGE_SPANISH,
201 wxLANGUAGE_SPANISH_ARGENTINA,
202 wxLANGUAGE_SPANISH_BOLIVIA,
203 wxLANGUAGE_SPANISH_CHILE,
204 wxLANGUAGE_SPANISH_COLOMBIA,
205 wxLANGUAGE_SPANISH_COSTA_RICA,
206 wxLANGUAGE_SPANISH_DOMINICAN_REPUBLIC,
207 wxLANGUAGE_SPANISH_ECUADOR,
208 wxLANGUAGE_SPANISH_EL_SALVADOR,
209 wxLANGUAGE_SPANISH_GUATEMALA,
210 wxLANGUAGE_SPANISH_HONDURAS,
211 wxLANGUAGE_SPANISH_MEXICAN,
212 wxLANGUAGE_SPANISH_MODERN,
213 wxLANGUAGE_SPANISH_NICARAGUA,
214 wxLANGUAGE_SPANISH_PANAMA,
215 wxLANGUAGE_SPANISH_PARAGUAY,
216 wxLANGUAGE_SPANISH_PERU,
217 wxLANGUAGE_SPANISH_PUERTO_RICO,
218 wxLANGUAGE_SPANISH_URUGUAY,
219 wxLANGUAGE_SPANISH_US,
220 wxLANGUAGE_SPANISH_VENEZUELA,
221 wxLANGUAGE_SUNDANESE,
222 wxLANGUAGE_SWAHILI,
223 wxLANGUAGE_SWEDISH,
224 wxLANGUAGE_SWEDISH_FINLAND,
225 wxLANGUAGE_TAGALOG,
226 wxLANGUAGE_TAJIK,
227 wxLANGUAGE_TAMIL,
228 wxLANGUAGE_TATAR,
229 wxLANGUAGE_TELUGU,
230 wxLANGUAGE_THAI,
231 wxLANGUAGE_TIBETAN,
232 wxLANGUAGE_TIGRINYA,
233 wxLANGUAGE_TONGA,
234 wxLANGUAGE_TSONGA,
235 wxLANGUAGE_TURKISH,
236 wxLANGUAGE_TURKMEN,
237 wxLANGUAGE_TWI,
238 wxLANGUAGE_UIGHUR,
239 wxLANGUAGE_UKRAINIAN,
240 wxLANGUAGE_URDU,
241 wxLANGUAGE_URDU_INDIA,
242 wxLANGUAGE_URDU_PAKISTAN,
243 wxLANGUAGE_UZBEK,
244 wxLANGUAGE_UZBEK_CYRILLIC,
245 wxLANGUAGE_UZBEK_LATIN,
246 wxLANGUAGE_VALENCIAN,
247 wxLANGUAGE_VIETNAMESE,
248 wxLANGUAGE_VOLAPUK,
249 wxLANGUAGE_WELSH,
250 wxLANGUAGE_WOLOF,
251 wxLANGUAGE_XHOSA,
252 wxLANGUAGE_YIDDISH,
253 wxLANGUAGE_YORUBA,
254 wxLANGUAGE_ZHUANG,
255 wxLANGUAGE_ZULU,
256
257 /// For custom, user-defined languages.
258 wxLANGUAGE_USER_DEFINED
259};
260
261// --- --- --- generated code ends here --- --- ---
262
263
264
f045c7f5
FM
265/**
266 This is the layout direction stored in wxLanguageInfo and returned by
267 wxApp::GetLayoutDirection() for RTL (right-to-left) languages support.
268*/
269enum wxLayoutDirection
270{
271 wxLayout_Default,
272 wxLayout_LeftToRight,
273 wxLayout_RightToLeft
274};
275
969daeea 276/**
d5c8403a 277 wxLanguageInfo: encapsulates ::wxLanguage to OS native lang.desc.
969daeea
FM
278 translation information
279*/
280struct WXDLLIMPEXP_BASE wxLanguageInfo
281{
d5c8403a 282 /// ::wxLanguage id. It should be greater than wxLANGUAGE_USER_DEFINED.
969daeea
FM
283 int Language;
284 wxString CanonicalName; //!< Canonical name, e.g. fr_FR.
285#ifdef __WXMSW__
286 wxUint32 WinLang, //!< Win32 language identifiers (LANG_xxxx, SUBLANG_xxxx).
287 WinSublang;
288#endif // __WXMSW__
289 wxString Description; //!< Human-readable name of the language.
290 wxLayoutDirection LayoutDirection;
291
292#ifdef __WXMSW__
293 /// Return the LCID corresponding to this language.
294 wxUint32 GetLCID() const;
295#endif // __WXMSW__
296
297 /// Return the locale name corresponding to this language usable with
298 /// setlocale() on the current system
299 wxString GetLocaleName() const;
300};
301
302
23324ae1
FM
303/**
304 @class wxLocale
7c913512 305
23324ae1
FM
306 wxLocale class encapsulates all language-dependent settings and is a
307 generalization of the C locale concept.
7c913512 308
23324ae1
FM
309 In wxWidgets this class manages message catalogs which contain the translations
310 of the strings used to the current language.
7c913512 311
969daeea
FM
312 For a list of the supported languages, please see ::wxLanguage enum values.
313 These constants may be used to specify the language in wxLocale::Init and
314 are returned by wxLocale::GetSystemLanguage.
315
316 @beginWxPerlOnly
317 In wxPerl you can't use the '_' function name, so
7c913512
FM
318 the @c Wx::Locale module can export the @c gettext and
319 @c gettext_noop under any given name.
320
23324ae1 321 @code
969daeea 322 # this imports gettext ( equivalent to Wx::GetTranslation
23324ae1
FM
323 # and gettext_noop ( a noop )
324 # into your module
325 use Wx::Locale qw(:default);
7c913512 326
23324ae1 327 # ....
7c913512 328
23324ae1 329 # use the functions
cdbcf4c2 330 print gettext( "Panic!" );
7c913512 331
cdbcf4c2 332 button = Wx::Button-new( window, -1, gettext( "Label" ) );
23324ae1 333 @endcode
7c913512 334
23324ae1
FM
335 If you need to translate a lot of strings, then adding gettext( ) around
336 each one is a long task ( that is why _( ) was introduced ), so just choose
337 a shorter name for gettext:
7c913512 338
23324ae1 339 @code
23324ae1
FM
340 use Wx::Locale 'gettext' = 't',
341 'gettext_noop' = 'gettext_noop';
7c913512 342
23324ae1 343 # ...
7c913512 344
23324ae1 345 # use the functions
cdbcf4c2 346 print t( "Panic!!" );
7c913512 347
23324ae1
FM
348 # ...
349 @endcode
969daeea 350 @endWxPerlOnly
7c913512 351
23324ae1 352 @library{wxbase}
969daeea 353 @category{misc}
7c913512 354
89bb3f02 355 @see @ref overview_i18n, @ref page_samples_internat, wxXLocale
23324ae1 356*/
7c913512 357class wxLocale
23324ae1
FM
358{
359public:
969daeea
FM
360 /**
361 This is the default constructor and it does nothing to initialize the object:
362 Init() must be used to do that.
363 */
364 wxLocale();
365
366 /**
367 See Init() for parameters description.
368 */
369 wxLocale(int language,
370 int flags = wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING);
371
23324ae1
FM
372 /**
373 See Init() for parameters description.
969daeea 374
23324ae1
FM
375 The call of this function has several global side effects which you should
376 understand: first of all, the application locale is changed - note that this
377 will affect many of standard C library functions such as printf() or strftime().
378 Second, this wxLocale object becomes the new current global locale for the
969daeea 379 application and so all subsequent calls to ::wxGetTranslation() will try to
23324ae1
FM
380 translate the messages using the message catalogs for this locale.
381 */
7c913512
FM
382 wxLocale(const wxString& name,
383 const wxString& short = wxEmptyString,
384 const wxString& locale = wxEmptyString,
4cc4bfaf
FM
385 bool bLoadDefault = true,
386 bool bConvertEncoding = false);
23324ae1
FM
387
388 /**
389 The destructor, like the constructor, also has global side effects: the
969daeea 390 previously set locale is restored and so the changes described in
23324ae1
FM
391 Init() documentation are rolled back.
392 */
adaaa686 393 virtual ~wxLocale();
23324ae1 394
23324ae1
FM
395 /**
396 Add a catalog for use with the current locale: it is searched for in standard
397 places (current directory first, then the system one), but you may also prepend
969daeea
FM
398 additional directories to the search path with AddCatalogLookupPathPrefix().
399
400 All loaded catalogs will be used for message lookup by GetString() for
401 the current locale.
402
a0a4c5aa 403 In this overload, @c msgid strings are assumed
23324ae1 404 to be in English and written only using 7-bit ASCII characters.
969daeea
FM
405 If you have to deal with non-English strings or 8-bit characters in the
406 source code, see the instructions in @ref overview_nonenglish.
a0a4c5aa
FM
407
408 @return
409 @true if catalog was successfully loaded, @false otherwise (which might
410 mean that the catalog is not found or that it isn't in the correct format).
23324ae1
FM
411 */
412 bool AddCatalog(const wxString& domain);
a0a4c5aa
FM
413
414 /**
415 Add a catalog for use with the current locale: it is searched for in standard
416 places (current directory first, then the system one), but you may also prepend
417 additional directories to the search path with AddCatalogLookupPathPrefix().
418
419 All loaded catalogs will be used for message lookup by GetString() for
420 the current locale.
421
422 This overload takes two additional arguments, @a msgIdLanguage and @a msgIdCharset.
423
e2c4ccaf
FM
424 @param domain
425 The catalog domain to add.
426
a0a4c5aa
FM
427 @param msgIdLanguage
428 Specifies the language of "msgid" strings in source code
429 (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
430 It is used if AddCatalog() cannot find any catalog for current language:
431 if the language is same as source code language, then strings from source
432 code are used instead.
433
434 @param msgIdCharset
435 Lets you specify the charset used for msgids in sources
436 in case they use 8-bit characters (e.g. German or French strings).
437 This argument has no effect in Unicode build, because literals in sources are
438 Unicode strings; you have to use compiler-specific method of setting the right
439 charset when compiling with Unicode.
440
441 @return
442 @true if catalog was successfully loaded, @false otherwise (which might
443 mean that the catalog is not found or that it isn't in the correct format).
444 */
969daeea 445 bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage,
7c913512 446 const wxString& msgIdCharset);
23324ae1
FM
447
448 /**
969daeea
FM
449 Add a prefix to the catalog lookup path: the message catalog files will
450 be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
23324ae1 451 (in this order).
969daeea 452
23324ae1
FM
453 This only applies to subsequent invocations of AddCatalog().
454 */
adaaa686 455 static void AddCatalogLookupPathPrefix(const wxString& prefix);
23324ae1
FM
456
457 /**
969daeea
FM
458 Adds custom, user-defined language to the database of known languages.
459 This database is used in conjunction with the first form of Init().
23324ae1
FM
460 */
461 static void AddLanguage(const wxLanguageInfo& info);
462
463 /**
464 This function may be used to find the language description structure for the
465 given locale, specified either as a two letter ISO language code (for example,
466 "pt"), a language code followed by the country code ("pt_BR") or a full, human
467 readable, language description ("Portuguese-Brazil").
969daeea 468
23324ae1 469 Returns the information for the given language or @NULL if this language
969daeea
FM
470 is unknown. Note that even if the returned pointer is valid, the caller
471 should @e not delete it.
3c4f71cc 472
4cc4bfaf 473 @see GetLanguageInfo()
23324ae1 474 */
4cc4bfaf 475 static wxLanguageInfo* FindLanguageInfo(const wxString& locale);
23324ae1
FM
476
477 /**
478 Returns the canonical form of current locale name. Canonical form is the
479 one that is used on UNIX systems: it is a two- or five-letter string in xx or
480 xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of
481 the country. Examples are "en", "en_GB", "en_US" or "fr_FR".
23324ae1 482 This form is internally used when looking up message catalogs.
23324ae1
FM
483 Compare GetSysName().
484 */
328f5751 485 wxString GetCanonicalName() const;
23324ae1
FM
486
487 /**
969daeea
FM
488 Returns the header value for header @a header.
489 The search for @a header is case sensitive. If an @a domain is passed,
490 this domain is searched. Else all domains will be searched until a
23324ae1 491 header has been found.
969daeea 492
23324ae1
FM
493 The return value is the value of the header if found. Else this will be empty.
494 */
495 wxString GetHeaderValue(const wxString& header,
328f5751 496 const wxString& domain = wxEmptyString) const;
23324ae1
FM
497
498 /**
d5c8403a 499 Returns the ::wxLanguage constant of current language.
969daeea 500
23324ae1 501 Note that you can call this function only if you used the form of
d5c8403a 502 Init() that takes ::wxLanguage argument.
23324ae1 503 */
328f5751 504 int GetLanguage() const;
23324ae1
FM
505
506 /**
969daeea
FM
507 Returns a pointer to wxLanguageInfo structure containing information about
508 the given language or @NULL if this language is unknown. Note that even if
509 the returned pointer is valid, the caller should @e not delete it.
510
511 See AddLanguage() for the wxLanguageInfo description.
512 As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed
513 as an argument to this function and in this case the result of
514 GetSystemLanguage() is used.
23324ae1 515 */
328f5751 516 static wxLanguageInfo* GetLanguageInfo(int lang) const;
23324ae1
FM
517
518 /**
519 Returns English name of the given language or empty string if this
520 language is unknown.
969daeea
FM
521
522 See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
23324ae1 523 */
328f5751 524 static wxString GetLanguageName(int lang) const;
23324ae1
FM
525
526 /**
969daeea
FM
527 Returns the locale name as passed to the constructor or Init().
528
529 This is a full, human-readable name, e.g. "English" or "French".
23324ae1 530 */
969daeea 531 const wxString& GetLocale() const;
23324ae1
FM
532
533 /**
534 Returns the current short name for the locale (as given to the constructor or
535 the Init() function).
536 */
969daeea 537 const wxString& GetName() const;
23324ae1 538
23324ae1 539 /**
969daeea 540 Retrieves the translation for a string in all loaded domains unless the @a domain
23324ae1 541 parameter is specified (and then only this catalog/domain is searched).
969daeea
FM
542
543 Returns original string if translation is not available (in this case an
544 error message is generated the first time a string is not found; use
545 wxLogNull to suppress it).
546
547 @remarks Domains are searched in the last to first order, i.e. catalogs
548 added later override those added before.
549 */
fadc2df6
FM
550 virtual const wxString& GetString(const wxString& origString,
551 const wxString& domain = wxEmptyString) const;
969daeea
FM
552
553 /**
554 Retrieves the translation for a string in all loaded domains unless the @a domain
555 parameter is specified (and then only this catalog/domain is searched).
556
557 Returns original string if translation is not available (in this case an
558 error message is generated the first time a string is not found; use
559 wxLogNull to suppress it).
560
561 This form is used when retrieving translation of string that has different
562 singular and plural form in English or different plural forms in some
563 other language.
564 It takes two extra arguments: @a origString parameter must contain the
565 singular form of the string to be converted.
566
23324ae1 567 It is also used as the key for the search in the catalog.
4cc4bfaf 568 The @a origString2 parameter is the plural form (in English).
969daeea
FM
569
570 The parameter @a n is used to determine the plural form.
571 If no message catalog is found @a origString is returned if 'n == 1',
572 otherwise @a origString2.
573
23324ae1 574 See GNU gettext manual for additional information on plural forms handling.
969daeea 575 This method is called by the wxGetTranslation() function and _() macro.
3c4f71cc 576
23324ae1 577 @remarks Domains are searched in the last to first order, i.e. catalogs
4cc4bfaf 578 added later override those added before.
23324ae1 579 */
7323ff1a
FM
580 virtual const wxString& GetString(const wxString& origString,
581 const wxString& origString2, size_t n,
582 const wxString& domain = wxEmptyString) const;
23324ae1
FM
583
584 /**
585 Returns current platform-specific locale name as passed to setlocale().
23324ae1
FM
586 Compare GetCanonicalName().
587 */
328f5751 588 wxString GetSysName() const;
23324ae1
FM
589
590 /**
591 Tries to detect the user's default font encoding.
969daeea
FM
592 Returns wxFontEncoding() value or @c wxFONTENCODING_SYSTEM if it
593 couldn't be determined.
23324ae1 594 */
328f5751 595 static wxFontEncoding GetSystemEncoding() const;
23324ae1
FM
596
597 /**
969daeea
FM
598 Tries to detect the name of the user's default font encoding.
599 This string isn't particularly useful for the application as its form is
600 platform-dependent and so you should probably use GetSystemEncoding() instead.
601
23324ae1
FM
602 Returns a user-readable string value or an empty string if it couldn't be
603 determined.
604 */
328f5751 605 static wxString GetSystemEncodingName() const;
23324ae1
FM
606
607 /**
608 Tries to detect the user's default language setting.
d5c8403a 609 Returns the ::wxLanguage value or @b wxLANGUAGE_UNKNOWN if the language-guessing
969daeea 610 algorithm failed.
23324ae1 611 */
328f5751 612 static int GetSystemLanguage() const;
23324ae1 613
23324ae1 614 /**
969daeea
FM
615 Initializes the wxLocale instance.
616
617 The call of this function has several global side effects which you should
618 understand: first of all, the application locale is changed - note that
619 this will affect many of standard C library functions such as printf()
620 or strftime().
621 Second, this wxLocale object becomes the new current global locale for
622 the application and so all subsequent calls to wxGetTranslation() will
623 try to translate the messages using the message catalogs for this locale.
3c4f71cc 624
7c913512 625 @param language
d5c8403a 626 ::wxLanguage identifier of the locale.
969daeea
FM
627 @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's
628 default language (see GetSystemLanguage()).
7c913512 629 @param flags
4cc4bfaf 630 Combination of the following:
969daeea
FM
631 - wxLOCALE_LOAD_DEFAULT: Load the message catalog for the given locale
632 containing the translations of standard wxWidgets messages
633 automatically.
634 - wxLOCALE_CONV_ENCODING: Automatically convert message catalogs to
635 platform's default encoding. Note that it will do only basic
636 conversion between well-known pair like iso8859-1 and windows-1252 or
637 iso8859-2 and windows-1250. See @ref overview_nonenglish for
638 detailed description of this behaviour.
639 Note that this flag is meaningless in Unicode build.
89bb3f02
FM
640
641 @return @true on success or @false if the given locale couldn't be set.
642 */
643 bool Init(int language = wxLANGUAGE_DEFAULT,
644 int flags = wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING);
645
646 /**
647 @deprecated
648 This form is deprecated, use the other one unless you know what you are doing.
649
4cc4bfaf
FM
650 @param name
651 The name of the locale. Only used in diagnostic messages.
652 @param short
653 The standard 2 letter locale abbreviation; it is used as the
654 directory prefix when looking for the message catalog files.
655 @param locale
969daeea
FM
656 The parameter for the call to setlocale().
657 Note that it is platform-specific.
4cc4bfaf 658 @param bLoadDefault
969daeea
FM
659 May be set to @false to prevent loading of the message catalog for the
660 given locale containing the translations of standard wxWidgets messages.
4cc4bfaf 661 This parameter would be rarely used in normal circumstances.
7c913512 662 @param bConvertEncoding
969daeea
FM
663 May be set to @true to do automatic conversion of message catalogs to
664 platform's native encoding. Note that it will do only basic conversion
665 between well-known pair like iso8859-1 and windows-1252 or iso8859-2
666 and windows-1250.
667 See @ref overview_nonenglish for detailed description of this behaviour.
969daeea 668 */
7323ff1a
FM
669 bool Init(const wxString& name, const wxString& short = wxEmptyString,
670 const wxString& locale = wxEmptyString, bool bLoadDefault = true,
4cc4bfaf 671 bool bConvertEncoding = false);
23324ae1
FM
672
673 /**
674 Check whether the operating system and/or C run time environment supports
675 this locale. For example in Windows 2000 and Windows XP, support for many
676 locales is not installed by default. Returns @true if the locale is
677 supported.
d5c8403a
FM
678
679 The argument @a lang is the ::wxLanguage identifier. To obtain this for a
680 given a two letter ISO language code, use FindLanguageInfo() to obtain its
681 wxLanguageInfo structure.
682 See AddLanguage() for the wxLanguageInfo description.
3c4f71cc 683
1e24c2af 684 @since 2.7.1.
23324ae1
FM
685 */
686 static bool IsAvailable(int lang);
687
688 /**
689 Check if the given catalog is loaded, and returns @true if it is.
969daeea
FM
690
691 According to GNU gettext tradition, each catalog normally corresponds to
692 'domain' which is more or less the application name.
693
694 @see AddCatalog()
23324ae1 695 */
43c48e1e 696 bool IsLoaded(const wxString& domain) const;
23324ae1
FM
697
698 /**
699 Returns @true if the locale could be set successfully.
700 */
328f5751 701 bool IsOk() const;
23324ae1
FM
702};
703
704
e54c96f1 705
e54c96f1 706
23324ae1
FM
707// ============================================================================
708// Global functions/macros
709// ============================================================================
710
3950d49c
BP
711/** @ingroup group_funcmacro_string */
712//@{
713
23324ae1 714/**
3950d49c
BP
715 This macro is identical to _() but for the plural variant of
716 wxGetTranslation().
717
d29a9a8a 718 @return A const wxString.
3950d49c
BP
719
720 @header{wx/intl.h}
23324ae1 721*/
3950d49c 722#define wxPLURAL(string, plural, n)
23324ae1
FM
723
724/**
3950d49c
BP
725 This macro doesn't do anything in the program code -- it simply expands to
726 the value of its argument.
727
23324ae1
FM
728 However it does have a purpose which is to mark the literal strings for the
729 extraction into the message catalog created by @c xgettext program. Usually
3950d49c
BP
730 this is achieved using _() but that macro not only marks the string for
731 extraction but also expands into a wxGetTranslation() call which means that
732 it cannot be used in some situations, notably for static array
23324ae1 733 initialization.
3950d49c 734
23324ae1
FM
735 Here is an example which should make it more clear: suppose that you have a
736 static array of strings containing the weekday names and which have to be
3950d49c
BP
737 translated (note that it is a bad example, really, as wxDateTime already
738 can be used to get the localized week day names already). If you write:
4cc4bfaf 739
23324ae1
FM
740 @code
741 static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
742 ...
743 // use weekdays[n] as usual
744 @endcode
7c913512 745
3950d49c
BP
746 The code wouldn't compile because the function calls are forbidden in the
747 array initializer. So instead you should do this:
4cc4bfaf 748
23324ae1
FM
749 @code
750 static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
751 wxTRANSLATE("Sun") };
752 ...
753 // use wxGetTranslation(weekdays[n])
754 @endcode
7c913512 755
23324ae1 756 Note that although the code @b would compile if you simply omit
3950d49c
BP
757 wxTRANSLATE() in the above, it wouldn't work as expected because there
758 would be no translations for the weekday names in the program message
759 catalog and wxGetTranslation() wouldn't find them.
760
d29a9a8a 761 @return A const wxChar*.
3950d49c
BP
762
763 @header{wx/intl.h}
23324ae1 764*/
3950d49c 765#define wxTRANSLATE(string)
23324ae1
FM
766
767/**
3950d49c
BP
768 This function returns the translation of @a string in the current
769 @c locale(). If the string is not found in any of the loaded message
770 catalogs (see @ref overview_i18n), the original string is returned. In
771 debug build, an error message is logged -- this should help to find the
772 strings which were not yet translated. If @a domain is specified then only
773 that domain/catalog is searched for a matching string. As this function is
774 used very often, an alternative (and also common in Unix world) syntax is
775 provided: the _() macro is defined to do the same thing as
776 wxGetTranslation().
777
778 This function calls wxLocale::GetString().
779
780 @note This function is not suitable for literal strings in Unicode builds
781 since the literal strings must be enclosed into _T() or wxT() macro
782 which makes them unrecognised by @c xgettext, and so they are not
783 extracted to the message catalog. Instead, use the _() and wxPLURAL()
784 macro for all literal strings.
785
786 @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
787
788 @header{wx/intl.h}
23324ae1 789*/
969daeea 790const wxString& wxGetTranslation(const wxString& string,
3950d49c 791 const wxString& domain = wxEmptyString);
23324ae1 792
23324ae1 793/**
3950d49c
BP
794 This is an overloaded version of
795 wxGetTranslation(const wxString&, const wxString&), please see its
796 documentation for general information.
797
798 This version is used when retrieving translation of string that has
799 different singular and plural forms in English or different plural forms in
800 some other language. Like wxGetTranslation(const wxString&,const wxString&),
801 the @a string parameter must contain the singular form of the string to be
802 converted and is used as the key for the search in the catalog. The
803 @a plural parameter is the plural form (in English). The parameter @a n is
804 used to determine the plural form. If no message catalog is found,
805 @a string is returned if "n == 1", otherwise @a plural is returned.
806
807 See GNU gettext Manual for additional information on plural forms handling:
808 <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
809 For a shorter alternative see the wxPLURAL() macro.
810
811 This function calls wxLocale::GetString().
812
813 @header{wx/intl.h}
23324ae1 814*/
969daeea 815const wxString& wxGetTranslation(const wxString& string,
3950d49c
BP
816 const wxString& plural, size_t n,
817 const wxString& domain = wxEmptyString);
818
819/**
820 This macro expands into a call to wxGetTranslation(), so it marks the
821 message for the extraction by @c xgettext just as wxTRANSLATE() does, but
822 also returns the translation of the string for the current locale during
823 execution.
824
825 Don't confuse this with _T()!
826
827 @header{wx/intl.h}
828*/
969daeea 829const wxString& _(const wxString& string);
3950d49c 830
23324ae1
FM
831//@}
832