wxWidgets: wxLocaleIdent Class Reference

| Version: 3.2.7

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

`#include <wx/uilocale.h>`

## Detailed Description

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:

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
wxLocaleIdent::wxLocaleIdent
wxLocaleIdent()
Default constructor creates an empty and invalid locale identifier.
wxASSERT
#define wxASSERT(condition)
Assert macro.
Definition: debug.h:75

For the first way, it is enough to just write

auto loc = wxLocaleIdent::FromTag("fr-BE"); // Dash, not underscore!
wxLocaleIdent::FromTag
static wxLocaleIdent FromTag(const wxString &tag)
Return the locale identifier corresponding to the given locale tag.

Since
  3.1.6

## Public Member Functions
| wxLocaleIdent ()
| Default constructor creates an empty and invalid locale identifier. More...
wxLocaleIdent & | Language (const wxString &language)
| Set language. More...
wxLocaleIdent & | Region (const wxString &region)
| Set region. More...
wxLocaleIdent & | Script (const wxString &script)
| Set script. More...
wxLocaleIdent & | Charset (const wxString &charset)
| Set charset. More...
wxLocaleIdent & | Modifier (const wxString &modifier)
| Set modifier. More...
wxLocaleIdent & | Extension (const wxString &extension)
| Set extension. More...
wxLocaleIdent & | Sortorder (const wxString &sortorder)
| Set sortorder. More...
const wxString & | GetLanguage () const
| Return the language part of the locale identifier. More...
const wxString & | GetRegion () const
| Return the region part of the locale identifier. More...
const wxString & | GetScript () const
| Return the script part of the locale identifier. More...
const wxString & | GetCharset () const
| Return the charset part of the locale identifier. More...
const wxString & | GetModifier () const
| Return the modifier part of the locale identifier. More...
const wxString & | GetExtension () const
| Return the extension part of the locale identifier. More...
const wxString & | GetSortorder () const
| Return the sortorder part of the locale identifier. More...
wxString | GetName () const
| Construct platform dependent name. More...
wxString | GetTag (wxLocaleTagType tagType=wxLOCALE_TAGTYPE_DEFAULT) const
| Construct name in specified format. More...
bool | IsEmpty () const
| Check if the locale is empty. More...

## Static Public Member Functions
static wxLocaleIdent | FromTag (const wxString &tag)
| Return the locale identifier corresponding to the given locale tag. More...

## Constructor & Destructor Documentation

## ◆ wxLocaleIdent()

wxLocaleIdent::wxLocaleIdent | ( |  | ) |

Default constructor creates an empty and invalid locale identifier.

At least Language() must be called to make the identifier valid.

## Member Function Documentation

## ◆ Charset()

wxLocaleIdent& wxLocaleIdent::Charset | ( | const wxString & | charset | ) |

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.

Parameters

  charset | Charset is a string such as "UTF-8", "ISO855915" or "KOI8R". Supported charsets depend on the implementation and installation.

## ◆ Extension()

wxLocaleIdent& wxLocaleIdent::Extension | ( | const wxString & | extension | ) |

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.

Parameters

  extension | Extension identifiers allow to support custom Windows locales. They are usually not portable, not even from one Windows system to the other.

## ◆ FromTag()

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

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.

## ◆ GetCharset()

const wxString& wxLocaleIdent::GetCharset | ( |  | ) | const

Return the charset part of the locale identifier.

## ◆ GetExtension()

const wxString& wxLocaleIdent::GetExtension | ( |  | ) | const

Return the extension part of the locale identifier.

## ◆ GetLanguage()

const wxString& wxLocaleIdent::GetLanguage | ( |  | ) | const

Return the language part of the locale identifier.

## ◆ GetModifier()

const wxString& wxLocaleIdent::GetModifier | ( |  | ) | const

Return the modifier part of the locale identifier.

## ◆ GetName()

wxString wxLocaleIdent::GetName | ( |  | ) | const

Construct platform dependent name.

Format:

- Windows: <language>-<script>-<REGION>-<extension>_<sortorder>
- Unix: <language>_<REGION>.<charset>@{<modifier>|<scriptalias>}
- MacOS: <language>-<script>_<REGION>

## ◆ GetRegion()

const wxString& wxLocaleIdent::GetRegion | ( |  | ) | const

Return the region part of the locale identifier.

## ◆ GetScript()

const wxString& wxLocaleIdent::GetScript | ( |  | ) | const

Return the script part of the locale identifier.

## ◆ GetSortorder()

const wxString& wxLocaleIdent::GetSortorder | ( |  | ) | const

Return the sortorder part of the locale identifier.

## ◆ GetTag()

wxString wxLocaleIdent::GetTag | ( | wxLocaleTagType | tagType = `wxLOCALE_TAGTYPE_DEFAULT` | ) | 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>

Parameters

  tagType | Value from wxLocaleTagType enum.

## ◆ IsEmpty()

bool wxLocaleIdent::IsEmpty | ( |  | ) | const

Check if the locale is empty.

Returns
  true if this is an empty, invalid object.

## ◆ Language()

wxLocaleIdent& wxLocaleIdent::Language | ( | const wxString & | language | ) |

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.

Parameters

  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.

## ◆ Modifier()

wxLocaleIdent& wxLocaleIdent::Modifier | ( | const wxString & | modifier | ) |

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.

Parameters

  modifier | Modifier is a free-form text string.

## ◆ Region()

wxLocaleIdent& wxLocaleIdent::Region | ( | const wxString & | region | ) |

Set region.

Return reference to `this` for method chaining.

Parameters

  region | It specifies an uppercase ISO 3166-1 country/region identifier.

## ◆ Script()

wxLocaleIdent& wxLocaleIdent::Script | ( | const wxString & | script | ) |

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.

Parameters

  script | It is an initial-uppercase ISO 15924 script code.

## ◆ Sortorder()

wxLocaleIdent& wxLocaleIdent::Sortorder | ( | const wxString & | sortorder | ) |

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.

Parameters

  sortorder | Sortorder identifiers are defined in the Windows Development documentation: https://docs.microsoft.com/en-us/windows/win32/intl/sort-order-identifiers.