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