Version: 3.2.5
wxLocaleIdent Class Reference

#include <wx/uilocale.h>

Detailed Description

Represents a locale in a portable way.

There are two possible ways to construct wxLocaleIdent:

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()
Default constructor creates an empty and invalid locale identifier.
#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!
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...
 
wxLocaleIdentLanguage (const wxString &language)
 Set language. More...
 
wxLocaleIdentRegion (const wxString &region)
 Set region. More...
 
wxLocaleIdentScript (const wxString &script)
 Set script. More...
 
wxLocaleIdentCharset (const wxString &charset)
 Set charset. More...
 
wxLocaleIdentModifier (const wxString &modifier)
 Set modifier. More...
 
wxLocaleIdentExtension (const wxString &extension)
 Set extension. More...
 
wxLocaleIdentSortorder (const wxString &sortorder)
 Set sortorder. More...
 
const wxStringGetLanguage () const
 Return the language part of the locale identifier. More...
 
const wxStringGetRegion () const
 Return the region part of the locale identifier. More...
 
const wxStringGetScript () const
 Return the script part of the locale identifier. More...
 
const wxStringGetCharset () const
 Return the charset part of the locale identifier. More...
 
const wxStringGetModifier () const
 Return the modifier part of the locale identifier. More...
 
const wxStringGetExtension () const
 Return the extension part of the locale identifier. More...
 
const wxStringGetSortorder () 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
charsetCharset 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
extensionExtension 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
tagTypeValue 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
languageA 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
modifierModifier is a free-form text string.

◆ Region()

wxLocaleIdent& wxLocaleIdent::Region ( const wxString region)

Set region.

Return reference to this for method chaining.

Parameters
regionIt 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
scriptIt 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
sortorderSortorder identifiers are defined in the Windows Development documentation: https://docs.microsoft.com/en-us/windows/win32/intl/sort-order-identifiers.