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