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{Include files}
  14
  15 <wx/intl.h>
  16
  17 \latexignore{\rtfignore{\wxheading{Members}}}
  18
  19 \membersection{wxLocale::wxLocale}\label{wxlocaledefctor}
  20
  21 \func{}{wxLocale}{\void}
  22
  23 This is the default constructor and it does nothing to initialize the object:
  24 \helpref{Init()}{wxlocaleinit} must be used to do that.
  25
  26 \func{}{wxLocale}{\param{const char }{*szName}, \param{const char }{*szShort = NULL}, \param{const char }{*szLocale = NULL}, \param{bool }{bLoadDefault = TRUE}}
  27
  28 The 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
  32 directory 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
  35 for the given locale containing the translations of standard wxWindows messages.
  36 This parameter would be rarely used in normal circumstances.
  37 \end{itemize}
  38
  39 The call of this function has several global side effects which you should
  40 understand: first of all, the application locale is changed - note that this
  41 will affect many of standard C library functions such as printf() or strftime().
  42 Second, this wxLocale object becomes the new current global locale for the
  43 application and so all subsequent calls to wxGetTranslation() will try to
  44 translate the messages using the message catalogs for this locale.
  45
  46 \membersection{wxLocale::\destruct{wxLocale}}\label{wxlocaledtor}
  47
  48 \func{}{\destruct{wxLocale}}{\void}
  49
  50 The destructor, like the constructor, also has global side effects: the previously
  51 set 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
  58 Returns the locale name as passed to the constructor or
  59 \helpref{Init()}{wxlocaleinit}.
  60
  61 \membersection{wxLocale::AddCatalog}\label{wxlocaleaddcatalog}
  62
  63 \func{bool}{AddCatalog}{\param{const char }{*szDomain}}
  64
  65 Add a catalog for use with the current locale: it's searched for in standard
  66 places (current directory first, then the system one), but you may also prepend
  67 additional directories to the search path with
  68 \helpref{AddCatalogLookupPathPrefix()}{wxlocaleaddcataloglookuppathprefix}.
  69
  70 All loaded catalogs will be used for message lookup by GetString() for the
  71 current locale.
  72
  73 Returns TRUE if catalog was successfully loaded, FALSE otherwise (which might
  74 mean 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
  80 Add a prefix to the catalog lookup path: the message catalog files will be
  81 looked up under prefix/<lang>/LC\_MESSAGES, prefix/LC\_MESSAGES and prefix
  82 (in this order).
  83
  84 This 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
  90 The parameters have the following meaning:
  91
  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
  95 directory 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
  98 for the given locale containing the translations of standard wxWindows messages.
  99 This parameter would be rarely used in normal circumstances.
 100 \end{itemize}
 101
 102 The call of this function has several global side effects which you should
 103 understand: first of all, the application locale is changed - note that this
 104 will affect many of standard C library functions such as printf() or strftime().
 105 Second, this wxLocale object becomes the new current global locale for the
 106 application and so all subsequent calls to wxGetTranslation() will try to
 107 translate the messages using the message catalogs for this locale.
 108
 109 Returns TRUE on success or FALSE if the given locale couldn't be set.
 110
 111 \membersection{wxLocale::IsLoaded}\label{wxlocaleisloaded}
 112
 113 \constfunc{bool}{IsLoaded}{\param{const char* }{domain}}
 114
 115 Check if the given catalog is loaded, and returns TRUE if it is.
 116
 117 According to GNU gettext tradition, each catalog
 118 normally corresponds to 'domain' which is more or less the application name.
 119
 120 See also: \helpref{AddCatalog}{wxlocaleaddcatalog}
 121
 122 \membersection{wxLocale::GetName}\label{wxlocalegetname}
 123
 124 \constfunc{const wxString\&}{GetName}{\void}
 125
 126 Returns the current short name for the locale (as given to the constructor or
 127 the 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
 133 Retrieves the translation for a string in all loaded domains unless the szDomain
 134 parameter is specified (and then only this catalog/domain is searched).
 135
 136 Returns original string if translation is not available
 137 (in this case an error message is generated the first time
 138 a string is not found; use \helpref{wxLogNull}{wxlogoverview} to suppress it).
 139
 140 \wxheading{Remarks}
 141
 142 Domains are searched in the last to first order, i.e. catalogs
 143 added later override those added before.
 144