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