0e544960b0
There are several ways to do it, and it's not clear which one of them should be illustrated here, but it should definitely be one that works. Closes #22389.
586 lines
21 KiB
C++
586 lines
21 KiB
C++
///////////////////////////////////////////////////////////////////////////////
|
|
// Name: wx/uilocale.h
|
|
// Purpose: Interface of wxUILocale
|
|
// Author: Vadim Zeitlin
|
|
// Created: 2021-08-01
|
|
// Copyright: (c) 2021 Vadim Zeitlin <vadim@wxwidgets.org>
|
|
// Licence: wxWindows licence
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
Flags for wxUILocale::CompareStrings() function.
|
|
|
|
@since 3.1.6
|
|
*/
|
|
enum
|
|
{
|
|
/// Compare strings case-sensitively, this is the default.
|
|
wxCompare_CaseSensitive = 0,
|
|
|
|
/**
|
|
Ignore strings case when comparing.
|
|
|
|
Note that this flag is not supported under POSIX systems, where it is
|
|
simply ignored.
|
|
*/
|
|
wxCompare_CaseInsensitive = 1
|
|
};
|
|
|
|
/**
|
|
Query and modify locale used for the UI by the current platform.
|
|
|
|
UI locale determines all culture-dependent conventions used in the user
|
|
interface, including numbers, currencies and dates formatting. It also
|
|
determines the language used by the native dialogs, such as wxFileDialog,
|
|
where different labels use the language corresponding to the current UI
|
|
locale.
|
|
|
|
The UI locale is, in general, different from C locale set by the standard
|
|
@c setlocale() function and affecting C standard library functions such as
|
|
@c printf(), @c scanf(), @c strftime() and many others. Unfortunately, the
|
|
relationship between C and UI locales is not the same depending on the
|
|
platform: with wxGTK they must be the same, but under macOS C locale must
|
|
not be changed, as doing this exposes bugs in the system. Because of this,
|
|
applications can't generally count on C locale being set to any particular
|
|
value and it is best to avoid using it, including implicitly via the
|
|
standard C functions, in portable code. Instead, consider using
|
|
wxNumberFormatter for parsing and formatting numbers according to the
|
|
current UI locale or wxString::FromCDouble() and wxString::ToCDouble()
|
|
functions for doing it always using period as decimal separator.
|
|
|
|
Localized applications should call wxUILocale::UseDefault() on startup to
|
|
explicitly indicate that they opt-in using the current UI locale, even if
|
|
this results in changing the global C locale, as is the case in wxGTK. Note
|
|
that some platforms (MSW and macOS) will use default user locale for their
|
|
standard dialogs even if this function is not called, but it is still
|
|
necessary to call it to use the correct number and date formats and to
|
|
avoid mixing messages in the user language with default formats not
|
|
corresponding to it.
|
|
|
|
Please also note that under macOS to really use the user locale, it must be
|
|
listed as a supported language in the application @c Info.plist file under
|
|
@c CFBundleLocalizations key.
|
|
|
|
Unlike wxLocale class, this class doesn't affect the translations used by
|
|
the application, see wxTranslations for doing this.
|
|
|
|
@library{wxbase}
|
|
@since 3.1.6
|
|
*/
|
|
class wxUILocale
|
|
{
|
|
public:
|
|
/**
|
|
Configure the UI to use the default user locale.
|
|
|
|
Localized applications should call this functions as early as possible
|
|
during the program startup, e.g. in the very beginning of the
|
|
overridden wxApp::OnInit().
|
|
|
|
Note that under most Unix systems (but not macOS) this function changes
|
|
the C locale to the locale specified by the environment variables and
|
|
so affects the results of calling C functions such as @c sprintf() etc
|
|
which can use comma, rather than period, as decimal separator. The
|
|
wxString::ToCDouble() and wxString::FromCDouble() functions can be used
|
|
for parsing and formatting floating point numbers using period as
|
|
decimal separator independently of the current locale.
|
|
|
|
@return @true on success or @false if the default locale couldn't be set
|
|
*/
|
|
static bool UseDefault();
|
|
|
|
/**
|
|
Get the object corresponding to the currently used locale.
|
|
|
|
If UseDefault() had been called, this object corresponds to the default
|
|
user locale. Otherwise it corresponds to a generic locale similar to
|
|
"C" locale, i.e. always uses period as decimal separator and m/d/y date
|
|
format.
|
|
*/
|
|
static const wxUILocale& GetCurrent();
|
|
|
|
/**
|
|
Creates the local corresponding to the given language tag.
|
|
|
|
This is exactly equivalent to using wxUILocale constructor with
|
|
the locale identifier returned by wxLocaleIdent::FromTag(), but
|
|
shorter.
|
|
|
|
See wxLocaleIdent::FromTag() for more information about the syntax of
|
|
the @a tag string.
|
|
*/
|
|
static wxUILocale FromTag(const wxString& tag);
|
|
|
|
/**
|
|
Creates the locale corresponding to the given locale identifier.
|
|
|
|
In the simplest case, this can be used as following:
|
|
@code
|
|
const wxUILocale loc(wxLocaleIdent().Language("fr"));
|
|
@endcode
|
|
see wxLocaleIdent description for more details, including other ways of
|
|
specifying the locale.
|
|
|
|
If @a localeId is not recognized or not supported, default ("C") locale
|
|
is used instead. Additionally, if @a localeId is empty (see
|
|
wxLocaleIdent::IsEmpty()), an assertion failure is triggered.
|
|
*/
|
|
explicit wxUILocale(const wxLocaleIdent& localeId);
|
|
|
|
/**
|
|
Compares two strings using comparison rules of this locale.
|
|
|
|
This function is useful for sorting the strings in the order expected
|
|
by the user, e.g. by correctly sorting "ä" in the same way as "a" when
|
|
using German locale, but not when using Swedish one, in which "ä" is
|
|
sorted after "z".
|
|
|
|
It can be used both with the current locale, and with any other
|
|
supported locale, even under systems not supporting changing the UI
|
|
locale, such as macOS.
|
|
|
|
@param lhs
|
|
First comparing string.
|
|
@param rhs
|
|
Second comparing string.
|
|
@param flags
|
|
Can be used to specify whether to compare strings case-sensitively
|
|
(default) or not, by specifying ::wxCompare_CaseInsensitive (note
|
|
that this flag only works under MSW and Mac and is simply ignored
|
|
under the other platforms).
|
|
@return
|
|
-1 if @a lhs is less than @a rhs.
|
|
0 if @a lhs is equal to @a rhs.
|
|
1 if @a lhs is greater than @a rhs.
|
|
*/
|
|
int CompareStrings(const wxString& lhs, const wxString& rhs,
|
|
int flags = wxCompare_CaseSensitive) const;
|
|
|
|
/**
|
|
Get the platform-dependent name of the current locale.
|
|
|
|
This name can be used in diagnostic messages.
|
|
*/
|
|
wxString GetName() const;
|
|
|
|
/**
|
|
Get the locale id from which the current locale was instantiated.
|
|
*/
|
|
wxLocaleIdent GetLocaleId() const;
|
|
|
|
/**
|
|
Query the locale for the specified information.
|
|
|
|
This function returns the value of the locale-specific option specified
|
|
by the given @a index.
|
|
|
|
@param index
|
|
One of the elements of wxLocaleInfo enum.
|
|
@param cat
|
|
The category to use with the given index or wxLOCALE_CAT_DEFAULT if
|
|
the index can only apply to a single category.
|
|
@return
|
|
The option value or empty string if the function failed.
|
|
*/
|
|
wxString GetInfo(wxLocaleInfo index,
|
|
wxLocaleCategory cat = wxLOCALE_CAT_DEFAULT) const;
|
|
|
|
/**
|
|
Query the locale for the specified localized name.
|
|
|
|
@param name
|
|
One of the elements of wxLocaleName enum.
|
|
@param form
|
|
The representation form requested.
|
|
@return
|
|
The localized name value or empty string if the function failed.
|
|
*/
|
|
wxString GetLocalizedName(wxLocaleName name, wxLocaleForm form) const;
|
|
|
|
/**
|
|
Query the layout direction of the current locale.
|
|
|
|
@return
|
|
The layout direction or wxLayout_Default if the function failed.
|
|
*/
|
|
wxLayoutDirection GetLayoutDirection() const;
|
|
|
|
/**
|
|
Return true if locale is supported on the current system.
|
|
|
|
If this function returns @a false, the other functions of this class,
|
|
such as GetInfo() and CompareStrings(), behave as in "C" locale, i.e.
|
|
it's still safe to call them, but their results don't reflect the rules
|
|
for the locale in question, but just use the default (i.e. US English)
|
|
conventions.
|
|
*/
|
|
bool IsSupported() const;
|
|
|
|
/**
|
|
Adds custom, user-defined language to the database of known languages.
|
|
This database is used in conjunction with the first form of Init().
|
|
*/
|
|
static void AddLanguage(const wxLanguageInfo& info);
|
|
|
|
/**
|
|
This function may be used to find the language description structure for the
|
|
given locale, specified either as a two letter ISO language code (for example,
|
|
"pt"), a language code followed by the country code ("pt_BR") or a full, human
|
|
readable, language description ("Portuguese_Brazil"). Please note that only
|
|
the underscore character is supported as the separator between language and
|
|
region codes.
|
|
|
|
Returns the information for the given language or @NULL if this language
|
|
is unknown. Note that even if the returned pointer is valid, the caller
|
|
should @e not delete it.
|
|
|
|
@see GetLanguageInfo()
|
|
*/
|
|
static const wxLanguageInfo* FindLanguageInfo(const wxString& locale);
|
|
|
|
/**
|
|
This function may be used to find the language description structure for the
|
|
given locale, specified as a locale identifier.
|
|
|
|
Returns the information for the given language or @NULL if this language
|
|
is unknown. Note that even if the returned pointer is valid, the caller
|
|
should @e not delete it.
|
|
|
|
@see GetLanguageInfo()
|
|
*/
|
|
static const wxLanguageInfo* FindLanguageInfo(const wxLocaleIdent& localeId);
|
|
|
|
/**
|
|
Returns a pointer to wxLanguageInfo structure containing information about
|
|
the given language or @NULL if this language is unknown. Note that even if
|
|
the returned pointer is valid, the caller should @e not delete it.
|
|
|
|
See AddLanguage() for the wxLanguageInfo description.
|
|
As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed
|
|
as an argument to this function and in this case the result of
|
|
GetSystemLanguage() is used.
|
|
*/
|
|
static const wxLanguageInfo* GetLanguageInfo(int lang);
|
|
|
|
/**
|
|
Returns English name of the given language or empty string if this
|
|
language is unknown.
|
|
|
|
See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
|
|
*/
|
|
static wxString GetLanguageName(int lang);
|
|
|
|
/**
|
|
Returns canonical name (see GetCanonicalName()) of the given language
|
|
or empty string if this language is unknown.
|
|
|
|
See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT.
|
|
*/
|
|
static wxString GetLanguageCanonicalName(int lang);
|
|
|
|
/**
|
|
Tries to detect the user's default user interface language setting.
|
|
|
|
Returns the ::wxLanguage value or @c wxLANGUAGE_UNKNOWN if the language-guessing
|
|
algorithm failed.
|
|
|
|
@note Where possible this function returns the user's preferred UI @em language.
|
|
This may be, and usually is, the same as the user's default locale, but it's
|
|
not the same thing. If retrieving the preferred UI language is not supported
|
|
by the operating system (for example, Windows 7 and below), the user's
|
|
default @em locale will be used.
|
|
|
|
@see wxTranslations::GetBestTranslation().
|
|
*/
|
|
static int GetSystemLanguage();
|
|
|
|
/**
|
|
Tries to detect the user's default locale setting.
|
|
|
|
Returns the ::wxLanguage value or @c wxLANGUAGE_UNKNOWN if the locale-guessing
|
|
algorithm failed.
|
|
|
|
@note This function works with @em locales and returns the user's default
|
|
locale. This may be, and usually is, the same as their preferred UI
|
|
language, but it's not the same thing. Use wxTranslation to obtain
|
|
@em language information.
|
|
|
|
@since 3.1.7
|
|
|
|
@see wxTranslations::GetBestTranslation().
|
|
*/
|
|
static int GetSystemLocale();};
|
|
|
|
/**
|
|
Return the format to use for formatting user-visible dates.
|
|
|
|
This is a simple wrapper function normally calling wxUILocale::GetInfo()
|
|
with wxLOCALE_SHORT_DATE_FMT argument, but which is also available when @c
|
|
wxUSE_INTL==0, i.e. support for internationalization is disabled at
|
|
compile-time, in which case it returns @c %x string, i.e. uses the current
|
|
C locale formatting rather than UI locale.
|
|
|
|
@see wxDateTime::Format()
|
|
|
|
@since 3.1.6
|
|
*/
|
|
wxString wxGetUIDateFormat();
|
|
|
|
/**
|
|
Represents a locale in a portable way.
|
|
|
|
There are two possible ways to construct wxLocaleIdent:
|
|
|
|
- You can either use FromTag() to create it from a string in the form
|
|
`language ["-" script] ["-" region]`, corresponding to
|
|
the subset of BCP 47 (https://www.rfc-editor.org/rfc/bcp/bcp47.txt)
|
|
syntax.
|
|
- Or you can create it from the different parts of this string by using
|
|
the default constructor and then chaining calls to Language(),
|
|
Region(), Script() and other methods.
|
|
|
|
The first method is useful for interoperating with the other software using
|
|
BCP 47 language tags, while the second one may may result in more readable
|
|
code and allows to specify Unix-specific locale description parts such as
|
|
charset and modifier that are not part of the BCP 47 strings.
|
|
|
|
Example of using wxLocaleIdent in the second way:
|
|
@code
|
|
auto loc = wxLocaleIdent().Language("fr").Region("BE").Modifier("euro");
|
|
#if defined(__WINDOWS__) || defined(__WXOSX__)
|
|
wxASSERT( loc.GetName() == "fr_BE" );
|
|
#elif defined(__UNIX__)
|
|
wxASSERT( loc.GetName() == "fr_BE@euro" );
|
|
#endif
|
|
@endcode
|
|
|
|
For the first way, it is enough to just write
|
|
@code
|
|
auto loc = wxLocaleIdent::FromTag("fr-BE"); // Dash, not underscore!
|
|
@endcode
|
|
|
|
@since 3.1.6
|
|
*/
|
|
class wxLocaleIdent
|
|
{
|
|
public:
|
|
/**
|
|
Return the locale identifier corresponding to the given locale tag.
|
|
|
|
This method accepts locale tags in various formats:
|
|
|
|
- BCP-47,
|
|
- Windows,
|
|
- POSIX,
|
|
- macOS. and
|
|
- MSVC CRT.
|
|
|
|
See section 2.01 of https://www.rfc-editor.org/rfc/bcp/bcp47.txt for the
|
|
full BCP-47 syntax. Here we fully support just the subset we're interested in:
|
|
|
|
- Normal language tags (not private use or grandfathered ones),
|
|
- Script, and
|
|
- Region.
|
|
|
|
Additionally platform-specific tags are supported:
|
|
|
|
- Extensions (without validity checks) (Windows only),
|
|
- Sortorder (Windows only)
|
|
- Charset (POSIX only), and
|
|
- Modifier (POSIX only).
|
|
|
|
Only language, script, and region are supported across all platforms.
|
|
The script tag is mapped to the modifier tag for POSIX platforms.
|
|
The script tag takes precedence, if a modifier is also specified.
|
|
|
|
The following tag syntax is accepted:
|
|
|
|
- BCP-47: \<language\>[-\<script\>][-\<region\>][-\<extension\>]
|
|
- Windows: \<language\>[-\<script\>][-\<region\>][-\<extension\>][_\<sortorder\>]
|
|
- POSIX: \<language\>[_\<region\>][.\<charset\>][@@\<modifier\>]
|
|
- macOS: \<language\>[-\<script\>][_\<region\>]
|
|
- MSVC CRT: \<language\>[_\<region\>][.\<charset\>]
|
|
|
|
The string must contain at least the language part (2 or 3 ASCII
|
|
letters) and may contain script and region separated by dashes, i.e.
|
|
all of the following are valid:
|
|
|
|
- "mn"
|
|
- "mn-MN"
|
|
- "mn-Cyrl-MN"
|
|
|
|
Note that while BCP 47 extlangs, variants, extensions, private use and
|
|
grandfathered tags are currently not directly supported, they may still
|
|
work for creating wxUILocale on platforms with native support for BCP
|
|
47 strings.
|
|
|
|
If the input argument uses an unrecognized syntax (e.g. is empty), an
|
|
empty wxLocaleIdent is returned. Of course, even if this function
|
|
returns a non-empty object, the resulting locale may still be invalid
|
|
or unsupported, use wxUILocale::IsSupported() to check for this.
|
|
|
|
Note that the format "MSVC CRT" (Microsoft Visual C++ C RunTime) is
|
|
only supported as an input format, so that locale names as returned
|
|
by the CRT function setlocale can be handled, mainly for compatibility
|
|
with wxLocale.
|
|
*/
|
|
static wxLocaleIdent FromTag(const wxString& tag);
|
|
|
|
/**
|
|
Default constructor creates an empty and invalid locale identifier.
|
|
|
|
At least Language() must be called to make the identifier valid.
|
|
*/
|
|
wxLocaleIdent();
|
|
|
|
/**
|
|
Set language.
|
|
|
|
Return reference to `this` for method chaining.
|
|
|
|
See https://www.loc.gov/standards/iso639-2/php/English_list.php for the
|
|
list of all language codes.
|
|
|
|
@param language
|
|
A two-letter ISO 639-1 language code or a three-letter ISO 639-2
|
|
code for the languages without ISO 639-1 codes.
|
|
*/
|
|
wxLocaleIdent& Language(const wxString& language);
|
|
|
|
/**
|
|
Set region.
|
|
Return reference to `this` for method chaining.
|
|
|
|
@param region
|
|
It specifies an uppercase ISO 3166-1 country/region identifier.
|
|
*/
|
|
wxLocaleIdent& Region(const wxString& region);
|
|
|
|
/**
|
|
Set script.
|
|
|
|
Note that under Unix systems the script value is currently mapped
|
|
to the modifier attribute using the script alias name, if the latter
|
|
is known. Otherwise it is ignored.
|
|
|
|
Return reference to `this` for method chaining.
|
|
|
|
@param script
|
|
It is an initial-uppercase ISO 15924 script code.
|
|
*/
|
|
wxLocaleIdent& Script(const wxString& script);
|
|
|
|
/**
|
|
Set charset.
|
|
|
|
Note that this value is only used under Unix systems and simply ignored
|
|
under the other ones.
|
|
|
|
Return reference to `this` for method chaining.
|
|
|
|
@param charset
|
|
Charset is a string such as "UTF-8", "ISO855915" or "KOI8R".
|
|
Supported charsets depend on the implementation and installation.
|
|
*/
|
|
wxLocaleIdent& Charset(const wxString& charset);
|
|
|
|
/**
|
|
Set modifier.
|
|
|
|
Note that this value is only used under Unix systems and simply ignored
|
|
under the other ones.
|
|
Note that under Unix systems the modifier value may represent a script
|
|
value. If the value corresponds to a valid script alias it is mapped
|
|
to the associated script tag.
|
|
|
|
Return reference to `this` for method chaining.
|
|
|
|
@param modifier
|
|
Modifier is a free-form text string.
|
|
*/
|
|
wxLocaleIdent& Modifier(const wxString& modifier);
|
|
|
|
/**
|
|
Set extension.
|
|
|
|
Note that this value is only used under Windows systems and simply ignored
|
|
under the other ones.
|
|
|
|
Return reference to `this` for method chaining.
|
|
|
|
@param extension
|
|
Extension identifiers allow to support custom Windows locales.
|
|
They are usually not portable, not even from one Windows system
|
|
to the other.
|
|
*/
|
|
wxLocaleIdent& Extension(const wxString& extension);
|
|
|
|
/**
|
|
Set sortorder.
|
|
|
|
Note that this value is only used under Windows systems and simply ignored
|
|
under the other ones.
|
|
|
|
Return reference to `this` for method chaining.
|
|
|
|
@param sortorder
|
|
Sortorder identifiers are defined in the Windows Development documentation:
|
|
https://docs.microsoft.com/en-us/windows/win32/intl/sort-order-identifiers.
|
|
*/
|
|
wxLocaleIdent& Sortorder(const wxString& sortorder);
|
|
|
|
/// Return the language part of the locale identifier.
|
|
const wxString& GetLanguage() const;
|
|
|
|
/// Return the region part of the locale identifier.
|
|
const wxString& GetRegion() const;
|
|
|
|
/// Return the script part of the locale identifier.
|
|
const wxString& GetScript() const;
|
|
|
|
/// Return the charset part of the locale identifier.
|
|
const wxString& GetCharset() const;
|
|
|
|
/// Return the modifier part of the locale identifier.
|
|
const wxString& GetModifier() const;
|
|
|
|
/// Return the extension part of the locale identifier.
|
|
const wxString& GetExtension() const;
|
|
|
|
/// Return the sortorder part of the locale identifier.
|
|
const wxString& GetSortorder() const;
|
|
|
|
/**
|
|
Construct platform dependent name.
|
|
|
|
Format:
|
|
- Windows: \<language\>-\<script\>-\<REGION\>-\<extension\>_\<sortorder\>
|
|
- Unix: \<language\>_\<REGION\>.\<charset\>@@{\<modifier\>\|\<scriptalias\>}
|
|
- MacOS: \<language\>-\<script\>_\<REGION\>
|
|
*/
|
|
wxString GetName() const;
|
|
|
|
/**
|
|
Construct name in specified format.
|
|
|
|
Format:
|
|
- Default: name as used in wxLocaleIdent::FromTag() or system format
|
|
- System: name in platform-dependent format
|
|
- Windows: \<language\>-\<script\>-\<REGION\>-\<extension\>_\<sortorder\>
|
|
- Unix: \<language\>_\<REGION\>.\<charset\>@@\<modifier\>
|
|
- MacOS: \<language\>-\<script\>_\<REGION\>
|
|
- BCP 47: \<language\>-\<script\>-\<REGION\>-\<extension\>
|
|
|
|
@param tagType
|
|
Value from wxLocaleTagType enum.
|
|
*/
|
|
wxString GetTag(wxLocaleTagType tagType = wxLOCALE_TAGTYPE_DEFAULT) const;
|
|
|
|
/**
|
|
Check if the locale is empty.
|
|
|
|
@return @true if this is an empty, invalid object.
|
|
*/
|
|
bool IsEmpty() const;
|
|
};
|