More doxygen topic overview cleanup.

[wxWidgets.git] / docs / latex / wx / xlocale.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        xlocale.tex
%% Purpose:     wxXLocale documentation
%% Author:      Vadim Zeitlin
%% Created:     2008-02-10
%% RCS-ID:      $Id: cmdlpars.tex 49199 2007-10-17 17:32:16Z VZ $
%% Copyright:   (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxXLocale}}\label{wxxlocale}

\subsection{Introduction}

This class represents a locale object used by so-called xlocale API. Unlike 
\helpref{wxLocale}{wxlocale} it doesn't provide any non-trivial operations but
simply provides a portable wrapper for POSIX \texttt{locale\_t} type. It exists
solely to be provided as an argument to various \texttt{wxFoo\_l()} functions
which are the extensions of the standard locale-dependent functions (hence the
name xlocale). These functions do exactly the same thing as the corresponding
standard \texttt{foo()} except that instead of using the global program locale
they use the provided wxXLocale object. For example, if the user runs the
program in French locale, the standard \texttt{printf()} function will output
floating point numbers using decimal comma instead of decimal period. If the
program needs to format a floating-point number in a standard format it can
use \texttt{wxPrintf\_l(wxXLocale::GetCLocale(), "\%g", number)} to do it.
Conversely, if a program wanted to output the number in French locale, even if
the current locale is different, it could use wxXLocale(wxLANGUAGE\_FRENCH).

\subsection{Availability}

This class is fully implemented only under the platforms where xlocale POSIX
API or equivalent is available. Currently the xlocale API is available under
most of the recent Unix systems (including Linux, various BSD and Mac OS X) and
Microsoft Visual C++ standard library provides a similar API starting from
version 8 (Visual Studio 2005).

If neither POSIX API nor Microsoft proprietary equivalent are available, this
class is still available but works in degraded mode: the only supported locale
is the C one and attempts to create wxXLocale object for any other locale will
fail. You can use the preprocessor macro \texttt{wxHAS\_XLOCALE\_SUPPORT} to
test if full xlocale API is available or only skeleton C locale support is
present.

Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if 
\texttt{wxUSE\_XLOCALE} was set to $0$ during the library compilation.

\subsection{Locale-dependent functions}

Currently the following \texttt{\_l}-functions are available:
\begin{itemize}
    \item Character classification functions: \texttt{wxIsxxx\_l()}, e.g.
          \texttt{wxIsalpha\_l()}, \texttt{wxIslower\_l()} and all the others.
    \item Character transformation functions: \texttt{wxTolower\_l()} and
          \texttt{wxToupper\_l()}
\end{itemize}

We hope to provide many more functions (covering numbers, time and formatted
IO) in the near future.


\wxheading{Derived from}

No base class

\wxheading{See also}

\helpref{wxLocale}{wxlocale}

\wxheading{Include files}

<wx/intl.h>

\wxheading{Library}

\helpref{wxBase}{librarieslist}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxXLocale::wxXLocale}\label{wxxlocalector}

\func{}{wxLocale}{\void}

Creates an uninitialized locale object, \helpref{IsOk}{wxxlocaleisok} method
will return false.

\func{}{wxLocale}{\param{wxLanguage}{ lang}}

Creates the locale object corresponding to the specified language.

\func{}{wxLocale}{\param{const char *}{loc}}

Creates the locale object corresponding to the specified locale string. The
locale string is system-dependent, use constructor taking wxLanguage for better
portability.


\membersection{wxXLocale::GetCLocale}\label{wxxlocalegetclocale}

\func{static wxXLocale\& }{GetCLocale}{\void}

Returns the global object representing the "C" locale. For an even shorter
access to this object a global \texttt{wxCLocale} variable (implemented as a
macro) is provided and can be used instead of calling this method.


\membersection{wxXLocale::IsOk}\label{wxxlocaleisok}

\constfunc{bool}{IsOk}{\void}

Returns \true if this object is initialized, i.e. represents a valid locale or 
\false otherwise.