docs/latex/wx/locale.tex

   1 \section{\class{wxLocale}}\label{wxlocale}
   2
   3 wxLocale class encapsulates all language-dependent settings and is a
   4 generalization of the C locale concept.
   5
   6 In wxWidgets this class manages message catalogs which contain the translations
   7 of the strings used to the current language.
   8
   9 \perlnote{In wxPerl you can't use the '\_' function name, so
  10 the {\tt Wx::Locale} module can export the {\tt gettext} and
  11 {\tt gettext\_noop} under any given name.
  12
  13 \begin{verbatim}
  14   # this imports gettext ( equivalent to Wx::GetTranslation
  15   # and gettext_noop ( a noop )
  16   # into your module
  17   use Wx::Locale qw(:default);
  18
  19   # ....
  20
  21   # use the functions
  22   print gettext( ``Panic!'' );
  23
  24   button = Wx::Button->new( window, -1, gettext( ``Label'' ) );
  25 \end{verbatim}
  26
  27 If you need to translate a lot of strings, then adding gettext( ) around
  28 each one is a long task ( that is why \_( ) was introduced ), so just choose
  29 a shorter name for gettext:
  30
  31 \begin{verbatim}
  32   #
  33   use Wx::Locale 'gettext' => 't',
  34                  'gettext_noop' => 'gettext_noop';
  35
  36   # ...
  37
  38   # use the functions
  39   print t( ``Panic!!'' );
  40
  41   # ...
  42 \end{verbatim}
  43 }%
  44
  45 \wxheading{Derived from}
  46
  47 No base class
  48
  49 \wxheading{See also}
  50
  51 \helpref{Internationalization overview}{internationalization},\\
  52 \helpref{Internat sample}{sampleinternat}
  53
  54 \wxheading{Include files}
  55
  56 <wx/intl.h>
  57
  58
  59 \latexignore{\rtfignore{\wxheading{Members}}}
  60
  61
  62
  63 \membersection{Supported languages}\label{wxlanguage}
  64
  65 The following wxLanguage constants may be used to specify the language
  66 in \helpref{Init}{wxlocaleinit} and are returned by
  67 \helpref{GetSystemLanguage}{wxlocalegetsystemlanguage}:
  68
  69
  70
  71 %% --- --- --- generated code begins here --- --- ---
  72
  73 %% This enum is generated by misc/languages/genlang.py
  74 %% When making changes, please put them into misc/languages/langtabl.txt
  75 \begin{itemize}\itemsep=0pt
  76 \item wxLANGUAGE\_DEFAULT -- user's default language as obtained from the operating system
  77 \item wxLANGUAGE\_UNKNOWN -- returned by \helpref{GetSystemLanguage}{wxlocalegetsystemlanguage}
  78 if it fails to detect the default language
  79 \item wxLANGUAGE\_USER\_DEFINED -- user defined languages' integer identifiers should start from
  80 this
  81 \item wxLANGUAGE\_ABKHAZIAN
  82 \item wxLANGUAGE\_AFAR
  83 \item wxLANGUAGE\_AFRIKAANS
  84 \item wxLANGUAGE\_ALBANIAN
  85 \item wxLANGUAGE\_AMHARIC
  86 \item wxLANGUAGE\_ARABIC
  87 \item wxLANGUAGE\_ARABIC\_ALGERIA
  88 \item wxLANGUAGE\_ARABIC\_BAHRAIN
  89 \item wxLANGUAGE\_ARABIC\_EGYPT
  90 \item wxLANGUAGE\_ARABIC\_IRAQ
  91 \item wxLANGUAGE\_ARABIC\_JORDAN
  92 \item wxLANGUAGE\_ARABIC\_KUWAIT
  93 \item wxLANGUAGE\_ARABIC\_LEBANON
  94 \item wxLANGUAGE\_ARABIC\_LIBYA
  95 \item wxLANGUAGE\_ARABIC\_MOROCCO
  96 \item wxLANGUAGE\_ARABIC\_OMAN
  97 \item wxLANGUAGE\_ARABIC\_QATAR
  98 \item wxLANGUAGE\_ARABIC\_SAUDI\_ARABIA
  99 \item wxLANGUAGE\_ARABIC\_SUDAN
 100 \item wxLANGUAGE\_ARABIC\_SYRIA
 101 \item wxLANGUAGE\_ARABIC\_TUNISIA
 102 \item wxLANGUAGE\_ARABIC\_UAE
 103 \item wxLANGUAGE\_ARABIC\_YEMEN
 104 \item wxLANGUAGE\_ARMENIAN
 105 \item wxLANGUAGE\_ASSAMESE
 106 \item wxLANGUAGE\_AYMARA
 107 \item wxLANGUAGE\_AZERI
 108 \item wxLANGUAGE\_AZERI\_CYRILLIC
 109 \item wxLANGUAGE\_AZERI\_LATIN
 110 \item wxLANGUAGE\_BASHKIR
 111 \item wxLANGUAGE\_BASQUE
 112 \item wxLANGUAGE\_BELARUSIAN
 113 \item wxLANGUAGE\_BENGALI
 114 \item wxLANGUAGE\_BHUTANI
 115 \item wxLANGUAGE\_BIHARI
 116 \item wxLANGUAGE\_BISLAMA
 117 \item wxLANGUAGE\_BRETON
 118 \item wxLANGUAGE\_BULGARIAN
 119 \item wxLANGUAGE\_BURMESE
 120 \item wxLANGUAGE\_CAMBODIAN
 121 \item wxLANGUAGE\_CATALAN
 122 \item wxLANGUAGE\_CHINESE
 123 \item wxLANGUAGE\_CHINESE\_SIMPLIFIED
 124 \item wxLANGUAGE\_CHINESE\_TRADITIONAL
 125 \item wxLANGUAGE\_CHINESE\_HONGKONG
 126 \item wxLANGUAGE\_CHINESE\_MACAU
 127 \item wxLANGUAGE\_CHINESE\_SINGAPORE
 128 \item wxLANGUAGE\_CHINESE\_TAIWAN
 129 \item wxLANGUAGE\_CORSICAN
 130 \item wxLANGUAGE\_CROATIAN
 131 \item wxLANGUAGE\_CZECH
 132 \item wxLANGUAGE\_DANISH
 133 \item wxLANGUAGE\_DUTCH
 134 \item wxLANGUAGE\_DUTCH\_BELGIAN
 135 \item wxLANGUAGE\_ENGLISH
 136 \item wxLANGUAGE\_ENGLISH\_UK
 137 \item wxLANGUAGE\_ENGLISH\_US
 138 \item wxLANGUAGE\_ENGLISH\_AUSTRALIA
 139 \item wxLANGUAGE\_ENGLISH\_BELIZE
 140 \item wxLANGUAGE\_ENGLISH\_BOTSWANA
 141 \item wxLANGUAGE\_ENGLISH\_CANADA
 142 \item wxLANGUAGE\_ENGLISH\_CARIBBEAN
 143 \item wxLANGUAGE\_ENGLISH\_DENMARK
 144 \item wxLANGUAGE\_ENGLISH\_EIRE
 145 \item wxLANGUAGE\_ENGLISH\_JAMAICA
 146 \item wxLANGUAGE\_ENGLISH\_NEW\_ZEALAND
 147 \item wxLANGUAGE\_ENGLISH\_PHILIPPINES
 148 \item wxLANGUAGE\_ENGLISH\_SOUTH\_AFRICA
 149 \item wxLANGUAGE\_ENGLISH\_TRINIDAD
 150 \item wxLANGUAGE\_ENGLISH\_ZIMBABWE
 151 \item wxLANGUAGE\_ESPERANTO
 152 \item wxLANGUAGE\_ESTONIAN
 153 \item wxLANGUAGE\_FAEROESE
 154 \item wxLANGUAGE\_FARSI
 155 \item wxLANGUAGE\_FIJI
 156 \item wxLANGUAGE\_FINNISH
 157 \item wxLANGUAGE\_FRENCH
 158 \item wxLANGUAGE\_FRENCH\_BELGIAN
 159 \item wxLANGUAGE\_FRENCH\_CANADIAN
 160 \item wxLANGUAGE\_FRENCH\_LUXEMBOURG
 161 \item wxLANGUAGE\_FRENCH\_MONACO
 162 \item wxLANGUAGE\_FRENCH\_SWISS
 163 \item wxLANGUAGE\_FRISIAN
 164 \item wxLANGUAGE\_GALICIAN
 165 \item wxLANGUAGE\_GEORGIAN
 166 \item wxLANGUAGE\_GERMAN
 167 \item wxLANGUAGE\_GERMAN\_AUSTRIAN
 168 \item wxLANGUAGE\_GERMAN\_BELGIUM
 169 \item wxLANGUAGE\_GERMAN\_LIECHTENSTEIN
 170 \item wxLANGUAGE\_GERMAN\_LUXEMBOURG
 171 \item wxLANGUAGE\_GERMAN\_SWISS
 172 \item wxLANGUAGE\_GREEK
 173 \item wxLANGUAGE\_GREENLANDIC
 174 \item wxLANGUAGE\_GUARANI
 175 \item wxLANGUAGE\_GUJARATI
 176 \item wxLANGUAGE\_HAUSA
 177 \item wxLANGUAGE\_HEBREW
 178 \item wxLANGUAGE\_HINDI
 179 \item wxLANGUAGE\_HUNGARIAN
 180 \item wxLANGUAGE\_ICELANDIC
 181 \item wxLANGUAGE\_INDONESIAN
 182 \item wxLANGUAGE\_INTERLINGUA
 183 \item wxLANGUAGE\_INTERLINGUE
 184 \item wxLANGUAGE\_INUKTITUT
 185 \item wxLANGUAGE\_INUPIAK
 186 \item wxLANGUAGE\_IRISH
 187 \item wxLANGUAGE\_ITALIAN
 188 \item wxLANGUAGE\_ITALIAN\_SWISS
 189 \item wxLANGUAGE\_JAPANESE
 190 \item wxLANGUAGE\_JAVANESE
 191 \item wxLANGUAGE\_KANNADA
 192 \item wxLANGUAGE\_KASHMIRI
 193 \item wxLANGUAGE\_KASHMIRI\_INDIA
 194 \item wxLANGUAGE\_KAZAKH
 195 \item wxLANGUAGE\_KERNEWEK
 196 \item wxLANGUAGE\_KINYARWANDA
 197 \item wxLANGUAGE\_KIRGHIZ
 198 \item wxLANGUAGE\_KIRUNDI
 199 \item wxLANGUAGE\_KONKANI
 200 \item wxLANGUAGE\_KOREAN
 201 \item wxLANGUAGE\_KURDISH
 202 \item wxLANGUAGE\_LAOTHIAN
 203 \item wxLANGUAGE\_LATIN
 204 \item wxLANGUAGE\_LATVIAN
 205 \item wxLANGUAGE\_LINGALA
 206 \item wxLANGUAGE\_LITHUANIAN
 207 \item wxLANGUAGE\_MACEDONIAN
 208 \item wxLANGUAGE\_MALAGASY
 209 \item wxLANGUAGE\_MALAY
 210 \item wxLANGUAGE\_MALAYALAM
 211 \item wxLANGUAGE\_MALAY\_BRUNEI\_DARUSSALAM
 212 \item wxLANGUAGE\_MALAY\_MALAYSIA
 213 \item wxLANGUAGE\_MALTESE
 214 \item wxLANGUAGE\_MANIPURI
 215 \item wxLANGUAGE\_MAORI
 216 \item wxLANGUAGE\_MARATHI
 217 \item wxLANGUAGE\_MOLDAVIAN
 218 \item wxLANGUAGE\_MONGOLIAN
 219 \item wxLANGUAGE\_NAURU
 220 \item wxLANGUAGE\_NEPALI
 221 \item wxLANGUAGE\_NEPALI\_INDIA
 222 \item wxLANGUAGE\_NORWEGIAN\_BOKMAL
 223 \item wxLANGUAGE\_NORWEGIAN\_NYNORSK
 224 \item wxLANGUAGE\_OCCITAN
 225 \item wxLANGUAGE\_ORIYA
 226 \item wxLANGUAGE\_OROMO
 227 \item wxLANGUAGE\_PASHTO
 228 \item wxLANGUAGE\_POLISH
 229 \item wxLANGUAGE\_PORTUGUESE
 230 \item wxLANGUAGE\_PORTUGUESE\_BRAZILIAN
 231 \item wxLANGUAGE\_PUNJABI
 232 \item wxLANGUAGE\_QUECHUA
 233 \item wxLANGUAGE\_RHAETO\_ROMANCE
 234 \item wxLANGUAGE\_ROMANIAN
 235 \item wxLANGUAGE\_RUSSIAN
 236 \item wxLANGUAGE\_RUSSIAN\_UKRAINE
 237 \item wxLANGUAGE\_SAMOAN
 238 \item wxLANGUAGE\_SANGHO
 239 \item wxLANGUAGE\_SANSKRIT
 240 \item wxLANGUAGE\_SCOTS\_GAELIC
 241 \item wxLANGUAGE\_SERBIAN
 242 \item wxLANGUAGE\_SERBIAN\_CYRILLIC
 243 \item wxLANGUAGE\_SERBIAN\_LATIN
 244 \item wxLANGUAGE\_SERBO\_CROATIAN
 245 \item wxLANGUAGE\_SESOTHO
 246 \item wxLANGUAGE\_SETSWANA
 247 \item wxLANGUAGE\_SHONA
 248 \item wxLANGUAGE\_SINDHI
 249 \item wxLANGUAGE\_SINHALESE
 250 \item wxLANGUAGE\_SISWATI
 251 \item wxLANGUAGE\_SLOVAK
 252 \item wxLANGUAGE\_SLOVENIAN
 253 \item wxLANGUAGE\_SOMALI
 254 \item wxLANGUAGE\_SPANISH
 255 \item wxLANGUAGE\_SPANISH\_ARGENTINA
 256 \item wxLANGUAGE\_SPANISH\_BOLIVIA
 257 \item wxLANGUAGE\_SPANISH\_CHILE
 258 \item wxLANGUAGE\_SPANISH\_COLOMBIA
 259 \item wxLANGUAGE\_SPANISH\_COSTA\_RICA
 260 \item wxLANGUAGE\_SPANISH\_DOMINICAN\_REPUBLIC
 261 \item wxLANGUAGE\_SPANISH\_ECUADOR
 262 \item wxLANGUAGE\_SPANISH\_EL\_SALVADOR
 263 \item wxLANGUAGE\_SPANISH\_GUATEMALA
 264 \item wxLANGUAGE\_SPANISH\_HONDURAS
 265 \item wxLANGUAGE\_SPANISH\_MEXICAN
 266 \item wxLANGUAGE\_SPANISH\_MODERN
 267 \item wxLANGUAGE\_SPANISH\_NICARAGUA
 268 \item wxLANGUAGE\_SPANISH\_PANAMA
 269 \item wxLANGUAGE\_SPANISH\_PARAGUAY
 270 \item wxLANGUAGE\_SPANISH\_PERU
 271 \item wxLANGUAGE\_SPANISH\_PUERTO\_RICO
 272 \item wxLANGUAGE\_SPANISH\_URUGUAY
 273 \item wxLANGUAGE\_SPANISH\_US
 274 \item wxLANGUAGE\_SPANISH\_VENEZUELA
 275 \item wxLANGUAGE\_SUNDANESE
 276 \item wxLANGUAGE\_SWAHILI
 277 \item wxLANGUAGE\_SWEDISH
 278 \item wxLANGUAGE\_SWEDISH\_FINLAND
 279 \item wxLANGUAGE\_TAGALOG
 280 \item wxLANGUAGE\_TAJIK
 281 \item wxLANGUAGE\_TAMIL
 282 \item wxLANGUAGE\_TATAR
 283 \item wxLANGUAGE\_TELUGU
 284 \item wxLANGUAGE\_THAI
 285 \item wxLANGUAGE\_TIBETAN
 286 \item wxLANGUAGE\_TIGRINYA
 287 \item wxLANGUAGE\_TONGA
 288 \item wxLANGUAGE\_TSONGA
 289 \item wxLANGUAGE\_TURKISH
 290 \item wxLANGUAGE\_TURKMEN
 291 \item wxLANGUAGE\_TWI
 292 \item wxLANGUAGE\_UIGHUR
 293 \item wxLANGUAGE\_UKRAINIAN
 294 \item wxLANGUAGE\_URDU
 295 \item wxLANGUAGE\_URDU\_INDIA
 296 \item wxLANGUAGE\_URDU\_PAKISTAN
 297 \item wxLANGUAGE\_UZBEK
 298 \item wxLANGUAGE\_UZBEK\_CYRILLIC
 299 \item wxLANGUAGE\_UZBEK\_LATIN
 300 \item wxLANGUAGE\_VIETNAMESE
 301 \item wxLANGUAGE\_VOLAPUK
 302 \item wxLANGUAGE\_WELSH
 303 \item wxLANGUAGE\_WOLOF
 304 \item wxLANGUAGE\_XHOSA
 305 \item wxLANGUAGE\_YIDDISH
 306 \item wxLANGUAGE\_YORUBA
 307 \item wxLANGUAGE\_ZHUANG
 308 \item wxLANGUAGE\_ZULU
 309 \end{itemize}
 310
 311 %% --- --- --- generated code ends here --- --- ---
 312
 313
 314
 315
 316
 317 \membersection{wxLocale::wxLocale}\label{wxlocaledefctor}
 318
 319 \func{}{wxLocale}{\void}
 320
 321 This is the default constructor and it does nothing to initialize the object:
 322 \helpref{Init()}{wxlocaleinit} must be used to do that.
 323
 324 \func{}{wxLocale}{\param{int }{language}, \param{int }{flags =
 325                           wxLOCALE\_LOAD\_DEFAULT | wxLOCALE\_CONV\_ENCODING}}
 326
 327 See \helpref{Init()}{wxlocaleinit} for parameters description.
 328
 329 \func{}{wxLocale}{\param{const char }{*szName}, \param{const char }{*szShort = NULL}, \param{const char }{*szLocale = NULL}, \param{bool }{bLoadDefault = true}, \param{bool }{bConvertEncoding = false}}
 330
 331 See \helpref{Init()}{wxlocaleinit} for parameters description.
 332
 333 The call of this function has several global side effects which you should
 334 understand: first of all, the application locale is changed - note that this
 335 will affect many of standard C library functions such as printf() or strftime().
 336 Second, this wxLocale object becomes the new current global locale for the
 337 application and so all subsequent calls to wxGetTranslation() will try to
 338 translate the messages using the message catalogs for this locale.
 339
 340
 341
 342 \membersection{wxLocale::\destruct{wxLocale}}\label{wxlocaledtor}
 343
 344 \func{}{\destruct{wxLocale}}{\void}
 345
 346 The destructor, like the constructor, also has global side effects: the previously
 347 set locale is restored and so the changes described in
 348 \helpref{Init}{wxlocaleinit} documentation are rolled back.
 349
 350
 351 \membersection{wxLocale::AddCatalog}\label{wxlocaleaddcatalog}
 352
 353 \func{bool}{AddCatalog}{\param{const char }{*szDomain}}
 354
 355 \func{bool}{AddCatalog}{\param{const char }{*szDomain}, \param{wxLanguage}{msgIdLanguage}, \param{const char }{*msgIdCharset}}
 356
 357 Add a catalog for use with the current locale: it is searched for in standard
 358 places (current directory first, then the system one), but you may also prepend
 359 additional directories to the search path with
 360 \helpref{AddCatalogLookupPathPrefix()}{wxlocaleaddcataloglookuppathprefix}.
 361
 362 All loaded catalogs will be used for message lookup by
 363 \helpref{GetString()}{wxlocalegetstring} for the current locale.
 364
 365 Returns true if catalog was successfully loaded, false otherwise (which might
 366 mean that the catalog is not found or that it isn't in the correct format).
 367
 368 The second form of this method takes two additional arguments,
 369 \arg{msgIdLanguage} and \arg{msgIdCharset}.
 370
 371 \arg{msgIdLanguage} specifies the language of "msgid" strings in source code
 372 (i.e. arguments to \helpref{GetString}{wxlocalegetstring},
 373 \helpref{wxGetTranslation}{wxgettranslation} and the
 374 \helpref{\_()}{underscore} macro). It is used if AddCatalog cannot find any
 375 catalog for current language: if the language is same as source code language,
 376 then strings from source code are used instead.
 377
 378 \arg{msgIdCharset} lets you specify the charset used for msgids in sources
 379 in case they use 8-bit characters (e.g. German or French strings).  This
 380 argument has no effect in Unicode build, because literals in sources are
 381 Unicode strings; you have to use compiler-specific method of setting the right
 382 charset when compiling with Unicode.
 383
 384 By default (i.e. when you use the first form), msgid strings are assumed
 385 to be in English and written only using 7-bit ASCII characters.
 386
 387 If you have to deal with non-English strings or 8-bit characters in the source
 388 code, see the instructions in
 389 \helpref{Writing non-English applications}{nonenglishoverview}.
 390
 391
 392 \membersection{wxLocale::AddCatalogLookupPathPrefix}\label{wxlocaleaddcataloglookuppathprefix}
 393
 394 \func{void}{AddCatalogLookupPathPrefix}{\param{const wxString\& }{prefix}}
 395
 396 Add a prefix to the catalog lookup path: the message catalog files will be
 397 looked up under prefix/<lang>/LC\_MESSAGES, prefix/LC\_MESSAGES and prefix
 398 (in this order).
 399
 400 This only applies to subsequent invocations of AddCatalog()!
 401
 402
 403 \membersection{wxLocale::AddLanguage}\label{wxlocaleaddlanguage}
 404
 405 \func{static void}{AddLanguage}{\param{const wxLanguageInfo\& }{info}}
 406
 407 Adds custom, user-defined language to the database of known languages. This
 408 database is used in conjunction with the first form of
 409 \helpref{Init}{wxlocaleinit}.
 410
 411 wxLanguageInfo is defined as follows:
 412
 413 \begin{verbatim}
 414 struct WXDLLEXPORT wxLanguageInfo
 415 {
 416     int Language;                   // wxLanguage id
 417     wxString CanonicalName;         // Canonical name, e.g. fr_FR
 418 #ifdef __WIN32__
 419     wxUint32 WinLang, WinSublang;   // Win32 language identifiers
 420                                     // (LANG_xxxx, SUBLANG_xxxx)
 421 #endif
 422     wxString Description;           // human-readable name of the language
 423 };
 424 \end{verbatim}
 425
 426
 427 {\it Language} should be greater than wxLANGUAGE\_USER\_DEFINED.
 428
 429 \perlnote{In wxPerl Wx::LanguageInfo has only one method:\par
 430 Wx::LanguageInfo->new( language, canonicalName, WinLang, WinSubLang, Description )}
 431
 432
 433 \membersection{wxLocale::FindLanguageInfo}{wxlocalefindlanguageinfo}
 434
 435 \constfunc{static wxLanguageInfo *}{FindLanguageInfo}{\param{const wxString\& }{locale}}
 436
 437 This function may be used to find the language description structure for the
 438 given locale, specified either as a two letter ISO language code (for example,
 439 "pt"), a language code followed by the country code ("pt\_BR") or a full, human
 440 readable, language description ("Portuguese-Brazil").
 441
 442 Returns the information for the given language or {\tt NULL} if this language
 443 is unknown. Note that even if the returned pointer is valid, the caller should
 444 {\it not} delete it.
 445
 446 \wxheading{See also}
 447
 448 \helpref{GetLanguageInfo}{wxlocalegetlanguageinfo}
 449
 450
 451 \membersection{wxLocale::GetCanonicalName}\label{wxlocalegetcanonicalname}
 452
 453 \constfunc{wxString}{GetSysName}{\void}
 454
 455 Returns the canonical form of current locale name. Canonical form is the
 456 one that is used on UNIX systems: it is a two- or five-letter string in xx or
 457 xx\_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of
 458 the country. Examples are "en", "en\_GB", "en\_US" or "fr\_FR".
 459
 460 This form is internally used when looking up message catalogs.
 461
 462 Compare \helpref{GetSysName}{wxlocalegetsysname}.
 463
 464
 465
 466
 467 \membersection{wxLocale::GetLanguage}\label{wxlocalegetlanguage}
 468
 469 \constfunc{int}{GetLanguage}{\void}
 470
 471 Returns \helpref{wxLanguage}{wxlanguage} constant of current language.
 472 Note that you can call this function only if you used the form of
 473 \helpref{Init}{wxlocaleinit} that takes wxLanguage argument.
 474
 475
 476 \membersection{wxLocale::GetLanguageInfo}\label{wxlocalegetlanguageinfo}
 477
 478 \constfunc{static wxLanguageInfo *}{GetLanguageInfo}{\param{int }{lang}}
 479
 480 Returns a pointer to wxLanguageInfo structure containing information about the
 481 given language or {\tt NULL} if this language is unknown. Note that even if the
 482 returned pointer is valid, the caller should {\it not} delete it.
 483
 484 See \helpref{AddLanguage}{wxlocaleaddlanguage} for the wxLanguageInfo
 485 description.
 486
 487 As with \helpref{Init}{wxlocaleinit}, \texttt{wxLANGUAGE\_DEFAULT} has the
 488 special meaning if passed as an argument to this function and in this case the
 489 result of \helpref{GetSystemLanguage()}{wxlocalegetsystemlanguage} is used.
 490
 491
 492 \membersection{wxLocale::GetLanguageName}\label{wxlocalegetlanguagename}
 493
 494 \constfunc{static wxString}{GetLanguageName}{\param{int }{lang}}
 495
 496 Returns English name of the given language or empty string if this
 497 language is unknown.
 498
 499 See \helpref{GetLanguageInfo}{wxlocalegetlanguageinfo} for a remark about
 500 special meaning of \texttt{wxLANGUAGE\_DEFAULT}.
 501
 502
 503 \membersection{wxLocale::GetLocale}\label{wxlocalegetlocale}
 504
 505 \constfunc{const char*}{GetLocale}{\void}
 506
 507 Returns the locale name as passed to the constructor or
 508 \helpref{Init()}{wxlocaleinit}. This is full, human-readable name,
 509 e.g. "English" or "French".
 510
 511
 512
 513 \membersection{wxLocale::GetName}\label{wxlocalegetname}
 514
 515 \constfunc{const wxString\&}{GetName}{\void}
 516
 517 Returns the current short name for the locale (as given to the constructor or
 518 the Init() function).
 519
 520
 521 \membersection{wxLocale::GetString}\label{wxlocalegetstring}
 522
 523 \constfunc{const char*}{GetString}{\param{const char }{*szOrigString}, \param{const char }{*szDomain = NULL}}
 524
 525 \constfunc{const char*}{GetString}{\param{const char }{*szOrigString}, \param{const char }{*szOrigString2}, \param{size\_t }{n}, \param{const char }{*szDomain = NULL}}
 526
 527 Retrieves the translation for a string in all loaded domains unless the szDomain
 528 parameter is specified (and then only this catalog/domain is searched).
 529
 530 Returns original string if translation is not available
 531 (in this case an error message is generated the first time
 532 a string is not found; use \helpref{wxLogNull}{wxlogoverview} to suppress it).
 533
 534 The second form is used when retrieving translation of string that has
 535 different singular and plural form in English or different plural forms in some
 536 other language. It takes two extra arguments: \arg{szOrigString}
 537 parameter must contain the singular form of the string to be converted.
 538 It is also used as the key for the search in the catalog.
 539 The \arg{szOrigString2} parameter is the plural form (in English).
 540 The parameter \arg{n} is used to determine the plural form.  If no
 541 message catalog is found \arg{szOrigString} is returned if `n == 1',
 542 otherwise \arg{szOrigString2}.
 543 See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} for additional information on plural forms handling.
 544
 545 This method is called by the \helpref{wxGetTranslation}{wxgettranslation}
 546 function and \helpref{\_()}{underscore} macro.
 547
 548 \wxheading{Remarks}
 549
 550 Domains are searched in the last to first order, i.e. catalogs
 551 added later override those added before.
 552
 553
 554 \membersection{wxLocale::GetHeaderValue}\label{wxlocalegetheadervalue}
 555
 556 \constfunc{wxString}{GetHeaderValue}{\param{const char }{*szHeader}, \param{const char }{*szDomain = NULL}}
 557
 558 Returns the header value for header \arg{szHeader}. The search for \arg{szHeader} is case sensitive. If an \arg{szDomain}
 559 is passed, this domain is searched. Else all domains will be searched until a header has been found.
 560 The return value is the value of the header if found. Else this will be empty.
 561
 562 \membersection{wxLocale::GetSysName}\label{wxlocalegetsysname}
 563
 564 \constfunc{wxString}{GetSysName}{\void}
 565
 566 Returns current platform-specific locale name as passed to setlocale().
 567
 568 Compare \helpref{GetCanonicalName}{wxlocalegetcanonicalname}.
 569
 570
 571
 572 \membersection{wxLocale::GetSystemEncoding}\label{wxlocalegetsystemencoding}
 573
 574 \constfunc{static wxFontEncoding}{GetSystemEncoding}{\void}
 575
 576 Tries to detect the user's default font encoding.
 577 Returns \helpref{wxFontEncoding}{wxfont} value or
 578 {\bf wxFONTENCODING\_SYSTEM} if it couldn't be determined.
 579
 580
 581 \membersection{wxLocale::GetSystemEncodingName}\label{wxlocalegetsystemencodingname}
 582
 583 \constfunc{static wxString}{GetSystemEncodingName}{\void}
 584
 585 Tries to detect the name of the user's default font encoding. This string isn't
 586 particularly useful for the application as its form is platform-dependent and
 587 so you should probably use
 588 \helpref{GetSystemEncoding}{wxlocalegetsystemencoding} instead.
 589
 590 Returns a user-readable string value or an empty string if it couldn't be
 591 determined.
 592
 593
 594 \membersection{wxLocale::GetSystemLanguage}\label{wxlocalegetsystemlanguage}
 595
 596 \constfunc{static int}{GetSystemLanguage}{\void}
 597
 598 Tries to detect the user's default language setting.
 599 Returns \helpref{wxLanguage}{wxlanguage} value or
 600  {\bf wxLANGUAGE\_UNKNOWN} if the language-guessing algorithm failed.
 601
 602
 603
 604 \membersection{wxLocale::Init}\label{wxlocaleinit}
 605
 606
 607 \func{bool}{Init}{\param{int }{language = wxLANGUAGE\_DEFAULT}, \param{int }{flags =
 608                           wxLOCALE\_LOAD\_DEFAULT | wxLOCALE\_CONV\_ENCODING}}
 609
 610 \func{bool}{Init}{\param{const char }{*szName}, \param{const char }{*szShort = NULL}, \param{const char }{*szLocale = NULL}, \param{bool }{bLoadDefault = true}, \param{bool }{bConvertEncoding = false}}
 611
 612 The second form is deprecated, use the first one unless you know what you are
 613 doing.
 614
 615
 616 \wxheading{Parameters}
 617
 618 \docparam{language}{\helpref{wxLanguage}{wxlanguage} identifier of the locale.
 619 wxLANGUAGE\_DEFAULT has special meaning -- wxLocale will use system's default
 620 language (see \helpref{GetSystemLanguage}{wxlocalegetsystemlanguage}).}
 621
 622 \docparam{flags}{Combination of the following:
 623
 624
 625 \begin{twocollist}\itemsep=0pt
 626 \twocolitem{\windowstyle{wxLOCALE\_LOAD\_DEFAULT}}{Load the message catalog
 627 for the given locale containing the translations of standard wxWidgets messages
 628 automatically.}
 629 \twocolitem{\windowstyle{wxLOCALE\_CONV\_ENCODING}}{Automatically convert message
 630 catalogs to platform's default encoding. Note that it will do only basic
 631 conversion between well-known pair like iso8859-1 and windows-1252 or
 632 iso8859-2 and windows-1250. See \helpref{Writing non-English applications}{nonenglishoverview} for detailed
 633 description of this behaviour. Note that this flag is meaningless in Unicode build.}
 634 \end{twocollist}
 635 }
 636
 637 \docparam{szName}{The name of the locale. Only used in diagnostic messages.}
 638
 639 \docparam{szShort}{The standard 2 letter locale abbreviation and is used as the
 640 directory prefix when looking for the message catalog files.}
 641
 642 \docparam{szLocale}{The parameter for the call to setlocale(). Note that it is
 643 platform-specific.}
 644
 645 \docparam{bLoadDefault}{May be set to false to prevent loading of the message catalog
 646 for the given locale containing the translations of standard wxWidgets messages.
 647 This parameter would be rarely used in normal circumstances.}
 648
 649 \docparam{bConvertEncoding}{May be set to true to do automatic conversion of message
 650 catalogs to platform's native encoding. Note that it will do only basic
 651 conversion between well-known pair like iso8859-1 and windows-1252 or
 652 iso8859-2 and windows-1250.
 653 See \helpref{Writing non-English applications}{nonenglishoverview} for detailed
 654 description of this behaviour.}
 655
 656
 657 The call of this function has several global side effects which you should
 658 understand: first of all, the application locale is changed - note that this
 659 will affect many of standard C library functions such as printf() or strftime().
 660 Second, this wxLocale object becomes the new current global locale for the
 661 application and so all subsequent calls to
 662 \helpref{wxGetTranslation()}{wxgettranslation} will try to
 663 translate the messages using the message catalogs for this locale.
 664
 665 Returns true on success or false if the given locale couldn't be set.
 666
 667
 668 \membersection{wxLocale::IsLoaded}\label{wxlocaleisloaded}
 669
 670 \constfunc{bool}{IsLoaded}{\param{const char* }{domain}}
 671
 672 Check if the given catalog is loaded, and returns true if it is.
 673
 674 According to GNU gettext tradition, each catalog
 675 normally corresponds to 'domain' which is more or less the application name.
 676
 677 See also: \helpref{AddCatalog}{wxlocaleaddcatalog}
 678
 679
 680 \membersection{wxLocale::IsOk}\label{wxlocaleisok}
 681
 682 \constfunc{bool}{IsOk}{\void}
 683
 684 Returns true if the locale could be set successfully.
 685