docs for wxXLocale (should have been part of r51632)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@51648 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/latex/wx/xlocale.tex b/docs/latex/wx/xlocale.tex
new file mode 100644 (file)
index 0000000..79b08f0
--- /dev/null
+++ b/docs/latex/wx/xlocale.tex
@@ -0,0 +1,114 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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.
+