]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/intl.h
Add test for absence of events from wxSpinCtrlDouble ctor.
[wxWidgets.git] / 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 short
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 };