]>
Commit | Line | Data |
---|---|---|
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 | struct WXDLLIMPEXP_BASE wxLanguageInfo | |
283 | { | |
284 | /// ::wxLanguage id. | |
285 | /// It should be greater than @c wxLANGUAGE_USER_DEFINED when defining your own | |
286 | /// language info structure. | |
287 | int Language; | |
288 | ||
289 | /// Canonical name of the language, e.g. @c fr_FR. | |
290 | wxString CanonicalName; | |
291 | ||
292 | //@{ | |
293 | /** | |
294 | Win32 language identifiers (LANG_xxxx, SUBLANG_xxxx). | |
295 | ||
296 | @onlyfor{wxmsw} | |
297 | */ | |
298 | wxUint32 WinLang, WinSublang; | |
299 | //@} | |
300 | ||
301 | /// Human-readable name of the language. | |
302 | wxString Description; | |
303 | ||
304 | /// The layout direction used for this language. | |
305 | wxLayoutDirection LayoutDirection; | |
306 | ||
307 | /// Return the LCID corresponding to this language. | |
308 | /// @onlyfor{wxmsw} | |
309 | wxUint32 GetLCID() const; | |
310 | ||
311 | /// Return the locale name corresponding to this language usable with | |
312 | /// @c setlocale() on the current system. | |
313 | wxString GetLocaleName() const; | |
314 | }; | |
315 | ||
316 | ||
317 | /** | |
318 | The category of locale settings. | |
319 | ||
320 | @see wxLocale::GetInfo() | |
321 | */ | |
322 | enum wxLocaleCategory | |
323 | { | |
324 | /// Number formatting. | |
325 | wxLOCALE_CAT_NUMBER, | |
326 | ||
327 | /// Date/time formatting. | |
328 | wxLOCALE_CAT_DATE, | |
329 | ||
330 | /// Monetary values formatting. | |
331 | wxLOCALE_CAT_MONEY, | |
332 | ||
333 | /** | |
334 | Default category for the wxLocaleInfo value. | |
335 | ||
336 | This category can be used for values which only make sense for a single | |
337 | category, e.g. wxLOCALE_SHORT_DATE_FMT which can only be used with | |
338 | wxLOCALE_CAT_DATE. As this is the default value of the second parameter | |
339 | of wxLocale::GetInfo(), wxLOCALE_CAT_DATE can be omitted when asking | |
340 | for wxLOCALE_SHORT_DATE_FMT value. | |
341 | ||
342 | @since 2.9.0 | |
343 | */ | |
344 | wxLOCALE_CAT_DEFAULT | |
345 | }; | |
346 | ||
347 | /** | |
348 | The values understood by wxLocale::GetInfo(). | |
349 | ||
350 | Note that for the @c wxLOCALE_*_FMT constants (the date and time formats), | |
351 | the strings returned by wxLocale::GetInfo() use strftime() or, | |
352 | equivalently, wxDateTime::Format() format. If the relevant format | |
353 | couldn't be determined, an empty string is returned -- there is no | |
354 | fallback value so that the application could determine the best course | |
355 | of actions itself in such case. | |
356 | ||
357 | All of these values are used with @c wxLOCALE_CAT_DATE in wxLocale::GetInfo() or, | |
358 | more typically, with @c wxLOCALE_CAT_DEFAULT as they only apply to a single category. | |
359 | */ | |
360 | enum wxLocaleInfo | |
361 | { | |
362 | /** | |
363 | The thousands separator. | |
364 | ||
365 | This value can be used with either wxLOCALE_CAT_NUMBER or | |
366 | wxLOCALE_CAT_MONEY categories. | |
367 | */ | |
368 | wxLOCALE_THOUSANDS_SEP, | |
369 | ||
370 | /** | |
371 | The character used as decimal point. | |
372 | ||
373 | This value can be used with either wxLOCALE_CAT_NUMBER or | |
374 | wxLOCALE_CAT_MONEY categories. | |
375 | */ | |
376 | wxLOCALE_DECIMAL_POINT, | |
377 | ||
378 | /** | |
379 | Short date format. | |
380 | ||
381 | Notice that short and long date formats may be the same under POSIX | |
382 | systems currently but may, and typically are, different under MSW or OS X. | |
383 | ||
384 | @since 2.9.0 | |
385 | */ | |
386 | wxLOCALE_SHORT_DATE_FMT, | |
387 | ||
388 | /** | |
389 | Long date format. | |
390 | ||
391 | @since 2.9.0 | |
392 | */ | |
393 | wxLOCALE_LONG_DATE_FMT, | |
394 | ||
395 | /** | |
396 | Date and time format. | |
397 | ||
398 | @since 2.9.0 | |
399 | */ | |
400 | wxLOCALE_DATE_TIME_FMT, | |
401 | ||
402 | /** | |
403 | Time format. | |
404 | ||
405 | @since 2.9.0 | |
406 | */ | |
407 | wxLOCALE_TIME_FMT | |
408 | }; | |
409 | ||
410 | ||
411 | /** | |
412 | @class wxLocale | |
413 | ||
414 | wxLocale class encapsulates all language-dependent settings and is a | |
415 | generalization of the C locale concept. | |
416 | ||
417 | In wxWidgets this class manages message catalogs which contain the translations | |
418 | of the strings used to the current language. | |
419 | ||
420 | For a list of the supported languages, please see ::wxLanguage enum values. | |
421 | These constants may be used to specify the language in wxLocale::Init and | |
422 | are returned by wxLocale::GetSystemLanguage. | |
423 | ||
424 | @beginWxPerlOnly | |
425 | In wxPerl you can't use the '_' function name, so | |
426 | the @c Wx::Locale module can export the @c gettext and | |
427 | @c gettext_noop under any given name. | |
428 | ||
429 | @code | |
430 | # this imports gettext ( equivalent to Wx::GetTranslation | |
431 | # and gettext_noop ( a noop ) | |
432 | # into your module | |
433 | use Wx::Locale qw(:default); | |
434 | ||
435 | # .... | |
436 | ||
437 | # use the functions | |
438 | print gettext( "Panic!" ); | |
439 | ||
440 | button = Wx::Button-new( window, -1, gettext( "Label" ) ); | |
441 | @endcode | |
442 | ||
443 | If you need to translate a lot of strings, then adding gettext( ) around | |
444 | each one is a long task ( that is why _( ) was introduced ), so just choose | |
445 | a shorter name for gettext: | |
446 | ||
447 | @code | |
448 | use Wx::Locale 'gettext' = 't', | |
449 | 'gettext_noop' = 'gettext_noop'; | |
450 | ||
451 | # ... | |
452 | ||
453 | # use the functions | |
454 | print t( "Panic!!" ); | |
455 | ||
456 | # ... | |
457 | @endcode | |
458 | @endWxPerlOnly | |
459 | ||
460 | @library{wxbase} | |
461 | @category{cfg} | |
462 | ||
463 | @see @ref overview_i18n, @ref page_samples_internat, wxXLocale | |
464 | */ | |
465 | class wxLocale | |
466 | { | |
467 | public: | |
468 | /** | |
469 | This is the default constructor and it does nothing to initialize the object: | |
470 | Init() must be used to do that. | |
471 | */ | |
472 | wxLocale(); | |
473 | ||
474 | /** | |
475 | See Init() for parameters description. | |
476 | */ | |
477 | wxLocale(int language, | |
478 | int flags = wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); | |
479 | ||
480 | /** | |
481 | See Init() for parameters description. | |
482 | ||
483 | The call of this function has several global side effects which you should | |
484 | understand: first of all, the application locale is changed - note that this | |
485 | will affect many of standard C library functions such as printf() or strftime(). | |
486 | Second, this wxLocale object becomes the new current global locale for the | |
487 | application and so all subsequent calls to ::wxGetTranslation() will try to | |
488 | translate the messages using the message catalogs for this locale. | |
489 | */ | |
490 | wxLocale(const wxString& name, | |
491 | const wxString& short = wxEmptyString, | |
492 | const wxString& locale = wxEmptyString, | |
493 | bool bLoadDefault = true, | |
494 | bool bConvertEncoding = false); | |
495 | ||
496 | /** | |
497 | The destructor, like the constructor, also has global side effects: the | |
498 | previously set locale is restored and so the changes described in | |
499 | Init() documentation are rolled back. | |
500 | */ | |
501 | virtual ~wxLocale(); | |
502 | ||
503 | /** | |
504 | Add a catalog for use with the current locale: it is searched for in standard | |
505 | places (current directory first, then the system one), but you may also prepend | |
506 | additional directories to the search path with AddCatalogLookupPathPrefix(). | |
507 | ||
508 | All loaded catalogs will be used for message lookup by GetString() for | |
509 | the current locale. | |
510 | ||
511 | In this overload, @c msgid strings are assumed | |
512 | to be in English and written only using 7-bit ASCII characters. | |
513 | If you have to deal with non-English strings or 8-bit characters in the | |
514 | source code, see the instructions in @ref overview_nonenglish. | |
515 | ||
516 | @return | |
517 | @true if catalog was successfully loaded, @false otherwise (which might | |
518 | mean that the catalog is not found or that it isn't in the correct format). | |
519 | */ | |
520 | bool AddCatalog(const wxString& domain); | |
521 | ||
522 | /** | |
523 | Add a catalog for use with the current locale: it is searched for in standard | |
524 | places (current directory first, then the system one), but you may also prepend | |
525 | additional directories to the search path with AddCatalogLookupPathPrefix(). | |
526 | ||
527 | All loaded catalogs will be used for message lookup by GetString() for | |
528 | the current locale. | |
529 | ||
530 | This overload takes two additional arguments, @a msgIdLanguage and @a msgIdCharset. | |
531 | ||
532 | @param domain | |
533 | The catalog domain to add. | |
534 | ||
535 | @param msgIdLanguage | |
536 | Specifies the language of "msgid" strings in source code | |
537 | (i.e. arguments to GetString(), wxGetTranslation() and the _() macro). | |
538 | It is used if AddCatalog() cannot find any catalog for current language: | |
539 | if the language is same as source code language, then strings from source | |
540 | code are used instead. | |
541 | ||
542 | @param msgIdCharset | |
543 | Lets you specify the charset used for msgids in sources | |
544 | in case they use 8-bit characters (e.g. German or French strings). | |
545 | This argument has no effect in Unicode build, because literals in sources are | |
546 | Unicode strings; you have to use compiler-specific method of setting the right | |
547 | charset when compiling with Unicode. | |
548 | ||
549 | @return | |
550 | @true if catalog was successfully loaded, @false otherwise (which might | |
551 | mean that the catalog is not found or that it isn't in the correct format). | |
552 | */ | |
553 | bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage, | |
554 | const wxString& msgIdCharset); | |
555 | ||
556 | /** | |
557 | Add a prefix to the catalog lookup path: the message catalog files will | |
558 | be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix | |
559 | (in this order). | |
560 | ||
561 | This only applies to subsequent invocations of AddCatalog(). | |
562 | */ | |
563 | static void AddCatalogLookupPathPrefix(const wxString& prefix); | |
564 | ||
565 | /** | |
566 | Adds custom, user-defined language to the database of known languages. | |
567 | This database is used in conjunction with the first form of Init(). | |
568 | */ | |
569 | static void AddLanguage(const wxLanguageInfo& info); | |
570 | ||
571 | /** | |
572 | This function may be used to find the language description structure for the | |
573 | given locale, specified either as a two letter ISO language code (for example, | |
574 | "pt"), a language code followed by the country code ("pt_BR") or a full, human | |
575 | readable, language description ("Portuguese-Brazil"). | |
576 | ||
577 | Returns the information for the given language or @NULL if this language | |
578 | is unknown. Note that even if the returned pointer is valid, the caller | |
579 | should @e not delete it. | |
580 | ||
581 | @see GetLanguageInfo() | |
582 | */ | |
583 | static const wxLanguageInfo* FindLanguageInfo(const wxString& locale); | |
584 | ||
585 | /** | |
586 | Returns the canonical form of current locale name. Canonical form is the | |
587 | one that is used on UNIX systems: it is a two- or five-letter string in xx or | |
588 | xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of | |
589 | the country. Examples are "en", "en_GB", "en_US" or "fr_FR". | |
590 | This form is internally used when looking up message catalogs. | |
591 | Compare GetSysName(). | |
592 | */ | |
593 | wxString GetCanonicalName() const; | |
594 | ||
595 | /** | |
596 | Returns the header value for header @a header. | |
597 | The search for @a header is case sensitive. If an @a domain is passed, | |
598 | this domain is searched. Else all domains will be searched until a | |
599 | header has been found. | |
600 | ||
601 | The return value is the value of the header if found. Else this will be empty. | |
602 | */ | |
603 | wxString GetHeaderValue(const wxString& header, | |
604 | const wxString& domain = wxEmptyString) const; | |
605 | ||
606 | /** | |
607 | Returns the ::wxLanguage constant of current language. | |
608 | ||
609 | Note that you can call this function only if you used the form of | |
610 | Init() that takes ::wxLanguage argument. | |
611 | */ | |
612 | int GetLanguage() const; | |
613 | ||
614 | /** | |
615 | Returns a pointer to wxLanguageInfo structure containing information about | |
616 | the given language or @NULL if this language is unknown. Note that even if | |
617 | the returned pointer is valid, the caller should @e not delete it. | |
618 | ||
619 | See AddLanguage() for the wxLanguageInfo description. | |
620 | As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed | |
621 | as an argument to this function and in this case the result of | |
622 | GetSystemLanguage() is used. | |
623 | */ | |
624 | static const wxLanguageInfo* GetLanguageInfo(int lang); | |
625 | ||
626 | /** | |
627 | Returns English name of the given language or empty string if this | |
628 | language is unknown. | |
629 | ||
630 | See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT. | |
631 | */ | |
632 | static wxString GetLanguageName(int lang); | |
633 | ||
634 | /** | |
635 | Returns the locale name as passed to the constructor or Init(). | |
636 | ||
637 | This is a full, human-readable name, e.g. "English" or "French". | |
638 | */ | |
639 | const wxString& GetLocale() const; | |
640 | ||
641 | /** | |
642 | Returns the current short name for the locale (as given to the constructor or | |
643 | the Init() function). | |
644 | */ | |
645 | const wxString& GetName() const; | |
646 | ||
647 | /** | |
648 | Retrieves the translation for a string in all loaded domains unless the @a domain | |
649 | parameter is specified (and then only this catalog/domain is searched). | |
650 | ||
651 | Returns original string if translation is not available (in this case an | |
652 | error message is generated the first time a string is not found; use | |
653 | wxLogNull to suppress it). | |
654 | ||
655 | @remarks Domains are searched in the last to first order, i.e. catalogs | |
656 | added later override those added before. | |
657 | */ | |
658 | virtual const wxString& GetString(const wxString& origString, | |
659 | const wxString& domain = wxEmptyString) const; | |
660 | ||
661 | /** | |
662 | Retrieves the translation for a string in all loaded domains unless the @a domain | |
663 | parameter is specified (and then only this catalog/domain is searched). | |
664 | ||
665 | Returns original string if translation is not available (in this case an | |
666 | error message is generated the first time a string is not found; use | |
667 | wxLogNull to suppress it). | |
668 | ||
669 | This form is used when retrieving translation of string that has different | |
670 | singular and plural form in English or different plural forms in some | |
671 | other language. | |
672 | It takes two extra arguments: @a origString parameter must contain the | |
673 | singular form of the string to be converted. | |
674 | ||
675 | It is also used as the key for the search in the catalog. | |
676 | The @a origString2 parameter is the plural form (in English). | |
677 | ||
678 | The parameter @a n is used to determine the plural form. | |
679 | If no message catalog is found @a origString is returned if 'n == 1', | |
680 | otherwise @a origString2. | |
681 | ||
682 | See GNU gettext manual for additional information on plural forms handling. | |
683 | This method is called by the wxGetTranslation() function and _() macro. | |
684 | ||
685 | @remarks Domains are searched in the last to first order, i.e. catalogs | |
686 | added later override those added before. | |
687 | */ | |
688 | virtual const wxString& GetString(const wxString& origString, | |
689 | const wxString& origString2, size_t n, | |
690 | const wxString& domain = wxEmptyString) const; | |
691 | ||
692 | /** | |
693 | Returns current platform-specific locale name as passed to setlocale(). | |
694 | Compare GetCanonicalName(). | |
695 | */ | |
696 | wxString GetSysName() const; | |
697 | ||
698 | /** | |
699 | Tries to detect the user's default font encoding. | |
700 | Returns wxFontEncoding() value or @c wxFONTENCODING_SYSTEM if it | |
701 | couldn't be determined. | |
702 | */ | |
703 | static wxFontEncoding GetSystemEncoding(); | |
704 | ||
705 | /** | |
706 | Tries to detect the name of the user's default font encoding. | |
707 | This string isn't particularly useful for the application as its form is | |
708 | platform-dependent and so you should probably use GetSystemEncoding() instead. | |
709 | ||
710 | Returns a user-readable string value or an empty string if it couldn't be | |
711 | determined. | |
712 | */ | |
713 | static wxString GetSystemEncodingName(); | |
714 | ||
715 | /** | |
716 | Tries to detect the user's default language setting. | |
717 | ||
718 | Returns the ::wxLanguage value or @c wxLANGUAGE_UNKNOWN if the language-guessing | |
719 | algorithm failed. | |
720 | */ | |
721 | static int GetSystemLanguage(); | |
722 | ||
723 | /** | |
724 | Get the values of the given locale-dependent datum. | |
725 | ||
726 | This function returns the value of the locale-specific option specified | |
727 | by the given @a index. | |
728 | ||
729 | @param index | |
730 | One of the elements of wxLocaleInfo enum. | |
731 | @param cat | |
732 | The category to use with the given index or wxLOCALE_CAT_DEFAULT if | |
733 | the index can only apply to a single category. | |
734 | @return | |
735 | The option value or empty string if the function failed. | |
736 | */ | |
737 | static wxString GetInfo(wxLocaleInfo index, | |
738 | wxLocaleCategory cat = wxLOCALE_CAT_DEFAULT); | |
739 | ||
740 | /** | |
741 | Initializes the wxLocale instance. | |
742 | ||
743 | The call of this function has several global side effects which you should | |
744 | understand: first of all, the application locale is changed - note that | |
745 | this will affect many of standard C library functions such as printf() | |
746 | or strftime(). | |
747 | Second, this wxLocale object becomes the new current global locale for | |
748 | the application and so all subsequent calls to wxGetTranslation() will | |
749 | try to translate the messages using the message catalogs for this locale. | |
750 | ||
751 | @param language | |
752 | ::wxLanguage identifier of the locale. | |
753 | @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's | |
754 | default language (see GetSystemLanguage()). | |
755 | @param flags | |
756 | Combination of the following: | |
757 | - wxLOCALE_LOAD_DEFAULT: Load the message catalog for the given locale | |
758 | containing the translations of standard wxWidgets messages | |
759 | automatically. | |
760 | - wxLOCALE_CONV_ENCODING: Automatically convert message catalogs to | |
761 | platform's default encoding. Note that it will do only basic | |
762 | conversion between well-known pair like iso8859-1 and windows-1252 or | |
763 | iso8859-2 and windows-1250. See @ref overview_nonenglish for | |
764 | detailed description of this behaviour. | |
765 | Note that this flag is meaningless in Unicode build. | |
766 | ||
767 | @return @true on success or @false if the given locale couldn't be set. | |
768 | */ | |
769 | bool Init(int language = wxLANGUAGE_DEFAULT, | |
770 | int flags = wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); | |
771 | ||
772 | /** | |
773 | @deprecated | |
774 | This form is deprecated, use the other one unless you know what you are doing. | |
775 | ||
776 | @param name | |
777 | The name of the locale. Only used in diagnostic messages. | |
778 | @param short | |
779 | The standard 2 letter locale abbreviation; it is used as the | |
780 | directory prefix when looking for the message catalog files. | |
781 | @param locale | |
782 | The parameter for the call to setlocale(). | |
783 | Note that it is platform-specific. | |
784 | @param bLoadDefault | |
785 | May be set to @false to prevent loading of the message catalog for the | |
786 | given locale containing the translations of standard wxWidgets messages. | |
787 | This parameter would be rarely used in normal circumstances. | |
788 | @param bConvertEncoding | |
789 | May be set to @true to do automatic conversion of message catalogs to | |
790 | platform's native encoding. Note that it will do only basic conversion | |
791 | between well-known pair like iso8859-1 and windows-1252 or iso8859-2 | |
792 | and windows-1250. | |
793 | See @ref overview_nonenglish for detailed description of this behaviour. | |
794 | */ | |
795 | bool Init(const wxString& name, const wxString& short = wxEmptyString, | |
796 | const wxString& locale = wxEmptyString, bool bLoadDefault = true, | |
797 | bool bConvertEncoding = false); | |
798 | ||
799 | /** | |
800 | Check whether the operating system and/or C run time environment supports | |
801 | this locale. For example in Windows 2000 and Windows XP, support for many | |
802 | locales is not installed by default. Returns @true if the locale is | |
803 | supported. | |
804 | ||
805 | The argument @a lang is the ::wxLanguage identifier. To obtain this for a | |
806 | given a two letter ISO language code, use FindLanguageInfo() to obtain its | |
807 | wxLanguageInfo structure. | |
808 | See AddLanguage() for the wxLanguageInfo description. | |
809 | ||
810 | @since 2.7.1. | |
811 | */ | |
812 | static bool IsAvailable(int lang); | |
813 | ||
814 | /** | |
815 | Check if the given catalog is loaded, and returns @true if it is. | |
816 | ||
817 | According to GNU gettext tradition, each catalog normally corresponds to | |
818 | 'domain' which is more or less the application name. | |
819 | ||
820 | @see AddCatalog() | |
821 | */ | |
822 | bool IsLoaded(const wxString& domain) const; | |
823 | ||
824 | /** | |
825 | Returns @true if the locale could be set successfully. | |
826 | */ | |
827 | bool IsOk() const; | |
828 | }; | |
829 | ||
830 | ||
831 | ||
832 | ||
833 | // ============================================================================ | |
834 | // Global functions/macros | |
835 | // ============================================================================ | |
836 | ||
837 | /** @addtogroup group_funcmacro_string */ | |
838 | //@{ | |
839 | ||
840 | /** | |
841 | This macro is identical to _() but for the plural variant of | |
842 | wxGetTranslation(). | |
843 | ||
844 | @return A const wxString. | |
845 | ||
846 | @header{wx/intl.h} | |
847 | */ | |
848 | #define wxPLURAL(string, plural, n) | |
849 | ||
850 | /** | |
851 | This macro doesn't do anything in the program code -- it simply expands to | |
852 | the value of its argument. | |
853 | ||
854 | However it does have a purpose which is to mark the literal strings for the | |
855 | extraction into the message catalog created by @c xgettext program. Usually | |
856 | this is achieved using _() but that macro not only marks the string for | |
857 | extraction but also expands into a wxGetTranslation() call which means that | |
858 | it cannot be used in some situations, notably for static array | |
859 | initialization. | |
860 | ||
861 | Here is an example which should make it more clear: suppose that you have a | |
862 | static array of strings containing the weekday names and which have to be | |
863 | translated (note that it is a bad example, really, as wxDateTime already | |
864 | can be used to get the localized week day names already). If you write: | |
865 | ||
866 | @code | |
867 | static const char * const weekdays[] = { _("Mon"), ..., _("Sun") }; | |
868 | ... | |
869 | // use weekdays[n] as usual | |
870 | @endcode | |
871 | ||
872 | The code wouldn't compile because the function calls are forbidden in the | |
873 | array initializer. So instead you should do this: | |
874 | ||
875 | @code | |
876 | static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., | |
877 | wxTRANSLATE("Sun") }; | |
878 | ... | |
879 | // use wxGetTranslation(weekdays[n]) | |
880 | @endcode | |
881 | ||
882 | Note that although the code @b would compile if you simply omit | |
883 | wxTRANSLATE() in the above, it wouldn't work as expected because there | |
884 | would be no translations for the weekday names in the program message | |
885 | catalog and wxGetTranslation() wouldn't find them. | |
886 | ||
887 | @return A const wxChar*. | |
888 | ||
889 | @header{wx/intl.h} | |
890 | */ | |
891 | #define wxTRANSLATE(string) | |
892 | ||
893 | /** | |
894 | This function returns the translation of @a string in the current | |
895 | @c locale(). If the string is not found in any of the loaded message | |
896 | catalogs (see @ref overview_i18n), the original string is returned. In | |
897 | debug build, an error message is logged -- this should help to find the | |
898 | strings which were not yet translated. If @a domain is specified then only | |
899 | that domain/catalog is searched for a matching string. As this function is | |
900 | used very often, an alternative (and also common in Unix world) syntax is | |
901 | provided: the _() macro is defined to do the same thing as | |
902 | wxGetTranslation(). | |
903 | ||
904 | This function calls wxLocale::GetString(). | |
905 | ||
906 | @note This function is not suitable for literal strings in Unicode builds | |
907 | since the literal strings must be enclosed into _T() or wxT() macro | |
908 | which makes them unrecognised by @c xgettext, and so they are not | |
909 | extracted to the message catalog. Instead, use the _() and wxPLURAL() | |
910 | macro for all literal strings. | |
911 | ||
912 | @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&) | |
913 | ||
914 | @header{wx/intl.h} | |
915 | */ | |
916 | const wxString& wxGetTranslation(const wxString& string, | |
917 | const wxString& domain = wxEmptyString); | |
918 | ||
919 | /** | |
920 | This is an overloaded version of | |
921 | wxGetTranslation(const wxString&, const wxString&), please see its | |
922 | documentation for general information. | |
923 | ||
924 | This version is used when retrieving translation of string that has | |
925 | different singular and plural forms in English or different plural forms in | |
926 | some other language. Like wxGetTranslation(const wxString&,const wxString&), | |
927 | the @a string parameter must contain the singular form of the string to be | |
928 | converted and is used as the key for the search in the catalog. The | |
929 | @a plural parameter is the plural form (in English). The parameter @a n is | |
930 | used to determine the plural form. If no message catalog is found, | |
931 | @a string is returned if "n == 1", otherwise @a plural is returned. | |
932 | ||
933 | See GNU gettext Manual for additional information on plural forms handling: | |
934 | <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms> | |
935 | For a shorter alternative see the wxPLURAL() macro. | |
936 | ||
937 | This function calls wxLocale::GetString(). | |
938 | ||
939 | @header{wx/intl.h} | |
940 | */ | |
941 | const wxString& wxGetTranslation(const wxString& string, | |
942 | const wxString& plural, size_t n, | |
943 | const wxString& domain = wxEmptyString); | |
944 | ||
945 | /** | |
946 | This macro expands into a call to wxGetTranslation(), so it marks the | |
947 | message for the extraction by @c xgettext just as wxTRANSLATE() does, but | |
948 | also returns the translation of the string for the current locale during | |
949 | execution. | |
950 | ||
951 | Don't confuse this with _T()! | |
952 | ||
953 | @header{wx/intl.h} | |
954 | */ | |
955 | const wxString& _(const wxString& string); | |
956 | ||
957 | //@} | |
958 |