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