]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/locale.tex
\\param -> \param
[wxWidgets.git] / docs / latex / wx / locale.tex
CommitLineData
c1b7dab0
VZ
1\section{\class{wxLocale}}\label{wxlocale}
2
dbdb39b2
JS
3wxLocale class encapsulates all language-dependent settings and is a
4generalization of the C locale concept.
c1b7dab0
VZ
5
6In wxWindows this class manages message catalogs which contain the translations
7of the strings used to the current language.
8
9\wxheading{Derived from}
10
11No base class
12
dbdb39b2
JS
13\wxheading{Include files}
14
15<wx/intl.h>
16
c1b7dab0
VZ
17\latexignore{\rtfignore{\wxheading{Members}}}
18
19\membersection{wxLocale::wxLocale}\label{wxlocaledefctor}
20
21\func{}{wxLocale}{\void}
22
23This is the default constructor and it does nothing to initialize the object:
dbdb39b2 24\helpref{Init()}{wxlocaleinit} must be used to do that.
c1b7dab0
VZ
25
26\func{}{wxLocale}{\param{const char }{*szName}, \param{const char }{*szShort = NULL}, \param{const char }{*szLocale = NULL}, \param{bool }{bLoadDefault = TRUE}}
27
28The parameters have the following meaning:
29\begin{itemize}\itemsep=0pt
30\item szName is the name of the locale and is only used in diagnostic messages
31\item szShort is the standard 2 letter locale abbreviation and is used as the
32directory prefix when looking for the message catalog files
33\item szLocale is the parameter for the call to setlocale()
34\item bLoadDefault may be set to FALSE to prevent loading of the message catalog
35for the given locale containing the translations of standard wxWindows messages.
36This parameter would be rarely used in normal circumstances.
37\end{itemize}
38
39The call of this function has several global side effects which you should
40understand: first of all, the application locale is changed - note that this
41will affect many of standard C library functions such as printf() or strftime().
42Second, this wxLocale object becomes the new current global locale for the
43application and so all subsequent calls to wxGetTranslation() will try to
44translate the messages using the message catalogs for this locale.
45
46\membersection{wxLocale::\destruct{wxLocale}}\label{wxlocaledtor}
47
48\func{}{\destruct{wxLocale}}{\void}
49
dbdb39b2 50The destructor, like the constructor, also has global side effects: the previously
c1b7dab0
VZ
51set locale is restored and so the changes described in
52\helpref{Init}{wxlocaleinit} documentation are rolled back.
53
54\membersection{wxLocale::GetLocale}\label{wxlocalegetlocale}
55
56\constfunc{const char*}{GetLocale}{\void}
57
58Returns the locale name as passed to the constructor or
59\helpref{Init()}{wxlocaleinit}.
60
c1b7dab0
VZ
61\membersection{wxLocale::AddCatalog}\label{wxlocaleaddcatalog}
62
63\func{bool}{AddCatalog}{\param{const char }{*szDomain}}
64
65Add a catalog for use with the current locale: it's searched for in standard
dbdb39b2 66places (current directory first, then the system one), but you may also prepend
c1b7dab0 67additional directories to the search path with
dbdb39b2 68\helpref{AddCatalogLookupPathPrefix()}{wxlocaleaddcataloglookuppathprefix}.
c1b7dab0
VZ
69
70All loaded catalogs will be used for message lookup by GetString() for the
71current locale.
72
73Returns TRUE if catalog was successfully loaded, FALSE otherwise (which might
74mean that the catalog is not found or that it isn't in the correct format).
75
76\membersection{wxLocale::AddCatalogLookupPathPrefix}\label{wxlocaleaddcataloglookuppathprefix}
77
78\func{void}{AddCatalogLookupPathPrefix}{\param{const wxString\& }{prefix}}
79
80Add a prefix to the catalog lookup path: the message catalog files will be
81looked up under prefix/<lang>/LC\_MESSAGES, prefix/LC\_MESSAGES and prefix
82(in this order).
83
84This only applies to subsequent invocations of AddCatalog()!
85
86\membersection{wxLocale::Init}\label{wxlocaleinit}
87
88\func{bool}{Init}{\param{const char }{*szName}, \param{const char }{*szShort = NULL}, \param{const char }{*szLocale = NULL}, \param{bool }{bLoadDefault = TRUE}}
89
90The parameters have the following meaning:
dbdb39b2 91
c1b7dab0
VZ
92\begin{itemize}\itemsep=0pt
93\item szName is the name of the locale and is only used in diagnostic messages
94\item szShort is the standard 2 letter locale abbreviation and is used as the
95directory prefix when looking for the message catalog files
96\item szLocale is the parameter for the call to setlocale()
97\item bLoadDefault may be set to FALSE to prevent loading of the message catalog
98for the given locale containing the translations of standard wxWindows messages.
99This parameter would be rarely used in normal circumstances.
100\end{itemize}
101
102The call of this function has several global side effects which you should
103understand: first of all, the application locale is changed - note that this
104will affect many of standard C library functions such as printf() or strftime().
105Second, this wxLocale object becomes the new current global locale for the
106application and so all subsequent calls to wxGetTranslation() will try to
107translate the messages using the message catalogs for this locale.
108
109Returns TRUE on success or FALSE if the given locale couldn't be set.
110
111\membersection{wxLocale::IsLoaded}\label{wxlocaleisloaded}
112
dbdb39b2
JS
113\constfunc{bool}{IsLoaded}{\param{const char* }{domain}}
114
115Check if the given catalog is loaded, and returns TRUE if it is.
c1b7dab0 116
dbdb39b2
JS
117According to GNU gettext tradition, each catalog
118normally corresponds to 'domain' which is more or less the application name.
c1b7dab0
VZ
119
120See also: \helpref{AddCatalog}{wxlocaleaddcatalog}
121
122\membersection{wxLocale::GetName}\label{wxlocalegetname}
123
124\constfunc{const wxString\&}{GetName}{\void}
125
126Returns the current short name for the locale (as given to the constructor or
127the Init() function).
128
129\membersection{wxLocale::GetString}\label{wxlocalegetstring}
130
131\constfunc{const char*}{GetString}{\param{const char }{*szOrigString}, \param{const char }{*szDomain = NULL}}
132
dbdb39b2 133Retrieves the translation for a string in all loaded domains unless the szDomain
c1b7dab0
VZ
134parameter is specified (and then only this catalog/domain is searched).
135
136Returns original string if translation is not available
137(in this case an error message is generated the first time
138a string is not found; use \helpref{wxLogNull}{wxlogoverview} to suppress it).
139
dbdb39b2
JS
140\wxheading{Remarks}
141
142Domains are searched in the last to first order, i.e. catalogs
c1b7dab0 143added later override those added before.
dbdb39b2 144