interface/wx/intl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        intl.h
   3 // Purpose:     interface of wxLocale
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     This is the layout direction stored in wxLanguageInfo and returned by
  10     wxApp::GetLayoutDirection(), wxWindow::GetLayoutDirection(),
  11     wxDC::GetLayoutDirection() for RTL (right-to-left) languages support.
  12 */
  13 enum wxLayoutDirection
  14 {
  15     wxLayout_Default,
  16     wxLayout_LeftToRight,
  17     wxLayout_RightToLeft
  18 };
  19
  20 /**
  21     Encapsulates a ::wxLanguage identifier together with OS-specific information
  22     related to that language.
  23
  24     @beginWxPerlOnly
  25     In wxPerl @c Wx::LanguageInfo has only one method:
  26     - Wx::LanguageInfo->new(language, canonicalName, WinLang, WinSubLang, Description)
  27     @endWxPerlOnly
  28 */
  29 struct wxLanguageInfo
  30 {
  31     /// ::wxLanguage id.
  32     /// It should be greater than @c wxLANGUAGE_USER_DEFINED when defining your own
  33     /// language info structure.
  34     int Language;
  35
  36     /// Canonical name of the language, e.g. @c fr_FR.
  37     wxString CanonicalName;
  38
  39     //@{
  40     /**
  41         Win32 language identifiers (LANG_xxxx, SUBLANG_xxxx).
  42
  43         @onlyfor{wxmsw}
  44     */
  45     wxUint32 WinLang, WinSublang;
  46     //@}
  47
  48     /// Human-readable name of the language.
  49     wxString Description;
  50
  51     /// The layout direction used for this language.
  52     wxLayoutDirection LayoutDirection;
  53
  54     /// Return the LCID corresponding to this language.
  55     /// @onlyfor{wxmsw}
  56     wxUint32 GetLCID() const;
  57
  58     /// Return the locale name corresponding to this language usable with
  59     /// @c setlocale() on the current system.
  60     wxString GetLocaleName() const;
  61 };
  62
  63
  64 /**
  65     The category of locale settings.
  66
  67     @see wxLocale::GetInfo()
  68 */
  69 enum wxLocaleCategory
  70 {
  71     /// Number formatting.
  72     wxLOCALE_CAT_NUMBER,
  73
  74     /// Date/time formatting.
  75     wxLOCALE_CAT_DATE,
  76
  77     /// Monetary values formatting.
  78     wxLOCALE_CAT_MONEY,
  79
  80     /**
  81         Default category for the wxLocaleInfo value.
  82
  83         This category can be used for values which only make sense for a single
  84         category, e.g. wxLOCALE_SHORT_DATE_FMT which can only be used with
  85         wxLOCALE_CAT_DATE. As this is the default value of the second parameter
  86         of wxLocale::GetInfo(), wxLOCALE_CAT_DATE can be omitted when asking
  87         for wxLOCALE_SHORT_DATE_FMT value.
  88
  89         @since 2.9.0
  90      */
  91     wxLOCALE_CAT_DEFAULT
  92 };
  93
  94 /**
  95     The values understood by wxLocale::GetInfo().
  96
  97     Note that for the @c wxLOCALE_*_FMT constants (the date and time formats),
  98     the strings returned by wxLocale::GetInfo() use strftime() or,
  99     equivalently, wxDateTime::Format() format. If the relevant format
 100     couldn't be determined, an empty string is returned -- there is no
 101     fallback value so that the application could determine the best course
 102     of actions itself in such case.
 103
 104     All of these values are used with @c wxLOCALE_CAT_DATE in wxLocale::GetInfo() or,
 105     more typically, with @c wxLOCALE_CAT_DEFAULT as they only apply to a single category.
 106 */
 107 enum wxLocaleInfo
 108 {
 109     /**
 110         The thousands separator.
 111
 112         This value can be used with either wxLOCALE_CAT_NUMBER or
 113         wxLOCALE_CAT_MONEY categories.
 114      */
 115     wxLOCALE_THOUSANDS_SEP,
 116
 117     /**
 118         The character used as decimal point.
 119
 120         This value can be used with either wxLOCALE_CAT_NUMBER or
 121         wxLOCALE_CAT_MONEY categories.
 122      */
 123     wxLOCALE_DECIMAL_POINT,
 124
 125     /**
 126         Short date format.
 127
 128         Notice that short and long date formats may be the same under POSIX
 129         systems currently but may, and typically are, different under MSW or OS X.
 130
 131         @since 2.9.0
 132      */
 133     wxLOCALE_SHORT_DATE_FMT,
 134
 135     /**
 136         Long date format.
 137
 138         @since 2.9.0
 139      */
 140     wxLOCALE_LONG_DATE_FMT,
 141
 142     /**
 143         Date and time format.
 144
 145         @since 2.9.0
 146      */
 147     wxLOCALE_DATE_TIME_FMT,
 148
 149     /**
 150         Time format.
 151
 152         @since 2.9.0
 153      */
 154     wxLOCALE_TIME_FMT
 155 };
 156
 157
 158 /**
 159     @class wxLocale
 160
 161     wxLocale class encapsulates all language-dependent settings and is a
 162     generalization of the C locale concept.
 163
 164     In wxWidgets this class manages current locale. It also initializes and
 165     activates wxTranslations object that manages message catalogs.
 166
 167     For a list of the supported languages, please see ::wxLanguage enum values.
 168     These constants may be used to specify the language in wxLocale::Init and
 169     are returned by wxLocale::GetSystemLanguage.
 170
 171     @beginWxPerlOnly
 172     In wxPerl you can't use the '_' function name, so
 173     the @c Wx::Locale module can export the @c gettext and
 174     @c gettext_noop under any given name.
 175
 176     @code
 177       # this imports gettext ( equivalent to Wx::GetTranslation
 178       # and gettext_noop ( a noop )
 179       # into your module
 180       use Wx::Locale qw(:default);
 181
 182       # ....
 183
 184       # use the functions
 185       print gettext( "Panic!" );
 186
 187       button = Wx::Button-new( window, -1, gettext( "Label" ) );
 188     @endcode
 189
 190     If you need to translate a lot of strings, then adding gettext( ) around
 191     each one is a long task ( that is why _( ) was introduced ), so just choose
 192     a shorter name for gettext:
 193
 194     @code
 195       use Wx::Locale 'gettext' = 't',
 196                      'gettext_noop' = 'gettext_noop';
 197
 198       # ...
 199
 200       # use the functions
 201       print t( "Panic!!" );
 202
 203       # ...
 204     @endcode
 205     @endWxPerlOnly
 206
 207     @library{wxbase}
 208     @category{cfg}
 209
 210     @see @ref overview_i18n, @ref page_samples_internat, wxXLocale, wxTranslations
 211 */
 212 class wxLocale
 213 {
 214 public:
 215     /**
 216         This is the default constructor and it does nothing to initialize the object:
 217         Init() must be used to do that.
 218     */
 219     wxLocale();
 220
 221     /**
 222         See Init() for parameters description.
 223     */
 224     wxLocale(int language, int flags = wxLOCALE_LOAD_DEFAULT);
 225
 226     /**
 227         See Init() for parameters description.
 228
 229         The call of this function has several global side effects which you should
 230         understand: first of all, the application locale is changed - note that this
 231         will affect many of standard C library functions such as printf() or strftime().
 232         Second, this wxLocale object becomes the new current global locale for the
 233         application and so all subsequent calls to ::wxGetTranslation() will try to
 234         translate the messages using the message catalogs for this locale.
 235     */
 236     wxLocale(const wxString& name,
 237              const wxString& shortName = wxEmptyString,
 238              const wxString& locale = wxEmptyString,
 239              bool bLoadDefault = true);
 240
 241     /**
 242         The destructor, like the constructor, also has global side effects: the
 243         previously set locale is restored and so the changes described in
 244         Init() documentation are rolled back.
 245     */
 246     virtual ~wxLocale();
 247
 248     /**
 249         Calls wxTranslations::AddCatalog(const wxString&).
 250     */
 251     bool AddCatalog(const wxString& domain);
 252
 253     /**
 254         Calls wxTranslations::AddCatalog(const wxString&, wxLanguage).
 255     */
 256     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage);
 257
 258     /**
 259         Calls wxTranslations::AddCatalog(const wxString&, wxLanguage, const wxString&).
 260     */
 261     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage,
 262                     const wxString& msgIdCharset);
 263
 264     /**
 265         Calls wxFileTranslationsLoader::AddCatalogLookupPathPrefix().
 266     */
 267     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 268
 269     /**
 270         Adds custom, user-defined language to the database of known languages.
 271         This database is used in conjunction with the first form of Init().
 272     */
 273     static void AddLanguage(const wxLanguageInfo& info);
 274
 275     /**
 276         This function may be used to find the language description structure for the
 277         given locale, specified either as a two letter ISO language code (for example,
 278         "pt"), a language code followed by the country code ("pt_BR") or a full, human
 279         readable, language description ("Portuguese-Brazil").
 280
 281         Returns the information for the given language or @NULL if this language
 282         is unknown. Note that even if the returned pointer is valid, the caller
 283         should @e not delete it.
 284
 285         @see GetLanguageInfo()
 286     */
 287     static const wxLanguageInfo* FindLanguageInfo(const wxString& locale);
 288
 289     /**
 290         Returns the canonical form of current locale name. Canonical form is the
 291         one that is used on UNIX systems: it is a two- or five-letter string in xx or
 292         xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of
 293         the country. Examples are "en", "en_GB", "en_US" or "fr_FR".
 294         This form is internally used when looking up message catalogs.
 295         Compare GetSysName().
 296     */
 297     wxString GetCanonicalName() const;
 298
 299     /**
 300         Calls wxTranslations::GetHeaderValue().
 301     */
 302     wxString GetHeaderValue(const wxString& header,
 303                             const wxString& domain = wxEmptyString) const;
 304
 305     /**
 306         Returns the ::wxLanguage constant of current language.
 307
 308         Note that you can call this function only if you used the form of
 309         Init() that takes ::wxLanguage argument.
 310     */
 311     int GetLanguage() const;
 312
 313     /**
 314         Returns a pointer to wxLanguageInfo structure containing information about
 315         the given language or @NULL if this language is unknown. Note that even if
 316         the returned pointer is valid, the caller should @e not delete it.
 317
 318         See AddLanguage() for the wxLanguageInfo description.
 319         As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed
 320         as an argument to this function and in this case the result of
 321         GetSystemLanguage() is used.
 322     */
 323     static const wxLanguageInfo* GetLanguageInfo(int lang);
 324
 325     /**
 326         Returns English name of the given language or empty string if this
 327         language is unknown.
 328
 329         See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
 330     */
 331     static wxString GetLanguageName(int lang);
 332
 333     /**
 334         Returns canonical name (see GetCanonicalName()) of the given language
 335         or empty string if this language is unknown.
 336
 337         See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
 338
 339         @since 2.9.1
 340     */
 341     static wxString GetLanguageCanonicalName(int lang);
 342
 343     /**
 344         Returns the locale name as passed to the constructor or Init().
 345
 346         This is a full, human-readable name, e.g. "English" or "French".
 347     */
 348     const wxString& GetLocale() const;
 349
 350     /**
 351         Returns the current short name for the locale (as given to the constructor or
 352         the Init() function).
 353     */
 354     const wxString& GetName() const;
 355
 356     /**
 357         Calls wxTranslations::GetString(const wxString&, const wxString&) const.
 358     */
 359     virtual const wxString& GetString(const wxString& origString,
 360                                       const wxString& domain = wxEmptyString) const;
 361
 362     /**
 363         Calls wxTranslations::GetString(const wxString&, const wxString&, unsigned, const wxString&) const.
 364     */
 365     virtual const wxString& GetString(const wxString& origString,
 366                                       const wxString& origString2, unsigned n,
 367                                       const wxString& domain = wxEmptyString) const;
 368
 369     /**
 370         Returns current platform-specific locale name as passed to setlocale().
 371         Compare GetCanonicalName().
 372     */
 373     wxString GetSysName() const;
 374
 375     /**
 376         Tries to detect the user's default font encoding.
 377         Returns wxFontEncoding() value or @c wxFONTENCODING_SYSTEM if it
 378         couldn't be determined.
 379     */
 380     static wxFontEncoding GetSystemEncoding();
 381
 382     /**
 383         Tries to detect the name of the user's default font encoding.
 384         This string isn't particularly useful for the application as its form is
 385         platform-dependent and so you should probably use GetSystemEncoding() instead.
 386
 387         Returns a user-readable string value or an empty string if it couldn't be
 388         determined.
 389     */
 390     static wxString GetSystemEncodingName();
 391
 392     /**
 393         Tries to detect the user's default locale setting.
 394
 395         Returns the ::wxLanguage value or @c wxLANGUAGE_UNKNOWN if the language-guessing
 396         algorithm failed.
 397
 398         @note This function works with @em locales and returns the user's default
 399               locale. This may be, and usually is, the same as their preferred UI
 400               language, but it's not the same thing. Use wxTranslation to obtain
 401               @em language information.
 402
 403         @see wxTranslations::GetBestTranslation().
 404     */
 405     static int GetSystemLanguage();
 406
 407     /**
 408         Get the values of the given locale-dependent datum.
 409
 410         This function returns the value of the locale-specific option specified
 411         by the given @a index.
 412
 413         @param index
 414             One of the elements of wxLocaleInfo enum.
 415         @param cat
 416             The category to use with the given index or wxLOCALE_CAT_DEFAULT if
 417             the index can only apply to a single category.
 418         @return
 419             The option value or empty string if the function failed.
 420     */
 421     static wxString GetInfo(wxLocaleInfo index,
 422                             wxLocaleCategory cat = wxLOCALE_CAT_DEFAULT);
 423
 424     /**
 425         Initializes the wxLocale instance.
 426
 427         The call of this function has several global side effects which you should
 428         understand: first of all, the application locale is changed - note that
 429         this will affect many of standard C library functions such as printf()
 430         or strftime().
 431         Second, this wxLocale object becomes the new current global locale for
 432         the application and so all subsequent calls to wxGetTranslation() will
 433         try to translate the messages using the message catalogs for this locale.
 434
 435         @param language
 436             ::wxLanguage identifier of the locale.
 437             @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's
 438             default language (see GetSystemLanguage()).
 439         @param flags
 440             Combination of the following:
 441             - wxLOCALE_LOAD_DEFAULT: Load the message catalog for the given locale
 442               containing the translations of standard wxWidgets messages
 443               automatically.
 444             - wxLOCALE_DONT_LOAD_DEFAULT: Negation of wxLOCALE_LOAD_DEFAULT.
 445
 446         @return @true on success or @false if the given locale couldn't be set.
 447     */
 448     bool Init(int language = wxLANGUAGE_DEFAULT,
 449               int flags = wxLOCALE_LOAD_DEFAULT);
 450
 451     /**
 452         @deprecated
 453         This form is deprecated, use the other one unless you know what you are doing.
 454
 455         @param name
 456             The name of the locale. Only used in diagnostic messages.
 457         @param shortName
 458             The standard 2 letter locale abbreviation; it is used as the
 459             directory prefix when looking for the message catalog files.
 460         @param locale
 461             The parameter for the call to setlocale().
 462             Note that it is platform-specific.
 463         @param bLoadDefault
 464             May be set to @false to prevent loading of the message catalog for the
 465             given locale containing the translations of standard wxWidgets messages.
 466             This parameter would be rarely used in normal circumstances.
 467     */
 468     bool Init(const wxString& name, const wxString& shortName = wxEmptyString,
 469               const wxString& locale = wxEmptyString, bool bLoadDefault = true);
 470
 471     /**
 472         Check whether the operating system and/or C run time environment supports
 473         this locale. For example in Windows 2000 and Windows XP, support for many
 474         locales is not installed by default. Returns @true if the locale is
 475         supported.
 476
 477         The argument @a lang is the ::wxLanguage identifier. To obtain this for a
 478         given a two letter ISO language code, use FindLanguageInfo() to obtain its
 479         wxLanguageInfo structure.
 480         See AddLanguage() for the wxLanguageInfo description.
 481
 482         @since 2.7.1.
 483     */
 484     static bool IsAvailable(int lang);
 485
 486     /**
 487         Calls wxTranslations::IsLoaded().
 488     */
 489     bool IsLoaded(const wxString& domain) const;
 490
 491     /**
 492         Returns @true if the locale could be set successfully.
 493     */
 494     bool IsOk() const;
 495 };