| Version: 3.3.1

Public Member Functions | Static Public Member Functions | List of all members
wxUILocale Class Reference

`#include <wx/uilocale.h>`

## Detailed Description

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 `setlocale()` function and affecting C standard library functions such as `printf()`, `scanf()`, `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.

To set the C runtime functions (e.g., `strtod()`) to use the user's locale consistently on all platforms, a wxLocale object should be created and initialized with `wxLANGUAGE_DEFAULT`. This is not recommended due to various side effects, but can be done for applications which rely on these functions. (Note that this should be done in conjunction with calling wxUILocale::UseDefault().)

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 `Info.plist` file under `CFBundleLocalizations` key.

Unlike the wxLocale class, this class doesn't affect the translations used by the application, see wxTranslations for doing this.

##

Library: wxBase

Since
  3.1.6

## Public Member Functions
| wxUILocale (const wxLocaleIdent &localeId)
| Creates the locale corresponding to the given locale identifier. More...
int | CompareStrings (const wxString &lhs, const wxString &rhs, int flags=wxCompare_CaseSensitive) const
| Compares two strings using comparison rules of this locale. More...
wxString | GetName () const
| Get the platform-dependent name of the current locale. More...
wxLocaleIdent | GetLocaleId () const
| Get the locale id from which the current locale was instantiated. More...
wxString | GetInfo (wxLocaleInfo index, wxLocaleCategory cat=wxLOCALE_CAT_DEFAULT) const
| Query the locale for the specified information. More...
wxString | GetLocalizedName (wxLocaleName name, wxLocaleForm form) const
| Query the locale for the specified localized name. More...
wxString | GetMonthName (wxDateTime::Month month, wxDateTime::NameForm form={})
| Gets the full (default), abbreviated or shortest name of the given month. More...
wxString | GetWeekDayName (wxDateTime::WeekDay weekday, wxDateTime::NameForm form={})
| Gets the full (default), abbreviated or shortest name of the given week day. More...
wxLayoutDirection | GetLayoutDirection () const
| Query the layout direction of the current locale. More...
bool | IsSupported () const
| Return true if locale is supported on the current system. More...

## Static Public Member Functions
static bool | UseDefault ()
| Configure the UI to use the default user locale. More...
static bool | IsSet ()
| Return true if the locale was set by calling either UseDefault() or UseLocaleName(). More...
static const wxUILocale & | GetCurrent ()
| Get the object corresponding to the currently used locale. More...
static bool | UseLocaleName (const wxString &localeName)
| Configure the UI to use the locale corresponding to the given locale name tag. More...
static wxUILocale | FromTag (const wxString &tag)
| Creates the local corresponding to the given language tag. More...
static void | AddLanguage (const wxLanguageInfo &info)
| Adds custom, user-defined language to the database of known languages. More...
static const wxLanguageInfo * | FindLanguageInfo (const wxString &locale)
| 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"). More...
static const wxLanguageInfo * | FindLanguageInfo (const wxLocaleIdent &localeId)
| This function may be used to find the language description structure for the given locale, specified as a locale identifier. More...
static const wxLanguageInfo * | GetLanguageInfo (int lang)
| Returns a pointer to wxLanguageInfo structure containing information about the given language or nullptr if this language is unknown. More...
static wxVector< wxString > | GetPreferredUILanguages ()
| Tries to retrieve a list of the user's (or OS's) preferred UI languages. More...
static wxString | GetLanguageName (int lang)
| Returns English name of the given language or empty string if this language is unknown. More...
static wxString | GetLanguageCanonicalName (int lang)
| Returns canonical name of the given language or empty string if this language is unknown. More...
static int | GetSystemLanguage ()
| Tries to detect the user's default user interface language setting. More...
static int | GetSystemLocale ()
| Tries to detect the user's default locale setting. More...
static wxLocaleIdent | GetSystemLocaleId ()
| Return the description of the default system locale. More...

## Constructor & Destructor Documentation

## ◆ wxUILocale()

wxUILocale::wxUILocale | ( | const wxLocaleIdent & | localeId | ) |
| explicit

Creates the locale corresponding to the given locale identifier.

In the simplest case, this can be used as following:

const wxUILocale loc(wxLocaleIdent().Language("fr"));
wxLocaleIdent
Represents a locale in a portable way.
Definition: uilocale.h:476
wxUILocale
Query and modify locale used for the UI by the current platform.
Definition: uilocale.h:78

see wxLocaleIdent description for more details, including other ways of specifying the locale.

If localeId is not recognized or not supported, default ("C") locale is used instead. Additionally, if localeId is empty (see wxLocaleIdent::IsEmpty()), an assertion failure is triggered.

## Member Function Documentation

## ◆ AddLanguage()

static void wxUILocale::AddLanguage | ( | const wxLanguageInfo & | info | ) |
| static

Adds custom, user-defined language to the database of known languages.

## ◆ CompareStrings()

int wxUILocale::CompareStrings | ( | const wxString & | lhs,
|  | const wxString & | rhs,
|  | int | flags = `wxCompare_CaseSensitive`
| ) |  | const

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.

Parameters

  lhs | First comparing string.
  rhs | Second comparing string.
  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).

Returns
  -1 if lhs is less than rhs. 0 if lhs is equal to rhs. 1 if lhs is greater than rhs.

## ◆ FindLanguageInfo() [1/2]

static const wxLanguageInfo* wxUILocale::FindLanguageInfo | ( | const wxLocaleIdent & | localeId | ) |
| static

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 nullptr if this language is unknown. Note that even if the returned pointer is valid, the caller should not delete it.

See also
  GetLanguageInfo()

## ◆ FindLanguageInfo() [2/2]

static const wxLanguageInfo* wxUILocale::FindLanguageInfo | ( | const wxString & | locale | ) |
| static

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 nullptr if this language is unknown. Note that even if the returned pointer is valid, the caller should not delete it.

See also
  GetLanguageInfo()

## ◆ FromTag()

static wxUILocale wxUILocale::FromTag | ( | const wxString & | tag | ) |
| static

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 tag string.

## ◆ GetCurrent()

static const wxUILocale& wxUILocale::GetCurrent | ( |  | ) |
| static

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.

## ◆ GetInfo()

wxString wxUILocale::GetInfo | ( | wxLocaleInfo | index,
|  | wxLocaleCategory | cat = `wxLOCALE_CAT_DEFAULT`
| ) |  | const

Query the locale for the specified information.

This function returns the value of the locale-specific option specified by the given index.

Parameters

  index | One of the elements of wxLocaleInfo enum.
  cat | The category to use with the given index or wxLOCALE_CAT_DEFAULT if the index can only apply to a single category.

Returns
  The option value or empty string if the function failed.

## ◆ GetLanguageCanonicalName()

static wxString wxUILocale::GetLanguageCanonicalName | ( | int | lang | ) |
| static

Returns canonical name of the given language or empty string if this language is unknown.

See GetLanguageInfo() for a remark about special meaning of `wxLANGUAGE_DEFAULT`.

## ◆ GetLanguageInfo()

static const wxLanguageInfo* wxUILocale::GetLanguageInfo | ( | int | lang | ) |
| static

Returns a pointer to wxLanguageInfo structure containing information about the given language or nullptr if this language is unknown.

Note that even if the returned pointer is valid, the caller should not delete it.

See AddLanguage() for the wxLanguageInfo description. As with Init(), `wxLANGUAGE_DEFAULT` has the special meaning if passed as an argument to this function and in this case the result of GetSystemLanguage() is used.

## ◆ GetLanguageName()

static wxString wxUILocale::GetLanguageName | ( | int | lang | ) |
| static

Returns English name of the given language or empty string if this language is unknown.

See GetLanguageInfo() for a remark about special meaning of `wxLANGUAGE_DEFAULT`.

## ◆ GetLayoutDirection()

wxLayoutDirection wxUILocale::GetLayoutDirection | ( |  | ) | const

Query the layout direction of the current locale.

Returns
  The layout direction or wxLayout_Default if the function failed.

## ◆ GetLocaleId()

wxLocaleIdent wxUILocale::GetLocaleId | ( |  | ) | const

Get the locale id from which the current locale was instantiated.

## ◆ GetLocalizedName()

wxString wxUILocale::GetLocalizedName | ( | wxLocaleName | name,
|  | wxLocaleForm | form
| ) |  | const

Query the locale for the specified localized name.

Parameters

  name | One of the elements of wxLocaleName enum.
  form | The representation form requested.

Returns
  The localized name value or empty string if the function failed.

## ◆ GetMonthName()

wxString wxUILocale::GetMonthName | ( | wxDateTime::Month | month,
|  | wxDateTime::NameForm | form = `{}`
| ) |  |

Gets the full (default), abbreviated or shortest name of the given month.

This function returns the name in the current locale, use wxDateTime::GetEnglishMonthName() to get the untranslated name if necessary.

Parameters

  month | One of wxDateTime::Jan, ..., wxDateTime::Dec values.
  form | Name form consisting of the flags (Name_Full, Name_Abbr, or Name_Shortest) and the context (Context_Formatting or Context_Standalone) The default is Name_Full in Context_Formatting. Example: wxNameForm().Abbr().Standalone()

See also
  GetWeekDayName()

Since
  3.3.0

## ◆ GetName()

wxString wxUILocale::GetName | ( |  | ) | const

Get the platform-dependent name of the current locale.

This name can be used in diagnostic messages.

## ◆ GetPreferredUILanguages()

static wxVector<wxString> wxUILocale::GetPreferredUILanguages | ( |  | ) |
| static

Tries to retrieve a list of the user's (or OS's) preferred UI languages.

Returns
  An empty list if language-guessing algorithm failed.

## ◆ GetSystemLanguage()

static int wxUILocale::GetSystemLanguage | ( |  | ) |
| static

Tries to detect the user's default user interface language setting.

Returns the wxLanguage value or `wxLANGUAGE_UNKNOWN` if the language-guessing algorithm failed.

Note
  Where possible this function returns the user's preferred UI 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 locale will be used.

See also
  wxTranslations::GetBestTranslation(), GetSystemLocaleId().

## ◆ GetSystemLocale()

static int wxUILocale::GetSystemLocale | ( |  | ) |
| static

Tries to detect the user's default locale setting.

Returns the wxLanguage value or `wxLANGUAGE_UNKNOWN` if the locale-guessing algorithm failed or if the locale can't be described using solely a language constant. Consider using GetSystemLocaleId() in this case.

Note
  This function works with 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 language information.

Since
  3.1.7

See also
  wxTranslations::GetBestTranslation().

## ◆ GetSystemLocaleId()

static wxLocaleIdent wxUILocale::GetSystemLocaleId | ( |  | ) |
| static

Return the description of the default system locale.

This function can always represent the system locale, even when using a language and region pair that doesn't correspond to any of the predefined wxLanguage constants, such as e.g. "fr-DE", which means French language used with German locale settings.

Since
  3.2.2

## ◆ GetWeekDayName()

wxString wxUILocale::GetWeekDayName | ( | wxDateTime::WeekDay | weekday,
|  | wxDateTime::NameForm | form = `{}`
| ) |  |

Gets the full (default), abbreviated or shortest name of the given week day.

This function returns the name in the current locale, use wxDateTime::GetEnglishWeekDayName() to get the untranslated name if necessary.

Parameters

  weekday | One of wxDateTime::Sun, ..., wxDateTime::Sat values.
  form | Name form consisting of the flags (Name_Full, Name_Abbr, or Name_Shortest) and the context (Context_Formatting or Context_Standalone) The default is Name_Full in Context_Formatting. Example: wxNameForm().Abbr().Standalone()

See also
  GetMonthName()

## ◆ IsSet()

static bool wxUILocale::IsSet | ( |  | ) |
| static

Return true if the locale was set by calling either UseDefault() or UseLocaleName().

It is typically not necessary to call this function, as GetCurrent() always returns a valid object, but it can be used to check whether an application-set locale or the default one is being used.

Since
  3.3.1

## ◆ IsSupported()

bool wxUILocale::IsSupported | ( |  | ) | const

Return true if locale is supported on the current system.

If this function returns 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.

## ◆ UseDefault()

static bool wxUILocale::UseDefault | ( |  | ) |
| static

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 `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.

Returns
  true on success or false if the default locale couldn't be set

## ◆ UseLocaleName()

static bool wxUILocale::UseLocaleName | ( | const wxString & | localeName | ) |
| static

Configure the UI to use the locale corresponding to the given locale name tag.

If localized applications use this function instead of the recommended function wxUILocale::UseDefault(), it should be called as early as possible during the program startup, e.g. in the very beginning of the overridden wxApp::OnInit().

Parameters

  localeName | The locale name tag for which the corresponding locale should be created. Example: "de_DE.UTF-8" - German locale name in POSIX notation. See wxLocaleIdent::FromTag() for more information about the syntax of the locale tag string.

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 `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.

Returns
  true on success or false if the locale with the given name couldn't be set

Note
  If an application tries to configure the UI to use a locale other than the default user locale of the system, it can't be guaranteed that really all controls will obey the locale setting. For example, under Windows the calendar control will always use the default user locale, no matter which locale was set by this function. Under MacOS several standard dialogs like the file selection dialog will use at least partially the default user locale.