.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2018 by Total Control Software
License: wxWindows License
.. include:: headings.inc
.. _wx.Locale:
==========================================================================================================================================
|phoenix_title| **wx.Locale**
==========================================================================================================================================
:ref:`wx.Locale` class encapsulates all language-dependent settings and is a generalization of the C locale concept.
In wxWidgets this class manages current locale. It also initializes and activates :ref:`wx.Translations` object that manages message catalogs.
For a list of the supported languages, please see :ref:`wx.Language` enum values. These constants may be used to specify the language in :meth:`wx.Locale.Init` and are returned by :meth:`wx.Locale.GetSystemLanguage` .
|
|class_hierarchy| Class Hierarchy
=================================
.. raw:: html
<div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
<img id="toggleBlock-trigger" src="_static/images/closed.png"/>
Inheritance diagram for class <strong>Locale</strong>:
</div>
<div id="toggleBlock-summary" style="display:block;"></div>
<div id="toggleBlock-content" style="display:none;">
<p class="graphviz">
<center><img src="_static/images/inheritance/wx.Locale_inheritance.png" alt="Inheritance diagram of Locale" usemap="#dummy" class="inheritance"/></center>
<script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
<map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Locale.html" title="wx.Locale class encapsulates all language-dependent settings and is a generalization of the C locale concept." alt="" coords="5,5,93,35"/> </map>
</p>
</div>
|
|method_summary| Methods Summary
================================
================================================================================ ================================================================================
:meth:`~wx.Locale.__init__` This is the default constructor and it does nothing to initialize the object: :meth:`~Locale.Init` must be used to do that.
:meth:`~wx.Locale.AddCatalog` Calls :meth:`wx.Translations.AddCatalog` .
:meth:`~wx.Locale.AddCatalogLookupPathPrefix` Calls :meth:`wx.FileTranslationsLoader.AddCatalogLookupPathPrefix` .
:meth:`~wx.Locale.AddLanguage` Adds custom, user-defined language to the database of known languages.
:meth:`~wx.Locale.FindLanguageInfo` 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").
:meth:`~wx.Locale.GetCanonicalName` Returns the canonical form of current locale name.
:meth:`~wx.Locale.GetHeaderValue` Calls :meth:`wx.Translations.GetHeaderValue` .
:meth:`~wx.Locale.GetInfo` Get the values of the given locale-dependent datum.
:meth:`~wx.Locale.GetLanguage` Returns the :ref:`wx.Language` constant of current language.
:meth:`~wx.Locale.GetLanguageCanonicalName` Returns canonical name (see :meth:`~Locale.GetCanonicalName` ) of the given language or empty string if this language is unknown.
:meth:`~wx.Locale.GetLanguageInfo` Returns a pointer to :ref:`wx.LanguageInfo` structure containing information about the given language or ``None`` if this language is unknown.
:meth:`~wx.Locale.GetLanguageName` Returns English name of the given language or empty string if this language is unknown.
:meth:`~wx.Locale.GetLocale` Returns the locale name as passed to the constructor or :meth:`~Locale.Init` .
:meth:`~wx.Locale.GetName` Returns the current short name for the locale (as given to the constructor or the :meth:`~Locale.Init` function).
:meth:`~wx.Locale.GetString` Calls `wx.GetTranslation` .
:meth:`~wx.Locale.GetSysName` Returns current platform-specific locale name as passed to setlocale().
:meth:`~wx.Locale.GetSystemEncoding` Tries to detect the user's default font encoding.
:meth:`~wx.Locale.GetSystemEncodingName` Tries to detect the name of the user's default font encoding.
:meth:`~wx.Locale.GetSystemLanguage` Tries to detect the user's default locale setting.
:meth:`~wx.Locale.Init` Initializes the :ref:`wx.Locale` instance.
:meth:`~wx.Locale.IsAvailable` Check whether the operating system and/or C run time environment supports this locale.
:meth:`~wx.Locale.IsLoaded` Calls :meth:`wx.Translations.IsLoaded` .
:meth:`~wx.Locale.IsOk` Returns ``True`` if the locale could be set successfully.
:meth:`~wx.Locale.__bool__`
:meth:`~wx.Locale.__nonzero__`
================================================================================ ================================================================================
|
|property_summary| Properties Summary
=====================================
================================================================================ ================================================================================
:attr:`~wx.Locale.CanonicalName` See :meth:`~wx.Locale.GetCanonicalName`
:attr:`~wx.Locale.Language` See :meth:`~wx.Locale.GetLanguage`
:attr:`~wx.Locale.Locale` See :meth:`~wx.Locale.GetLocale`
:attr:`~wx.Locale.Name` See :meth:`~wx.Locale.GetName`
:attr:`~wx.Locale.SysName` See :meth:`~wx.Locale.GetSysName`
================================================================================ ================================================================================
|
|api| Class API
===============
.. class:: wx.Locale(object)
**Possible constructors**::
Locale()
Locale(language, flags=LOCALE_LOAD_DEFAULT)
Locale(name, shortName="", locale="",
bLoadDefault=True)
Locale class encapsulates all language-dependent settings and is a
generalization of the C locale concept.
.. method:: __init__(self, *args, **kw)
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self)`
This is the default constructor and it does nothing to initialize the object: :meth:`Init` must be used to do that.
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self, language, flags=LOCALE_LOAD_DEFAULT)`
See :meth:`Init` for parameters description.
:param `language`:
:type `language`: int
:param `flags`:
:type `flags`: int
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self, name, shortName="", locale="", bLoadDefault=True)`
See :meth:`Init` for parameters description.
The call of this function has several global side effects which you should understand: first of all, the application locale is changed - note that this will affect many of standard C library functions such as printf() or strftime(). Second, this :ref:`wx.Locale` object becomes the new current global locale for the application and so all subsequent calls to `wx.GetTranslation` will try to translate the messages using the message catalogs for this locale.
:param `name`:
:type `name`: string
:param `shortName`:
:type `shortName`: string
:param `locale`:
:type `locale`: string
:param `bLoadDefault`:
:type `bLoadDefault`: bool
:html:`<hr class="overloadsep" /><br />`
.. method:: AddCatalog(self, *args, **kw)
Calls :meth:`wx.Translations.AddCatalog` .
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**AddCatalog** `(self, domain)`
:param `domain`:
:type `domain`: string
:rtype: `bool`
:html:`<hr class="overloadsep" /><br />`
**AddCatalog** `(self, domain, msgIdLanguage)`
:param `domain`:
:type `domain`: string
:param `msgIdLanguage`:
:type `msgIdLanguage`: wx.Language
:rtype: `bool`
:html:`<hr class="overloadsep" /><br />`
**AddCatalog** `(self, domain, msgIdLanguage, msgIdCharset)`
:param `domain`:
:type `domain`: string
:param `msgIdLanguage`:
:type `msgIdLanguage`: wx.Language
:param `msgIdCharset`:
:type `msgIdCharset`: string
:rtype: `bool`
:html:`<hr class="overloadsep" /><br />`
.. staticmethod:: AddCatalogLookupPathPrefix(prefix)
Calls :meth:`wx.FileTranslationsLoader.AddCatalogLookupPathPrefix` .
:param `prefix`:
:type `prefix`: string
.. staticmethod:: AddLanguage(info)
Adds custom, user-defined language to the database of known languages.
This database is used in conjunction with the first form of :meth:`Init` .
:param `info`:
:type `info`: wx.LanguageInfo
.. staticmethod:: FindLanguageInfo(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").
Returns the information for the given language or ``None`` if this language is unknown. Note that even if the returned pointer is valid, the caller should `not` delete it.
:param `locale`:
:type `locale`: string
:rtype: :ref:`wx.LanguageInfo`
.. seealso:: :meth:`GetLanguageInfo`
.. method:: GetCanonicalName(self)
Returns the canonical form of current locale name.
Canonical form is the one that is used on ``UNIX`` systems: it is a two- or five-letter string in xx or xx_YY format, where xx is ``ISO`` 639 code of language and ``YY`` is ``ISO`` 3166 code of the country. Examples are "en", "en_GB", "en_US" or "fr_FR". This form is internally used when looking up message catalogs. Compare :meth:`GetSysName` .
:rtype: `string`
.. method:: GetHeaderValue(self, header, domain="")
Calls :meth:`wx.Translations.GetHeaderValue` .
:param `header`:
:type `header`: string
:param `domain`:
:type `domain`: string
:rtype: `string`
.. staticmethod:: GetInfo(index, cat=LOCALE_CAT_DEFAULT)
Get the values of the given locale-dependent datum.
This function returns the value of the locale-specific option specified by the given `index`.
:param `index`: One of the elements of LocaleInfo enum.
:type `index`: wx.LocaleInfo
:param `cat`: The category to use with the given index or ``wx.LOCALE_CAT_DEFAULT`` if the index can only apply to a single category.
:type `cat`: wx.LocaleCategory
:rtype: `string`
:returns:
The option value or empty string if the function failed.
.. method:: GetLanguage(self)
Returns the :ref:`wx.Language` constant of current language.
Note that you can call this function only if you used the form of :meth:`Init` that takes :ref:`wx.Language` argument.
:rtype: `int`
.. staticmethod:: GetLanguageCanonicalName(lang)
Returns canonical name (see :meth:`GetCanonicalName` ) of the given language or empty string if this language is unknown.
See :meth:`GetLanguageInfo` for a remark about special meaning of ``LANGUAGE_DEFAULT`` .
:param `lang`:
:type `lang`: int
:rtype: `string`
.. versionadded:: 2.9.1
.. staticmethod:: GetLanguageInfo(lang)
Returns a pointer to :ref:`wx.LanguageInfo` structure containing information about the given language or ``None`` if this language is unknown.
Note that even if the returned pointer is valid, the caller should `not` delete it.
See :meth:`AddLanguage` for the :ref:`wx.LanguageInfo` description. As with :meth:`Init` , ``LANGUAGE_DEFAULT`` has the special meaning if passed as an argument to this function and in this case the result of :meth:`GetSystemLanguage` is used.
:param `lang`:
:type `lang`: int
:rtype: :ref:`wx.LanguageInfo`
.. staticmethod:: GetLanguageName(lang)
Returns English name of the given language or empty string if this language is unknown.
See :meth:`GetLanguageInfo` for a remark about special meaning of ``LANGUAGE_DEFAULT`` .
:param `lang`:
:type `lang`: int
:rtype: `string`
.. method:: GetLocale(self)
Returns the locale name as passed to the constructor or :meth:`Init` .
This is a full, human-readable name, e.g. "English" or "French".
:rtype: `string`
.. method:: GetName(self)
Returns the current short name for the locale (as given to the constructor or the :meth:`Init` function).
:rtype: `string`
.. method:: GetString(self, *args, **kw)
Calls `wx.GetTranslation` .
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**GetString** `(self, origString, domain="")`
:param `origString`:
:type `origString`: string
:param `domain`:
:type `domain`: string
:rtype: `string`
:html:`<hr class="overloadsep" /><br />`
**GetString** `(self, origString, origString2, n, domain="")`
:param `origString`:
:type `origString`: string
:param `origString2`:
:type `origString2`: string
:param `n`:
:param `domain`:
:type `domain`: string
:rtype: `string`
:html:`<hr class="overloadsep" /><br />`
.. method:: GetSysName(self)
Returns current platform-specific locale name as passed to setlocale().
Compare :meth:`GetCanonicalName` .
:rtype: `string`
.. staticmethod:: GetSystemEncoding()
Tries to detect the user's default font encoding.
Returns :ref:`wx.FontEncoding` value or ``FONTENCODING_SYSTEM`` if it couldn't be determined.
:rtype: :ref:`wx.FontEncoding`
.. staticmethod:: GetSystemEncodingName()
Tries to detect the name of the user's default font encoding.
This string isn't particularly useful for the application as its form is platform-dependent and so you should probably use :meth:`GetSystemEncoding` instead.
Returns a user-readable string value or an empty string if it couldn't be determined.
:rtype: `string`
.. staticmethod:: GetSystemLanguage()
Tries to detect the user's default locale setting.
Returns the :ref:`wx.Language` value or ``LANGUAGE_UNKNOWN`` if the language-guessing algorithm failed.
:rtype: `int`
.. 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 Translation to obtain `language` information.
.. seealso:: :meth:`wx.Translations.GetBestTranslation` .
.. method:: Init(self, *args, **kw)
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**Init** `(self, language=LANGUAGE_DEFAULT, flags=LOCALE_LOAD_DEFAULT)`
Initializes the :ref:`wx.Locale` instance.
The call of this function has several global side effects which you should understand: first of all, the application locale is changed - note that this will affect many of standard C library functions such as printf() or strftime(). Second, this :ref:`wx.Locale` object becomes the new current global locale for the application and so all subsequent calls to `wx.GetTranslation` will try to translate the messages using the message catalogs for this locale.
:param `language`: :ref:`wx.Language` identifier of the locale. ``LANGUAGE_DEFAULT`` has special meaning :ref:`wx.Locale` will use system's default language (see :meth:`GetSystemLanguage` ).
:type `language`: int
:param `flags`: Combination of the following:
- ``wx.LOCALE_LOAD_DEFAULT``: Load the message catalog for the given locale containing the translations of standard wxWidgets messages automatically.
- ``wx.LOCALE_DONT_LOAD_DEFAULT``: Negation of ``wx.LOCALE_LOAD_DEFAULT``.
:type `flags`: int
:rtype: `bool`
:returns:
``True`` on success or ``False`` if the given locale couldn't be set.
:html:`<hr class="overloadsep" /><br />`
**Init** `(self, name, shortName="", locale="", bLoadDefault=True)`
:param `name`: The name of the locale. Only used in diagnostic messages.
:type `name`: string
:param `shortName`: The standard 2 letter locale abbreviation; it is used as the directory prefix when looking for the message catalog files.
:type `shortName`: string
:param `locale`: The parameter for the call to setlocale(). Note that it is platform-specific.
:type `locale`: string
:param `bLoadDefault`: May be set to ``False`` to prevent loading of the message catalog for the given locale containing the translations of standard wxWidgets messages. This parameter would be rarely used in normal circumstances.
:type `bLoadDefault`: bool
:rtype: `bool`
.. wxdeprecated::
This form is deprecated, use the other one unless you know what you are doing.
:html:`<hr class="overloadsep" /><br />`
.. staticmethod:: IsAvailable(lang)
Check whether the operating system and/or C run time environment supports this locale.
For example in Windows 2000 and Windows XP, support for many locales is not installed by default. Returns ``True`` if the locale is supported.
The argument `lang` is the :ref:`wx.Language` identifier. To obtain this for a given a two letter ``ISO`` language code, use :meth:`FindLanguageInfo` to obtain its :ref:`wx.LanguageInfo` structure. See :meth:`AddLanguage` for the :ref:`wx.LanguageInfo` description.
:param `lang`:
:type `lang`: int
:rtype: `bool`
.. versionadded:: 2.7.1.
.. method:: IsLoaded(self, domain)
Calls :meth:`wx.Translations.IsLoaded` .
:param `domain`:
:type `domain`: string
:rtype: `bool`
.. method:: IsOk(self)
Returns ``True`` if the locale could be set successfully.
:rtype: `bool`
.. method:: __bool__(self)
:rtype: `int`
.. method:: __nonzero__(self)
:rtype: `int`
.. attribute:: CanonicalName
See :meth:`~wx.Locale.GetCanonicalName`
.. attribute:: Language
See :meth:`~wx.Locale.GetLanguage`
.. attribute:: Locale
See :meth:`~wx.Locale.GetLocale`
.. attribute:: Name
See :meth:`~wx.Locale.GetName`
.. attribute:: SysName
See :meth:`~wx.Locale.GetSysName`