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