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