docs/latex/wx/locale.tex

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