wxLocale class encapsulates all language-dependent settings and is a
generalization of the C locale concept.
-In wxWindows this class manages message catalogs which contain the translations
+In wxWidgets this class manages message catalogs which contain the translations
of the strings used to the current language.
\perlnote{In wxPerl you can't use the '\_' function name, so
the {\tt Wx::Locale} module can export the {\tt gettext} and
{\tt gettext\_noop} under any given name.
+
\begin{verbatim}
# this imports gettext ( equivalent to Wx::GetTranslation
# and gettext_noop ( a noop )
button = Wx::Button->new( window, -1, gettext( ``Label'' ) );
\end{verbatim}
+
If you need to translate a lot of strings, then adding gettext( ) around
each one is a long task ( that is why \_( ) was introduced ), so just choose
a shorter name for gettext:
+
\begin{verbatim}
#
use Wx::Locale 'gettext' => 't',
# ...
\end{verbatim}
-}
+}%
\wxheading{Derived from}
\latexignore{\rtfignore{\wxheading{Members}}}
+
\membersection{Supported languages}\label{wxlanguage}
The following wxLanguage constants may be used to specify the language
+
\membersection{wxLocale::wxLocale}\label{wxlocaledefctor}
\func{}{wxLocale}{\void}
translate the messages using the message catalogs for this locale.
+
\membersection{wxLocale::\destruct{wxLocale}}\label{wxlocaledtor}
\func{}{\destruct{wxLocale}}{\void}
set locale is restored and so the changes described in
\helpref{Init}{wxlocaleinit} documentation are rolled back.
+
\membersection{wxLocale::AddCatalog}\label{wxlocaleaddcatalog}
\func{bool}{AddCatalog}{\param{const char }{*szDomain}}
+\func{bool}{AddCatalog}{\param{const char }{*szDomain}, \param{wxLanguage}{msgIdLanguage}, \param{const char }{*msgIdCharset}}
+
Add a catalog for use with the current locale: it is searched for in standard
places (current directory first, then the system one), but you may also prepend
additional directories to the search path with
\helpref{AddCatalogLookupPathPrefix()}{wxlocaleaddcataloglookuppathprefix}.
-All loaded catalogs will be used for message lookup by GetString() for the
-current locale.
+All loaded catalogs will be used for message lookup by
+\helpref{GetString()}{wxlocalegetstring} for the current locale.
Returns true if catalog was successfully loaded, false otherwise (which might
mean that the catalog is not found or that it isn't in the correct format).
+The second form of this method takes two additional arguments,
+\arg{msgIdLanguage} and \arg{msgIdCharset}.
+
+\arg{msgIdLanguage} specifies the language of "msgid" strings in source code
+(i.e. arguments to \helpref{GetString}{wxlocalegetstring},
+\helpref{wxGetTranslation}{wxgettranslation} and the
+\helpref{\_()}{underscore} macro). It is used if AddCatalog cannot find any
+catalog for current language: if the language is same as source code language,
+then strings from source code are used instead.
+
+\arg{msgIdCharset} lets you specify the charset used for msgids in sources
+in case they use 8-bit characters (e.g. German or French strings). This
+argument has no effect in Unicode build, because literals in sources are
+Unicode strings; you have to use compiler-specific method of setting the right
+charset when compiling with Unicode.
+
+By default (i.e. when you use the first form), msgid strings are assumed
+to be in English and written only using 7-bit ASCII characters.
+
+If you have to deal with non-English strings or 8-bit characters in the source
+code, see the instructions in
+\helpref{Writing non-English applications}{nonenglishoverview}.
+
+
\membersection{wxLocale::AddCatalogLookupPathPrefix}\label{wxlocaleaddcataloglookuppathprefix}
\func{void}{AddCatalogLookupPathPrefix}{\param{const wxString\& }{prefix}}
This only applies to subsequent invocations of AddCatalog()!
+
\membersection{wxLocale::AddLanguage}\label{wxlocaleaddlanguage}
\func{static void}{AddLanguage}{\param{const wxLanguageInfo\& }{info}}
\perlnote{In wxPerl Wx::LanguageInfo has only one method:\par
Wx::LanguageInfo->new( language, canonicalName, WinLang, WinSubLang, Description )}
+
\membersection{wxLocale::FindLanguageInfo}{wxlocalefindlanguageinfo}
\constfunc{static wxLanguageInfo *}{FindLanguageInfo}{\param{const wxString\& }{locale}}
\helpref{GetLanguageInfo}{wxlocalegetlanguageinfo}
+
\membersection{wxLocale::GetCanonicalName}\label{wxlocalegetcanonicalname}
\constfunc{wxString}{GetSysName}{\void}
+
\membersection{wxLocale::GetLanguage}\label{wxlocalegetlanguage}
\constfunc{int}{GetLanguage}{\void}
Note that you can call this function only if you used the form of
\helpref{Init}{wxlocaleinit} that takes wxLanguage argument.
+
\membersection{wxLocale::GetLanguageInfo}\label{wxlocalegetlanguageinfo}
\constfunc{static wxLanguageInfo *}{GetLanguageInfo}{\param{int }{lang}}
See \helpref{AddLanguage}{wxlocaleaddlanguage} for the wxLanguageInfo
description.
+As with \helpref{Init}{wxlocaleinit}, \texttt{wxLANGUAGE\_DEFAULT} has the
+special meaning if passed as an argument to this function and in this case the
+result of \helpref{GetSystemLanguage()}{wxlocalegetsystemlanguage} is used.
+
+
\membersection{wxLocale::GetLanguageName}\label{wxlocalegetlanguagename}
\constfunc{static wxString}{GetLanguageName}{\param{int }{lang}}
Returns English name of the given language or empty string if this
language is unknown.
+See \helpref{GetLanguageInfo}{wxlocalegetlanguageinfo} for a remark about
+special meaning of \texttt{wxLANGUAGE\_DEFAULT}.
+
\membersection{wxLocale::GetLocale}\label{wxlocalegetlocale}
e.g. "English" or "French".
+
\membersection{wxLocale::GetName}\label{wxlocalegetname}
\constfunc{const wxString\&}{GetName}{\void}
Returns the current short name for the locale (as given to the constructor or
the Init() function).
+
\membersection{wxLocale::GetString}\label{wxlocalegetstring}
\constfunc{const char*}{GetString}{\param{const char }{*szOrigString}, \param{const char }{*szDomain = NULL}}
The second form is used when retrieving translation of string that has
different singular and plural form in English or different plural forms in some
-other language. \arg{szOrigString2} is plural form of the string in English and
-\arg{n} is used to determine the plural form.
+other language. It takes two extra arguments: \arg{szOrigString}
+parameter must contain the singular form of the string to be converted.
+It is also used as the key for the search in the catalog.
+The \arg{szOrigString2} parameter is the plural form (in English).
+The parameter \arg{n} is used to determine the plural form. If no
+message catalog is found \arg{szOrigString} is returned if `n == 1',
+otherwise \arg{szOrigString2}.
+See \urlref{GNU gettext manual}{http://www.gnu.org/manual/gettext/html\_chapter/gettext\_10.html\#SEC150} for additional information on plural forms handling.
+
+This method is called by the \helpref{wxGetTranslation}{wxgettranslation}
+function and \helpref{\_()}{underscore} macro.
\wxheading{Remarks}
Domains are searched in the last to first order, i.e. catalogs
added later override those added before.
+
+\membersection{wxLocale::GetHeaderValue}\label{wxlocalegetheadervalue}
+
+\constfunc{wxString}{GetHeaderValue}{\param{const char }{*szHeader}, \param{const char }{*szDomain = NULL}}
+
+Returns the header value for header \arg{szHeader}. The search for \arg{szHeader} is case sensitive. If an \arg{szDomain}
+is passed, this domain is searched. Else all domains will be searched until a header has been found.
+The return value is the value of the header if found. Else this will be empty.
+
\membersection{wxLocale::GetSysName}\label{wxlocalegetsysname}
\constfunc{wxString}{GetSysName}{\void}
Compare \helpref{GetCanonicalName}{wxlocalegetcanonicalname}.
+
\membersection{wxLocale::GetSystemEncoding}\label{wxlocalegetsystemencoding}
\constfunc{static wxFontEncoding}{GetSystemEncoding}{\void}
Returns \helpref{wxFontEncoding}{wxfont} value or
{\bf wxFONTENCODING\_SYSTEM} if it couldn't be determined.
+
\membersection{wxLocale::GetSystemEncodingName}\label{wxlocalegetsystemencodingname}
\constfunc{static wxString}{GetSystemEncodingName}{\void}
Returns a user-readable string value or an empty string if it couldn't be
determined.
+
\membersection{wxLocale::GetSystemLanguage}\label{wxlocalegetsystemlanguage}
\constfunc{static int}{GetSystemLanguage}{\void}
{\bf wxLANGUAGE\_UNKNOWN} if the language-guessing algorithm failed.
+
\membersection{wxLocale::Init}\label{wxlocaleinit}
language (see \helpref{GetSystemLanguage}{wxlocalegetsystemlanguage}).}
\docparam{flags}{Combination of the following:
+
+
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxLOCALE\_LOAD\_DEFAULT}}{Load the message catalog
-for the given locale containing the translations of standard wxWindows messages
+for the given locale containing the translations of standard wxWidgets messages
automatically.}
\twocolitem{\windowstyle{wxLOCALE\_CONV\_ENCODING}}{Automatically convert message
catalogs to platform's default encoding. Note that it will do only basic
platform-specific.}
\docparam{bLoadDefault}{May be set to false to prevent loading of the message catalog
-for the given locale containing the translations of standard wxWindows messages.
+for the given locale containing the translations of standard wxWidgets messages.
This parameter would be rarely used in normal circumstances.}
\docparam{bConvertEncoding}{May be set to true to do automatic conversion of message
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 wxLocale object becomes the new current global locale for the
-application and so all subsequent calls to wxGetTranslation() will try to
+application and so all subsequent calls to
+\helpref{wxGetTranslation()}{wxgettranslation} will try to
translate the messages using the message catalogs for this locale.
Returns true on success or false if the given locale couldn't be set.
+
\membersection{wxLocale::IsLoaded}\label{wxlocaleisloaded}
\constfunc{bool}{IsLoaded}{\param{const char* }{domain}}
See also: \helpref{AddCatalog}{wxlocaleaddcatalog}
+
\membersection{wxLocale::IsOk}\label{wxlocaleisok}
\constfunc{bool}{IsOk}{\void}
projects / wxWidgets.git / blobdiff