interface/wx/intl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        intl.h
   3 // Purpose:     interface of wxLocale
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 // --- --- --- generated code begins here --- --- ---
  11
  12 /**
  13     The languages supported by wxLocale.
  14
  15     This enum is generated by misc/languages/genlang.py
  16     When making changes, please put them into misc/languages/langtabl.txt
  17 */
  18 enum wxLanguage
  19 {
  20     /// User's default/preffered language as got from OS.
  21     wxLANGUAGE_DEFAULT,
  22
  23     /// Unknown language, returned if wxLocale::GetSystemLanguage fails.
  24     wxLANGUAGE_UNKNOWN,
  25
  26     wxLANGUAGE_ABKHAZIAN,
  27     wxLANGUAGE_AFAR,
  28     wxLANGUAGE_AFRIKAANS,
  29     wxLANGUAGE_ALBANIAN,
  30     wxLANGUAGE_AMHARIC,
  31     wxLANGUAGE_ARABIC,
  32     wxLANGUAGE_ARABIC_ALGERIA,
  33     wxLANGUAGE_ARABIC_BAHRAIN,
  34     wxLANGUAGE_ARABIC_EGYPT,
  35     wxLANGUAGE_ARABIC_IRAQ,
  36     wxLANGUAGE_ARABIC_JORDAN,
  37     wxLANGUAGE_ARABIC_KUWAIT,
  38     wxLANGUAGE_ARABIC_LEBANON,
  39     wxLANGUAGE_ARABIC_LIBYA,
  40     wxLANGUAGE_ARABIC_MOROCCO,
  41     wxLANGUAGE_ARABIC_OMAN,
  42     wxLANGUAGE_ARABIC_QATAR,
  43     wxLANGUAGE_ARABIC_SAUDI_ARABIA,
  44     wxLANGUAGE_ARABIC_SUDAN,
  45     wxLANGUAGE_ARABIC_SYRIA,
  46     wxLANGUAGE_ARABIC_TUNISIA,
  47     wxLANGUAGE_ARABIC_UAE,
  48     wxLANGUAGE_ARABIC_YEMEN,
  49     wxLANGUAGE_ARMENIAN,
  50     wxLANGUAGE_ASSAMESE,
  51     wxLANGUAGE_ASTURIAN,
  52     wxLANGUAGE_AYMARA,
  53     wxLANGUAGE_AZERI,
  54     wxLANGUAGE_AZERI_CYRILLIC,
  55     wxLANGUAGE_AZERI_LATIN,
  56     wxLANGUAGE_BASHKIR,
  57     wxLANGUAGE_BASQUE,
  58     wxLANGUAGE_BELARUSIAN,
  59     wxLANGUAGE_BENGALI,
  60     wxLANGUAGE_BHUTANI,
  61     wxLANGUAGE_BIHARI,
  62     wxLANGUAGE_BISLAMA,
  63     wxLANGUAGE_BRETON,
  64     wxLANGUAGE_BULGARIAN,
  65     wxLANGUAGE_BURMESE,
  66     wxLANGUAGE_CAMBODIAN,
  67     wxLANGUAGE_CATALAN,
  68     wxLANGUAGE_CHINESE,
  69     wxLANGUAGE_CHINESE_SIMPLIFIED,
  70     wxLANGUAGE_CHINESE_TRADITIONAL,
  71     wxLANGUAGE_CHINESE_HONGKONG,
  72     wxLANGUAGE_CHINESE_MACAU,
  73     wxLANGUAGE_CHINESE_SINGAPORE,
  74     wxLANGUAGE_CHINESE_TAIWAN,
  75     wxLANGUAGE_CORSICAN,
  76     wxLANGUAGE_CROATIAN,
  77     wxLANGUAGE_CZECH,
  78     wxLANGUAGE_DANISH,
  79     wxLANGUAGE_DUTCH,
  80     wxLANGUAGE_DUTCH_BELGIAN,
  81     wxLANGUAGE_ENGLISH,
  82     wxLANGUAGE_ENGLISH_UK,
  83     wxLANGUAGE_ENGLISH_US,
  84     wxLANGUAGE_ENGLISH_AUSTRALIA,
  85     wxLANGUAGE_ENGLISH_BELIZE,
  86     wxLANGUAGE_ENGLISH_BOTSWANA,
  87     wxLANGUAGE_ENGLISH_CANADA,
  88     wxLANGUAGE_ENGLISH_CARIBBEAN,
  89     wxLANGUAGE_ENGLISH_DENMARK,
  90     wxLANGUAGE_ENGLISH_EIRE,
  91     wxLANGUAGE_ENGLISH_JAMAICA,
  92     wxLANGUAGE_ENGLISH_NEW_ZEALAND,
  93     wxLANGUAGE_ENGLISH_PHILIPPINES,
  94     wxLANGUAGE_ENGLISH_SOUTH_AFRICA,
  95     wxLANGUAGE_ENGLISH_TRINIDAD,
  96     wxLANGUAGE_ENGLISH_ZIMBABWE,
  97     wxLANGUAGE_ESPERANTO,
  98     wxLANGUAGE_ESTONIAN,
  99     wxLANGUAGE_FAEROESE,
 100     wxLANGUAGE_FARSI,
 101     wxLANGUAGE_FIJI,
 102     wxLANGUAGE_FINNISH,
 103     wxLANGUAGE_FRENCH,
 104     wxLANGUAGE_FRENCH_BELGIAN,
 105     wxLANGUAGE_FRENCH_CANADIAN,
 106     wxLANGUAGE_FRENCH_LUXEMBOURG,
 107     wxLANGUAGE_FRENCH_MONACO,
 108     wxLANGUAGE_FRENCH_SWISS,
 109     wxLANGUAGE_FRISIAN,
 110     wxLANGUAGE_GALICIAN,
 111     wxLANGUAGE_GEORGIAN,
 112     wxLANGUAGE_GERMAN,
 113     wxLANGUAGE_GERMAN_AUSTRIAN,
 114     wxLANGUAGE_GERMAN_BELGIUM,
 115     wxLANGUAGE_GERMAN_LIECHTENSTEIN,
 116     wxLANGUAGE_GERMAN_LUXEMBOURG,
 117     wxLANGUAGE_GERMAN_SWISS,
 118     wxLANGUAGE_GREEK,
 119     wxLANGUAGE_GREENLANDIC,
 120     wxLANGUAGE_GUARANI,
 121     wxLANGUAGE_GUJARATI,
 122     wxLANGUAGE_HAUSA,
 123     wxLANGUAGE_HEBREW,
 124     wxLANGUAGE_HINDI,
 125     wxLANGUAGE_HUNGARIAN,
 126     wxLANGUAGE_ICELANDIC,
 127     wxLANGUAGE_INDONESIAN,
 128     wxLANGUAGE_INTERLINGUA,
 129     wxLANGUAGE_INTERLINGUE,
 130     wxLANGUAGE_INUKTITUT,
 131     wxLANGUAGE_INUPIAK,
 132     wxLANGUAGE_IRISH,
 133     wxLANGUAGE_ITALIAN,
 134     wxLANGUAGE_ITALIAN_SWISS,
 135     wxLANGUAGE_JAPANESE,
 136     wxLANGUAGE_JAVANESE,
 137     wxLANGUAGE_KANNADA,
 138     wxLANGUAGE_KASHMIRI,
 139     wxLANGUAGE_KASHMIRI_INDIA,
 140     wxLANGUAGE_KAZAKH,
 141     wxLANGUAGE_KERNEWEK,
 142     wxLANGUAGE_KINYARWANDA,
 143     wxLANGUAGE_KIRGHIZ,
 144     wxLANGUAGE_KIRUNDI,
 145     wxLANGUAGE_KONKANI,
 146     wxLANGUAGE_KOREAN,
 147     wxLANGUAGE_KURDISH,
 148     wxLANGUAGE_LAOTHIAN,
 149     wxLANGUAGE_LATIN,
 150     wxLANGUAGE_LATVIAN,
 151     wxLANGUAGE_LINGALA,
 152     wxLANGUAGE_LITHUANIAN,
 153     wxLANGUAGE_MACEDONIAN,
 154     wxLANGUAGE_MALAGASY,
 155     wxLANGUAGE_MALAY,
 156     wxLANGUAGE_MALAYALAM,
 157     wxLANGUAGE_MALAY_BRUNEI_DARUSSALAM,
 158     wxLANGUAGE_MALAY_MALAYSIA,
 159     wxLANGUAGE_MALTESE,
 160     wxLANGUAGE_MANIPURI,
 161     wxLANGUAGE_MAORI,
 162     wxLANGUAGE_MARATHI,
 163     wxLANGUAGE_MOLDAVIAN,
 164     wxLANGUAGE_MONGOLIAN,
 165     wxLANGUAGE_NAURU,
 166     wxLANGUAGE_NEPALI,
 167     wxLANGUAGE_NEPALI_INDIA,
 168     wxLANGUAGE_NORWEGIAN_BOKMAL,
 169     wxLANGUAGE_NORWEGIAN_NYNORSK,
 170     wxLANGUAGE_OCCITAN,
 171     wxLANGUAGE_ORIYA,
 172     wxLANGUAGE_OROMO,
 173     wxLANGUAGE_PASHTO,
 174     wxLANGUAGE_POLISH,
 175     wxLANGUAGE_PORTUGUESE,
 176     wxLANGUAGE_PORTUGUESE_BRAZILIAN,
 177     wxLANGUAGE_PUNJABI,
 178     wxLANGUAGE_QUECHUA,
 179     wxLANGUAGE_RHAETO_ROMANCE,
 180     wxLANGUAGE_ROMANIAN,
 181     wxLANGUAGE_RUSSIAN,
 182     wxLANGUAGE_RUSSIAN_UKRAINE,
 183     wxLANGUAGE_SAMI,
 184     wxLANGUAGE_SAMOAN,
 185     wxLANGUAGE_SANGHO,
 186     wxLANGUAGE_SANSKRIT,
 187     wxLANGUAGE_SCOTS_GAELIC,
 188     wxLANGUAGE_SERBIAN,
 189     wxLANGUAGE_SERBIAN_CYRILLIC,
 190     wxLANGUAGE_SERBIAN_LATIN,
 191     wxLANGUAGE_SERBO_CROATIAN,
 192     wxLANGUAGE_SESOTHO,
 193     wxLANGUAGE_SETSWANA,
 194     wxLANGUAGE_SHONA,
 195     wxLANGUAGE_SINDHI,
 196     wxLANGUAGE_SINHALESE,
 197     wxLANGUAGE_SISWATI,
 198     wxLANGUAGE_SLOVAK,
 199     wxLANGUAGE_SLOVENIAN,
 200     wxLANGUAGE_SOMALI,
 201     wxLANGUAGE_SPANISH,
 202     wxLANGUAGE_SPANISH_ARGENTINA,
 203     wxLANGUAGE_SPANISH_BOLIVIA,
 204     wxLANGUAGE_SPANISH_CHILE,
 205     wxLANGUAGE_SPANISH_COLOMBIA,
 206     wxLANGUAGE_SPANISH_COSTA_RICA,
 207     wxLANGUAGE_SPANISH_DOMINICAN_REPUBLIC,
 208     wxLANGUAGE_SPANISH_ECUADOR,
 209     wxLANGUAGE_SPANISH_EL_SALVADOR,
 210     wxLANGUAGE_SPANISH_GUATEMALA,
 211     wxLANGUAGE_SPANISH_HONDURAS,
 212     wxLANGUAGE_SPANISH_MEXICAN,
 213     wxLANGUAGE_SPANISH_MODERN,
 214     wxLANGUAGE_SPANISH_NICARAGUA,
 215     wxLANGUAGE_SPANISH_PANAMA,
 216     wxLANGUAGE_SPANISH_PARAGUAY,
 217     wxLANGUAGE_SPANISH_PERU,
 218     wxLANGUAGE_SPANISH_PUERTO_RICO,
 219     wxLANGUAGE_SPANISH_URUGUAY,
 220     wxLANGUAGE_SPANISH_US,
 221     wxLANGUAGE_SPANISH_VENEZUELA,
 222     wxLANGUAGE_SUNDANESE,
 223     wxLANGUAGE_SWAHILI,
 224     wxLANGUAGE_SWEDISH,
 225     wxLANGUAGE_SWEDISH_FINLAND,
 226     wxLANGUAGE_TAGALOG,
 227     wxLANGUAGE_TAJIK,
 228     wxLANGUAGE_TAMIL,
 229     wxLANGUAGE_TATAR,
 230     wxLANGUAGE_TELUGU,
 231     wxLANGUAGE_THAI,
 232     wxLANGUAGE_TIBETAN,
 233     wxLANGUAGE_TIGRINYA,
 234     wxLANGUAGE_TONGA,
 235     wxLANGUAGE_TSONGA,
 236     wxLANGUAGE_TURKISH,
 237     wxLANGUAGE_TURKMEN,
 238     wxLANGUAGE_TWI,
 239     wxLANGUAGE_UIGHUR,
 240     wxLANGUAGE_UKRAINIAN,
 241     wxLANGUAGE_URDU,
 242     wxLANGUAGE_URDU_INDIA,
 243     wxLANGUAGE_URDU_PAKISTAN,
 244     wxLANGUAGE_UZBEK,
 245     wxLANGUAGE_UZBEK_CYRILLIC,
 246     wxLANGUAGE_UZBEK_LATIN,
 247     wxLANGUAGE_VALENCIAN,
 248     wxLANGUAGE_VIETNAMESE,
 249     wxLANGUAGE_VOLAPUK,
 250     wxLANGUAGE_WELSH,
 251     wxLANGUAGE_WOLOF,
 252     wxLANGUAGE_XHOSA,
 253     wxLANGUAGE_YIDDISH,
 254     wxLANGUAGE_YORUBA,
 255     wxLANGUAGE_ZHUANG,
 256     wxLANGUAGE_ZULU,
 257
 258     /// For custom, user-defined languages.
 259     wxLANGUAGE_USER_DEFINED
 260 };
 261
 262 // --- --- --- generated code ends here --- --- ---
 263
 264
 265
 266 /**
 267     This is the layout direction stored in wxLanguageInfo and returned by
 268     wxApp::GetLayoutDirection(), wxWindow::GetLayoutDirection(),
 269     wxDC::GetLayoutDirection() for RTL (right-to-left) languages support.
 270 */
 271 enum wxLayoutDirection
 272 {
 273     wxLayout_Default,
 274     wxLayout_LeftToRight,
 275     wxLayout_RightToLeft
 276 };
 277
 278 /**
 279     Encapsulates a ::wxLanguage indentifier together with OS-specific information
 280     related to that language.
 281
 282     @beginWxPerlOnly
 283     In wxPerl @c Wx::LanguageInfo has only one method:
 284     - Wx::LanguageInfo->new(language, canonicalName, WinLang, WinSubLang, Description)
 285     @endWxPerlOnly
 286 */
 287 struct WXDLLIMPEXP_BASE wxLanguageInfo
 288 {
 289     /// ::wxLanguage id.
 290     /// It should be greater than @c wxLANGUAGE_USER_DEFINED when defining your own
 291     /// language info structure.
 292     int Language;
 293
 294     /// Canonical name of the language, e.g. @c fr_FR.
 295     wxString CanonicalName;
 296
 297     //@{
 298     /**
 299         Win32 language identifiers (LANG_xxxx, SUBLANG_xxxx).
 300
 301         @onlyfor{wxmsw}
 302     */
 303     wxUint32 WinLang, WinSublang;
 304     //@}
 305
 306     /// Human-readable name of the language.
 307     wxString Description;
 308
 309     /// The layout direction used for this language.
 310     wxLayoutDirection LayoutDirection;
 311
 312     /// Return the LCID corresponding to this language.
 313     /// @onlyfor{wxmsw}
 314     wxUint32 GetLCID() const;
 315
 316     /// Return the locale name corresponding to this language usable with
 317     /// @c setlocale() on the current system.
 318     wxString GetLocaleName() const;
 319 };
 320
 321
 322 /**
 323     The category of locale settings.
 324
 325     @see wxLocale::GetInfo()
 326 */
 327 enum wxLocaleCategory
 328 {
 329     /// Number formatting.
 330     wxLOCALE_CAT_NUMBER,
 331
 332     /// Date/time formatting.
 333     wxLOCALE_CAT_DATE,
 334
 335     /// Monetary values formatting.
 336     wxLOCALE_CAT_MONEY,
 337
 338     /**
 339         Default category for the wxLocaleInfo value.
 340
 341         This category can be used for values which only make sense for a single
 342         category, e.g. wxLOCALE_SHORT_DATE_FMT which can only be used with
 343         wxLOCALE_CAT_DATE. As this is the default value of the second parameter
 344         of wxLocale::GetInfo(), wxLOCALE_CAT_DATE can be omitted when asking
 345         for wxLOCALE_SHORT_DATE_FMT value.
 346
 347         @since 2.9.0
 348      */
 349     wxLOCALE_CAT_DEFAULT
 350 };
 351
 352 /**
 353     The values understood by wxLocale::GetInfo().
 354
 355     Note that for the @c wxLOCALE_*_FMT constants (the date and time formats),
 356     the strings returned by wxLocale::GetInfo() use strftime() or,
 357     equivalently, wxDateTime::Format() format. If the relevant format
 358     couldn't be determined, an empty string is returned -- there is no
 359     fallback value so that the application could determine the best course
 360     of actions itself in such case.
 361
 362     All of these values are used with @c wxLOCALE_CAT_DATE in wxLocale::GetInfo() or,
 363     more typically, with @c wxLOCALE_CAT_DEFAULT as they only apply to a single category.
 364 */
 365 enum wxLocaleInfo
 366 {
 367     /**
 368         The thousands separator.
 369
 370         This value can be used with either wxLOCALE_CAT_NUMBER or
 371         wxLOCALE_CAT_MONEY categories.
 372      */
 373     wxLOCALE_THOUSANDS_SEP,
 374
 375     /**
 376         The character used as decimal point.
 377
 378         This value can be used with either wxLOCALE_CAT_NUMBER or
 379         wxLOCALE_CAT_MONEY categories.
 380      */
 381     wxLOCALE_DECIMAL_POINT,
 382
 383     /**
 384         Short date format.
 385
 386         Notice that short and long date formats may be the same under POSIX
 387         systems currently but may, and typically are, different under MSW or OS X.
 388
 389         @since 2.9.0
 390      */
 391     wxLOCALE_SHORT_DATE_FMT,
 392
 393     /**
 394         Long date format.
 395
 396         @since 2.9.0
 397      */
 398     wxLOCALE_LONG_DATE_FMT,
 399
 400     /**
 401         Date and time format.
 402
 403         @since 2.9.0
 404      */
 405     wxLOCALE_DATE_TIME_FMT,
 406
 407     /**
 408         Time format.
 409
 410         @since 2.9.0
 411      */
 412     wxLOCALE_TIME_FMT
 413 };
 414
 415
 416 /**
 417     @class wxLocale
 418
 419     wxLocale class encapsulates all language-dependent settings and is a
 420     generalization of the C locale concept.
 421
 422     In wxWidgets this class manages current locale. It also initializes and
 423     activates wxTranslations object that manages message catalogs.
 424
 425     For a list of the supported languages, please see ::wxLanguage enum values.
 426     These constants may be used to specify the language in wxLocale::Init and
 427     are returned by wxLocale::GetSystemLanguage.
 428
 429     @beginWxPerlOnly
 430     In wxPerl you can't use the '_' function name, so
 431     the @c Wx::Locale module can export the @c gettext and
 432     @c gettext_noop under any given name.
 433
 434     @code
 435       # this imports gettext ( equivalent to Wx::GetTranslation
 436       # and gettext_noop ( a noop )
 437       # into your module
 438       use Wx::Locale qw(:default);
 439
 440       # ....
 441
 442       # use the functions
 443       print gettext( "Panic!" );
 444
 445       button = Wx::Button-new( window, -1, gettext( "Label" ) );
 446     @endcode
 447
 448     If you need to translate a lot of strings, then adding gettext( ) around
 449     each one is a long task ( that is why _( ) was introduced ), so just choose
 450     a shorter name for gettext:
 451
 452     @code
 453       use Wx::Locale 'gettext' = 't',
 454                      'gettext_noop' = 'gettext_noop';
 455
 456       # ...
 457
 458       # use the functions
 459       print t( "Panic!!" );
 460
 461       # ...
 462     @endcode
 463     @endWxPerlOnly
 464
 465     @library{wxbase}
 466     @category{cfg}
 467
 468     @see @ref overview_i18n, @ref page_samples_internat, wxXLocale, wxTranslations
 469 */
 470 class wxLocale
 471 {
 472 public:
 473     /**
 474         This is the default constructor and it does nothing to initialize the object:
 475         Init() must be used to do that.
 476     */
 477     wxLocale();
 478
 479     /**
 480         See Init() for parameters description.
 481     */
 482     wxLocale(int language, int flags = wxLOCALE_LOAD_DEFAULT);
 483
 484     /**
 485         See Init() for parameters description.
 486
 487         The call of this function has several global side effects which you should
 488         understand: first of all, the application locale is changed - note that this
 489         will affect many of standard C library functions such as printf() or strftime().
 490         Second, this wxLocale object becomes the new current global locale for the
 491         application and so all subsequent calls to ::wxGetTranslation() will try to
 492         translate the messages using the message catalogs for this locale.
 493     */
 494     wxLocale(const wxString& name,
 495              const wxString& short = wxEmptyString,
 496              const wxString& locale = wxEmptyString,
 497              bool bLoadDefault = true);
 498
 499     /**
 500         The destructor, like the constructor, also has global side effects: the
 501         previously set locale is restored and so the changes described in
 502         Init() documentation are rolled back.
 503     */
 504     virtual ~wxLocale();
 505
 506     /**
 507         Calls wxTranslations::AddCatalog(const wxString&).
 508     */
 509     bool AddCatalog(const wxString& domain);
 510
 511     /**
 512         Calls wxTranslations::AddCatalog(const wxString&, wxLanguage).
 513     */
 514     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
 515
 516     /**
 517         Calls wxTranslations::AddCatalog(const wxString&, wxLanguage, const wxString&).
 518     */
 519     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage,
 520                     const wxString& msgIdCharset);
 521
 522     /**
 523         Calls wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
 524     */
 525     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 526
 527     /**
 528         Adds custom, user-defined language to the database of known languages.
 529         This database is used in conjunction with the first form of Init().
 530     */
 531     static void AddLanguage(const wxLanguageInfo& info);
 532
 533     /**
 534         This function may be used to find the language description structure for the
 535         given locale, specified either as a two letter ISO language code (for example,
 536         "pt"), a language code followed by the country code ("pt_BR") or a full, human
 537         readable, language description ("Portuguese-Brazil").
 538
 539         Returns the information for the given language or @NULL if this language
 540         is unknown. Note that even if the returned pointer is valid, the caller
 541         should @e not delete it.
 542
 543         @see GetLanguageInfo()
 544     */
 545     static const wxLanguageInfo* FindLanguageInfo(const wxString& locale);
 546
 547     /**
 548         Returns the canonical form of current locale name. Canonical form is the
 549         one that is used on UNIX systems: it is a two- or five-letter string in xx or
 550         xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of
 551         the country. Examples are "en", "en_GB", "en_US" or "fr_FR".
 552         This form is internally used when looking up message catalogs.
 553         Compare GetSysName().
 554     */
 555     wxString GetCanonicalName() const;
 556
 557     /**
 558         Calls wxTranslations::GetHeaderValue().
 559     */
 560     wxString GetHeaderValue(const wxString& header,
 561                             const wxString& domain = wxEmptyString) const;
 562
 563     /**
 564         Returns the ::wxLanguage constant of current language.
 565
 566         Note that you can call this function only if you used the form of
 567         Init() that takes ::wxLanguage argument.
 568     */
 569     int GetLanguage() const;
 570
 571     /**
 572         Returns a pointer to wxLanguageInfo structure containing information about
 573         the given language or @NULL if this language is unknown. Note that even if
 574         the returned pointer is valid, the caller should @e not delete it.
 575
 576         See AddLanguage() for the wxLanguageInfo description.
 577         As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed
 578         as an argument to this function and in this case the result of
 579         GetSystemLanguage() is used.
 580     */
 581     static const wxLanguageInfo* GetLanguageInfo(int lang);
 582
 583     /**
 584         Returns English name of the given language or empty string if this
 585         language is unknown.
 586
 587         See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
 588     */
 589     static wxString GetLanguageName(int lang);
 590
 591     /**
 592         Returns canonical name (see GetCanonicalName()) of the given language
 593         or empty string if this language is unknown.
 594
 595         See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
 596
 597         @since 2.9.1
 598     */
 599     static wxString GetLanguageCanonicalName(int lang);
 600
 601     /**
 602         Returns the locale name as passed to the constructor or Init().
 603
 604         This is a full, human-readable name, e.g. "English" or "French".
 605     */
 606     const wxString& GetLocale() const;
 607
 608     /**
 609         Returns the current short name for the locale (as given to the constructor or
 610         the Init() function).
 611     */
 612     const wxString& GetName() const;
 613
 614     /**
 615         Calls wxTranslations::GetString(const wxString&, const wxString&) const.
 616     */
 617     virtual const wxString& GetString(const wxString& origString,
 618                                       const wxString& domain = wxEmptyString) const;
 619
 620     /**
 621         Calls wxTranslations::GetString(const wxString&, const wxString&, size_t, const wxString&) const.
 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         This function returns the value of the locale-specific option specified
 662         by the given @a index.
 663
 664         @param index
 665             One of the elements of wxLocaleInfo enum.
 666         @param cat
 667             The category to use with the given index or wxLOCALE_CAT_DEFAULT if
 668             the index can only apply to a single category.
 669         @return
 670             The option value or empty string if the function failed.
 671     */
 672     static wxString GetInfo(wxLocaleInfo index,
 673                             wxLocaleCategory cat = wxLOCALE_CAT_DEFAULT);
 674
 675     /**
 676         Initializes the wxLocale instance.
 677
 678         The call of this function has several global side effects which you should
 679         understand: first of all, the application locale is changed - note that
 680         this will affect many of standard C library functions such as printf()
 681         or strftime().
 682         Second, this wxLocale object becomes the new current global locale for
 683         the application and so all subsequent calls to wxGetTranslation() will
 684         try to translate the messages using the message catalogs for this locale.
 685
 686         @param language
 687             ::wxLanguage identifier of the locale.
 688             @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's
 689             default language (see GetSystemLanguage()).
 690         @param flags
 691             Combination of the following:
 692             - wxLOCALE_LOAD_DEFAULT: Load the message catalog for the given locale
 693               containing the translations of standard wxWidgets messages
 694               automatically.
 695             - wxLOCALE_DONT_LOAD_DEFAULT: Negation of wxLOCALE_LOAD_DEFAULT.
 696
 697         @return @true on success or @false if the given locale couldn't be set.
 698     */
 699     bool Init(int language = wxLANGUAGE_DEFAULT,
 700               int flags = wxLOCALE_LOAD_DEFAULT);
 701
 702     /**
 703         @deprecated
 704         This form is deprecated, use the other one unless you know what you are doing.
 705
 706         @param name
 707             The name of the locale. Only used in diagnostic messages.
 708         @param short
 709             The standard 2 letter locale abbreviation; it is used as the
 710             directory prefix when looking for the message catalog files.
 711         @param locale
 712             The parameter for the call to setlocale().
 713             Note that it is platform-specific.
 714         @param bLoadDefault
 715             May be set to @false to prevent loading of the message catalog for the
 716             given locale containing the translations of standard wxWidgets messages.
 717             This parameter would be rarely used in normal circumstances.
 718     */
 719     bool Init(const wxString& name, const wxString& short = wxEmptyString,
 720               const wxString& locale = wxEmptyString, bool bLoadDefault = true);
 721
 722     /**
 723         Check whether the operating system and/or C run time environment supports
 724         this locale. For example in Windows 2000 and Windows XP, support for many
 725         locales is not installed by default. Returns @true if the locale is
 726         supported.
 727
 728         The argument @a lang is the ::wxLanguage identifier. To obtain this for a
 729         given a two letter ISO language code, use FindLanguageInfo() to obtain its
 730         wxLanguageInfo structure.
 731         See AddLanguage() for the wxLanguageInfo description.
 732
 733         @since 2.7.1.
 734     */
 735     static bool IsAvailable(int lang);
 736
 737     /**
 738         Calls wxTranslations::IsLoaded().
 739     */
 740     bool IsLoaded(const wxString& domain) const;
 741
 742     /**
 743         Returns @true if the locale could be set successfully.
 744     */
 745     bool IsOk() const;
 746 };
 747
 748
 749 /**
 750     This class allows to get translations for strings.
 751
 752     In wxWidgets this class manages message catalogs which contain the
 753     translations of the strings used to the current language. Unlike wxLocale,
 754     it isn't bound to locale. It can be used either independently of, or in
 755     conjunction with wxLocale. In the latter case, you should initialize
 756     wxLocale (which creates wxTranslations instance) first; in the former, you
 757     need to create a wxTranslations object and Set() it manually.
 758
 759     Only one wxTranslations instance is active at a time; it is set with the
 760     Set() method and obtained using Get().
 761
 762     Unlike wxLocale, wxTranslations' primary mean of identifying language
 763     is by its "canonical name", i.e. ISO 639 code, possibly combined with
 764     ISO 3166 country code and additional modifiers (examples include
 765     "fr", "en_GB" or "ca@valencia"; see wxLocale::GetCanonicalName() for
 766     more information). This allows apps using wxTranslations API to use even
 767     languages not recognized by the operating system or not listed in
 768     wxLanguage enum.
 769
 770     @since 2.9.1
 771
 772     @see wxLocale
 773  */
 774 class wxTranslations
 775 {
 776 public:
 777     /// Constructor
 778     wxTranslations();
 779
 780     /**
 781         Returns current translations object, may return NULL.
 782
 783         You must either call this early in app initialization code, or let
 784         wxLocale do it for you.
 785      */
 786     static wxTranslations *Get();
 787
 788     /**
 789         Sets current translations object.
 790
 791         Deletes previous translation object and takes ownership of @a t.
 792      */
 793     static void Set(wxTranslations *t);
 794
 795     /**
 796         Changes loader use to read catalogs to a non-default one.
 797
 798         Deletes previous loader and takes ownership of @a loader.
 799
 800         @see wxTranslationsLoader, wxFileTranslationsLoader
 801      */
 802     void SetLoader(wxTranslationsLoader *loader);
 803
 804     /**
 805         Sets translations language to use.
 806
 807         wxLANGUAGE_DEFAULT has special meaning: best suitable translation,
 808         given user's preference and available translations, will be used.
 809      */
 810     void SetLanguage(wxLanguage lang);
 811
 812     /**
 813         Sets translations language to use.
 814
 815         Empty @a lang string has the same meaning as wxLANGUAGE_DEFAULT in
 816         SetLanguage(wxLanguage): best suitable translation, given user's
 817         preference and available translations, will be used.
 818      */
 819     void SetLanguage(const wxString& lang);
 820
 821     /**
 822         Add standard wxWidgets catalogs ("wxstd" and possible port-specific
 823         catalogs).
 824
 825         @return @true if a suitable catalog was found, @false otherwise
 826
 827         @see AddCatalog()
 828      */
 829     bool AddStdCatalog();
 830
 831     /**
 832         Add a catalog for use with the current locale.
 833
 834         By default, it is searched for in standard places (see
 835         wxFileTranslationsLoader), but you may also prepend additional
 836         directories to the search path with
 837         wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
 838
 839         All loaded catalogs will be used for message lookup by GetString() for
 840         the current locale.
 841
 842         In this overload, @c msgid strings are assumed
 843         to be in English and written only using 7-bit ASCII characters.
 844         If you have to deal with non-English strings or 8-bit characters in the
 845         source code, see the instructions in @ref overview_nonenglish.
 846
 847         @return
 848             @true if catalog was successfully loaded, @false otherwise (which might
 849             mean that the catalog is not found or that it isn't in the correct format).
 850      */
 851     bool AddCatalog(const wxString& domain);
 852
 853     /**
 854         Same as AddCatalog(const wxString&), but takes an additional argument,
 855         @a msgIdLanguage.
 856
 857         @param domain
 858             The catalog domain to add.
 859
 860         @param msgIdLanguage
 861             Specifies the language of "msgid" strings in source code
 862             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 863             It is used if AddCatalog() cannot find any catalog for current language:
 864             if the language is same as source code language, then strings from source
 865             code are used instead.
 866
 867         @return
 868             @true if catalog was successfully loaded, @false otherwise (which might
 869             mean that the catalog is not found or that it isn't in the correct format).
 870      */
 871     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
 872
 873     /**
 874         Same as AddCatalog(const wxString&, wxLanguage), but takes two
 875         additional arguments, @a msgIdLanguage and @a msgIdCharset.
 876
 877         This overload is only available in non-Unicode build.
 878
 879         @param domain
 880             The catalog domain to add.
 881
 882         @param msgIdLanguage
 883             Specifies the language of "msgid" strings in source code
 884             (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
 885             It is used if AddCatalog() cannot find any catalog for current language:
 886             if the language is same as source code language, then strings from source
 887             code are used instead.
 888
 889         @param msgIdCharset
 890             Lets you specify the charset used for msgids in sources
 891             in case they use 8-bit characters (e.g. German or French strings).
 892
 893         @return
 894             @true if catalog was successfully loaded, @false otherwise (which might
 895             mean that the catalog is not found or that it isn't in the correct format).
 896      */
 897     bool AddCatalog(const wxString& domain,
 898                     wxLanguage msgIdLanguage,
 899                     const wxString& msgIdCharset);
 900
 901     /**
 902         Check if the given catalog is loaded, and returns @true if it is.
 903
 904         According to GNU gettext tradition, each catalog normally corresponds to
 905         'domain' which is more or less the application name.
 906
 907         @see AddCatalog()
 908      */
 909     bool IsLoaded(const wxString& domain) const;
 910
 911     /**
 912         Directly loads catalog from a file.
 913
 914         It is caller's responsibility to ensure that the catalog contains
 915         correct language. This function is primarily intended for
 916         wxTranslationsLoader implementations.
 917
 918         @param filename  Name of the MO file to load.
 919         @param domain    Domain to load the translations into (typically
 920                          matches file's basename).
 921      */
 922     bool LoadCatalogFile(const wxString& filename,
 923                          const wxString& domain = wxEmptyString);
 924
 925     /**
 926         Retrieves the translation for a string in all loaded domains unless the @a domain
 927         parameter is specified (and then only this catalog/domain is searched).
 928
 929         Returns original string if translation is not available (in this case an
 930         error message is generated the first time a string is not found; use
 931         wxLogNull to suppress it).
 932
 933         @remarks Domains are searched in the last to first order, i.e. catalogs
 934                  added later override those added before.
 935     */
 936     const wxString& GetString(const wxString& origString,
 937                               const wxString& domain = wxEmptyString) const;
 938
 939     /**
 940         Retrieves the translation for a string in all loaded domains unless the @a domain
 941         parameter is specified (and then only this catalog/domain is searched).
 942
 943         Returns original string if translation is not available (in this case an
 944         error message is generated the first time a string is not found; use
 945         wxLogNull to suppress it).
 946
 947         This form is used when retrieving translation of string that has different
 948         singular and plural form in English or different plural forms in some
 949         other language.
 950         It takes two extra arguments: @a origString parameter must contain the
 951         singular form of the string to be converted.
 952
 953         It is also used as the key for the search in the catalog.
 954         The @a origString2 parameter is the plural form (in English).
 955
 956         The parameter @a n is used to determine the plural form.
 957         If no message catalog is found @a origString is returned if 'n == 1',
 958         otherwise @a origString2.
 959
 960         See GNU gettext manual for additional information on plural forms handling.
 961         This method is called by the wxGetTranslation() function and _() macro.
 962
 963         @remarks Domains are searched in the last to first order, i.e. catalogs
 964                  added later override those added before.
 965     */
 966     const wxString& GetString(const wxString& origString,
 967                               const wxString& origString2,
 968                               size_t n,
 969                               const wxString& domain = wxEmptyString) const;
 970
 971     /**
 972         Returns the header value for header @a header.
 973         The search for @a header is case sensitive. If an @a domain is passed,
 974         this domain is searched. Else all domains will be searched until a
 975         header has been found.
 976
 977         The return value is the value of the header if found. Else this will be empty.
 978     */
 979     wxString GetHeaderValue(const wxString& header,
 980                             const wxString& domain = wxEmptyString) const;
 981 };
 982
 983
 984 /**
 985     Abstraction of translations discovery and loading.
 986
 987     This interface makes it possible to override wxWidgets' default catalogs
 988     loading mechanism and load MO files from locations other than the
 989     filesystem (e.g. embed them in executable).
 990
 991     Implementations must implement the LoadCatalog() method.
 992
 993     @see wxFileTranslationsLoader
 994  */
 995 class wxTranslationsLoader
 996 {
 997 public:
 998     /// Constructor
 999     wxTranslationsLoader() {}
1000
1001     /**
1002         Called to load requested catalog.
1003
1004         If the catalog is found, LoadCatalog() should call LoadCatalogFile()
1005         on @a translations to add the translation.
1006
1007         @param translations  wxTranslations requesting loading.
1008         @param domain        Domain to load.
1009         @param lang          Language to look for. This is "canonical name"
1010                              (see wxLocale::GetCanonicalName()), i.e. ISO 639
1011                              code, possibly combined with country code or
1012                              additional modifiers (e.g. "fr", "en_GB" or
1013                              "ca@valencia").
1014
1015         @return @true on successful load, @false otherwise
1016      */
1017     virtual bool LoadCatalog(wxTranslations *translations,
1018                              const wxString& domain, const wxString& lang) = 0;
1019 };
1020
1021 /**
1022     Standard wxTranslationsLoader implementation.
1023
1024     This finds catalogs in the filesystem, using the standard Unix layout.
1025     This is the default unless you change the loader with
1026     wxTranslations::SetLoader().
1027
1028     Catalogs are searched for in standard places (current directory first, then
1029     the system one), but you may also prepend additional directories to the
1030     search path with AddCatalogLookupPathPrefix().
1031  */
1032 class wxFileTranslationsLoader : public wxTranslationsLoader
1033 {
1034 public:
1035     /**
1036         Add a prefix to the catalog lookup path: the message catalog files will
1037         be looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix
1038         (in this order).
1039
1040         This only applies to subsequent invocations of
1041         wxTranslations::AddCatalog().
1042     */
1043     static void AddCatalogLookupPathPrefix(const wxString& prefix);
1044 };
1045
1046
1047
1048 // ============================================================================
1049 // Global functions/macros
1050 // ============================================================================
1051
1052 /** @addtogroup group_funcmacro_string */
1053 //@{
1054
1055 /**
1056     This macro is identical to _() but for the plural variant of
1057     wxGetTranslation().
1058
1059     @return A const wxString.
1060
1061     @header{wx/intl.h}
1062 */
1063 #define wxPLURAL(string, plural, n)
1064
1065 /**
1066     This macro doesn't do anything in the program code -- it simply expands to
1067     the value of its argument.
1068
1069     However it does have a purpose which is to mark the literal strings for the
1070     extraction into the message catalog created by @c xgettext program. Usually
1071     this is achieved using _() but that macro not only marks the string for
1072     extraction but also expands into a wxGetTranslation() call which means that
1073     it cannot be used in some situations, notably for static array
1074     initialization.
1075
1076     Here is an example which should make it more clear: suppose that you have a
1077     static array of strings containing the weekday names and which have to be
1078     translated (note that it is a bad example, really, as wxDateTime already
1079     can be used to get the localized week day names already). If you write:
1080
1081     @code
1082     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
1083     ...
1084     // use weekdays[n] as usual
1085     @endcode
1086
1087     The code wouldn't compile because the function calls are forbidden in the
1088     array initializer. So instead you should do this:
1089
1090     @code
1091     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
1092     wxTRANSLATE("Sun") };
1093     ...
1094     // use wxGetTranslation(weekdays[n])
1095     @endcode
1096
1097     Note that although the code @b would compile if you simply omit
1098     wxTRANSLATE() in the above, it wouldn't work as expected because there
1099     would be no translations for the weekday names in the program message
1100     catalog and wxGetTranslation() wouldn't find them.
1101
1102     @return A const wxChar*.
1103
1104     @header{wx/intl.h}
1105 */
1106 #define wxTRANSLATE(string)
1107
1108 /**
1109     This function returns the translation of @a string in the current
1110     @c locale(). If the string is not found in any of the loaded message
1111     catalogs (see @ref overview_i18n), the original string is returned. In
1112     debug build, an error message is logged -- this should help to find the
1113     strings which were not yet translated.  If @a domain is specified then only
1114     that domain/catalog is searched for a matching string.  As this function is
1115     used very often, an alternative (and also common in Unix world) syntax is
1116     provided: the _() macro is defined to do the same thing as
1117     wxGetTranslation().
1118
1119     This function calls wxTranslations::GetString().
1120
1121     @note This function is not suitable for literal strings in Unicode builds
1122           since the literal strings must be enclosed into _T() or wxT() macro
1123           which makes them unrecognised by @c xgettext, and so they are not
1124           extracted to the message catalog. Instead, use the _() and wxPLURAL()
1125           macro for all literal strings.
1126
1127     @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
1128
1129     @header{wx/intl.h}
1130 */
1131 const wxString& wxGetTranslation(const wxString& string,
1132                                  const wxString& domain = wxEmptyString);
1133
1134 /**
1135     This is an overloaded version of
1136     wxGetTranslation(const wxString&, const wxString&), please see its
1137     documentation for general information.
1138
1139     This version is used when retrieving translation of string that has
1140     different singular and plural forms in English or different plural forms in
1141     some other language. Like wxGetTranslation(const wxString&,const wxString&),
1142     the @a string parameter must contain the singular form of the string to be
1143     converted and is used as the key for the search in the catalog. The
1144     @a plural parameter is the plural form (in English). The parameter @a n is
1145     used to determine the plural form. If no message catalog is found,
1146     @a string is returned if "n == 1", otherwise @a plural is returned.
1147
1148     See GNU gettext Manual for additional information on plural forms handling:
1149     <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
1150     For a shorter alternative see the wxPLURAL() macro.
1151
1152     This function calls wxLocale::GetString().
1153
1154     @header{wx/intl.h}
1155 */
1156 const wxString& wxGetTranslation(const wxString& string,
1157                                  const wxString& plural, size_t n,
1158                                  const wxString& domain = wxEmptyString);
1159
1160 /**
1161     This macro expands into a call to wxGetTranslation(), so it marks the
1162     message for the extraction by @c xgettext just as wxTRANSLATE() does, but
1163     also returns the translation of the string for the current locale during
1164     execution.
1165
1166     Don't confuse this with _T()!
1167
1168     @header{wx/intl.h}
1169 */
1170 const wxString& _(const wxString& string);
1171
1172 //@}
1173