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 enum wxLocaleInitFlags 213 { 214 wxLOCALE_DONT_LOAD_DEFAULT = 0x0000, ///< Don't load wxstd.mo catalog. 215 wxLOCALE_LOAD_DEFAULT = 0x0001 ///< Load wxstd.mo (done by default). 216 }; 217 218 class wxLocale 219 { 220 public: 221 /** 222 This is the default constructor and it does nothing to initialize the object: 223 Init() must be used to do that. 224 */ 225 wxLocale(); 226 227 /** 228 See Init() for parameters description. 229 */ 230 wxLocale(int language, int flags = wxLOCALE_LOAD_DEFAULT); 231 232 /** 233 See Init() for parameters description. 234 235 The call of this function has several global side effects which you should 236 understand: first of all, the application locale is changed - note that this 237 will affect many of standard C library functions such as printf() or strftime(). 238 Second, this wxLocale object becomes the new current global locale for the 239 application and so all subsequent calls to ::wxGetTranslation() will try to 240 translate the messages using the message catalogs for this locale. 241 */ 242 wxLocale(const wxString& name, 243 const wxString& shortName = wxEmptyString, 244 const wxString& locale = wxEmptyString, 245 bool bLoadDefault = true); 246 247 /** 248 The destructor, like the constructor, also has global side effects: the 249 previously set locale is restored and so the changes described in 250 Init() documentation are rolled back. 251 */ 252 virtual ~wxLocale(); 253 254 /** 255 Calls wxTranslations::AddCatalog(const wxString&). 256 */ 257 bool AddCatalog(const wxString& domain); 258 259 /** 260 Calls wxTranslations::AddCatalog(const wxString&, wxLanguage). 261 */ 262 bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage); 263 264 /** 265 Calls wxTranslations::AddCatalog(const wxString&, wxLanguage, const wxString&). 266 */ 267 bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage, 268 const wxString& msgIdCharset); 269 270 /** 271 Calls wxFileTranslationsLoader::AddCatalogLookupPathPrefix(). 272 */ 273 static void AddCatalogLookupPathPrefix(const wxString& prefix); 274 275 /** 276 Adds custom, user-defined language to the database of known languages. 277 This database is used in conjunction with the first form of Init(). 278 */ 279 static void AddLanguage(const wxLanguageInfo& info); 280 281 /** 282 This function may be used to find the language description structure for the 283 given locale, specified either as a two letter ISO language code (for example, 284 "pt"), a language code followed by the country code ("pt_BR") or a full, human 285 readable, language description ("Portuguese-Brazil"). 286 287 Returns the information for the given language or @NULL if this language 288 is unknown. Note that even if the returned pointer is valid, the caller 289 should @e not delete it. 290 291 @see GetLanguageInfo() 292 */ 293 static const wxLanguageInfo* FindLanguageInfo(const wxString& locale); 294 295 /** 296 Returns the canonical form of current locale name. Canonical form is the 297 one that is used on UNIX systems: it is a two- or five-letter string in xx or 298 xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of 299 the country. Examples are "en", "en_GB", "en_US" or "fr_FR". 300 This form is internally used when looking up message catalogs. 301 Compare GetSysName(). 302 */ 303 wxString GetCanonicalName() const; 304 305 /** 306 Calls wxTranslations::GetHeaderValue(). 307 */ 308 wxString GetHeaderValue(const wxString& header, 309 const wxString& domain = wxEmptyString) const; 310 311 /** 312 Returns the ::wxLanguage constant of current language. 313 314 Note that you can call this function only if you used the form of 315 Init() that takes ::wxLanguage argument. 316 */ 317 int GetLanguage() const; 318 319 /** 320 Returns a pointer to wxLanguageInfo structure containing information about 321 the given language or @NULL if this language is unknown. Note that even if 322 the returned pointer is valid, the caller should @e not delete it. 323 324 See AddLanguage() for the wxLanguageInfo description. 325 As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed 326 as an argument to this function and in this case the result of 327 GetSystemLanguage() is used. 328 */ 329 static const wxLanguageInfo* GetLanguageInfo(int lang); 330 331 /** 332 Returns English name of the given language or empty string if this 333 language is unknown. 334 335 See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT. 336 */ 337 static wxString GetLanguageName(int lang); 338 339 /** 340 Returns canonical name (see GetCanonicalName()) of the given language 341 or empty string if this language is unknown. 342 343 See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT. 344 345 @since 2.9.1 346 */ 347 static wxString GetLanguageCanonicalName(int lang); 348 349 /** 350 Returns the locale name as passed to the constructor or Init(). 351 352 This is a full, human-readable name, e.g. "English" or "French". 353 */ 354 const wxString& GetLocale() const; 355 356 /** 357 Returns the current short name for the locale (as given to the constructor or 358 the Init() function). 359 */ 360 const wxString& GetName() const; 361 362 /** 363 Calls wxGetTranslation(const wxString&, const wxString&). 364 */ 365 const wxString& GetString(const wxString& origString, 366 const wxString& domain = wxEmptyString) const; 367 368 /** 369 Calls wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&). 370 */ 371 const wxString& GetString(const wxString& origString, 372 const wxString& origString2, unsigned n, 373 const wxString& domain = wxEmptyString) const; 374 375 /** 376 Returns current platform-specific locale name as passed to setlocale(). 377 Compare GetCanonicalName(). 378 */ 379 wxString GetSysName() const; 380 381 /** 382 Tries to detect the user's default font encoding. 383 Returns wxFontEncoding() value or @c wxFONTENCODING_SYSTEM if it 384 couldn't be determined. 385 */ 386 static wxFontEncoding GetSystemEncoding(); 387 388 /** 389 Tries to detect the name of the user's default font encoding. 390 This string isn't particularly useful for the application as its form is 391 platform-dependent and so you should probably use GetSystemEncoding() instead. 392 393 Returns a user-readable string value or an empty string if it couldn't be 394 determined. 395 */ 396 static wxString GetSystemEncodingName(); 397 398 /** 399 Tries to detect the user's default locale setting. 400 401 Returns the ::wxLanguage value or @c wxLANGUAGE_UNKNOWN if the language-guessing 402 algorithm failed. 403 404 @note This function works with @em locales and returns the user's default 405 locale. This may be, and usually is, the same as their preferred UI 406 language, but it's not the same thing. Use wxTranslation to obtain 407 @em language information. 408 409 @see wxTranslations::GetBestTranslation(). 410 */ 411 static int GetSystemLanguage(); 412 413 /** 414 Get the values of the given locale-dependent datum. 415 416 This function returns the value of the locale-specific option specified 417 by the given @a index. 418 419 @param index 420 One of the elements of wxLocaleInfo enum. 421 @param cat 422 The category to use with the given index or wxLOCALE_CAT_DEFAULT if 423 the index can only apply to a single category. 424 @return 425 The option value or empty string if the function failed. 426 */ 427 static wxString GetInfo(wxLocaleInfo index, 428 wxLocaleCategory cat = wxLOCALE_CAT_DEFAULT); 429 430 /** 431 Initializes the wxLocale instance. 432 433 The call of this function has several global side effects which you should 434 understand: first of all, the application locale is changed - note that 435 this will affect many of standard C library functions such as printf() 436 or strftime(). 437 Second, this wxLocale object becomes the new current global locale for 438 the application and so all subsequent calls to wxGetTranslation() will 439 try to translate the messages using the message catalogs for this locale. 440 441 @param language 442 ::wxLanguage identifier of the locale. 443 @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's 444 default language (see GetSystemLanguage()). 445 @param flags 446 Combination of the following: 447 - wxLOCALE_LOAD_DEFAULT: Load the message catalog for the given locale 448 containing the translations of standard wxWidgets messages 449 automatically. 450 - wxLOCALE_DONT_LOAD_DEFAULT: Negation of wxLOCALE_LOAD_DEFAULT. 451 452 @return @true on success or @false if the given locale couldn't be set. 453 */ 454 bool Init(int language = wxLANGUAGE_DEFAULT, 455 int flags = wxLOCALE_LOAD_DEFAULT); 456 457 /** 458 @deprecated 459 This form is deprecated, use the other one unless you know what you are doing. 460 461 @param name 462 The name of the locale. Only used in diagnostic messages. 463 @param shortName 464 The standard 2 letter locale abbreviation; it is used as the 465 directory prefix when looking for the message catalog files. 466 @param locale 467 The parameter for the call to setlocale(). 468 Note that it is platform-specific. 469 @param bLoadDefault 470 May be set to @false to prevent loading of the message catalog for the 471 given locale containing the translations of standard wxWidgets messages. 472 This parameter would be rarely used in normal circumstances. 473 */ 474 bool Init(const wxString& name, const wxString& shortName = wxEmptyString, 475 const wxString& locale = wxEmptyString, bool bLoadDefault = true); 476 477 /** 478 Check whether the operating system and/or C run time environment supports 479 this locale. For example in Windows 2000 and Windows XP, support for many 480 locales is not installed by default. Returns @true if the locale is 481 supported. 482 483 The argument @a lang is the ::wxLanguage identifier. To obtain this for a 484 given a two letter ISO language code, use FindLanguageInfo() to obtain its 485 wxLanguageInfo structure. 486 See AddLanguage() for the wxLanguageInfo description. 487 488 @since 2.7.1. 489 */ 490 static bool IsAvailable(int lang); 491 492 /** 493 Calls wxTranslations::IsLoaded(). 494 */ 495 bool IsLoaded(const wxString& domain) const; 496 497 /** 498 Returns @true if the locale could be set successfully. 499 */ 500 bool IsOk() const; 501 }; 502 503 504 505 /** 506 Get the current locale object (note that it may be NULL!) 507 */ 508 wxLocale* wxGetLocale(); 509 510