interface/wx/xlocale.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        xlocale.h
   3 // Purpose:     interface of wxXLocale
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxXLocale
  12
  13     This class represents a locale object used by so-called xlocale API.
  14     Unlike wxLocale it doesn't provide any non-trivial operations but simply
  15     provides a portable wrapper for POSIX @c locale_t type.
  16
  17     It exists solely to be provided as an argument to various @c wxFoo_l() functions
  18     which are the extensions of the standard locale-dependent functions (hence the
  19     name xlocale). These functions do exactly the same thing as the corresponding
  20     standard @c foo() except that instead of using the global program locale
  21     they use the provided wxXLocale object.
  22
  23     For example, if the user runs the program in French locale, the standard
  24     @c printf() function will output floating point numbers using decimal comma
  25     instead of decimal period. If the program needs to format a floating-point
  26     number in a standard format it can use:
  27     @code wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) @endcode
  28     to do it.
  29
  30     Conversely, if a program wanted to output the number in French locale, even if
  31     the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH).
  32
  33
  34     @section xlocale_avail Availability
  35
  36     This class is fully implemented only under the platforms where xlocale POSIX
  37     API or equivalent is available. Currently the xlocale API is available under
  38     most of the recent Unix systems (including Linux, various BSD and Mac OS X) and
  39     Microsoft Visual C++ standard library provides a similar API starting from
  40     version 8 (Visual Studio 2005).
  41
  42     If neither POSIX API nor Microsoft proprietary equivalent are available, this
  43     class is still available but works in degraded mode: the only supported locale
  44     is the C one and attempts to create wxXLocale object for any other locale will
  45     fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to test if
  46     full xlocale API is available or only skeleton C locale support is present.
  47
  48     Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if
  49     @c wxUSE_XLOCALE was set to 0 during the library compilation.
  50
  51
  52     @section xlocale_func Locale-dependent functions
  53
  54     Currently the following @c _l-functions are available:
  55
  56     Character classification functions: @c wxIsxxx_l(), e.g.
  57               @c wxIsalpha_l(), @c wxIslower_l() and all the others.
  58          Character transformation functions: @c wxTolower_l() and
  59               @c wxToupper_l()
  60
  61     We hope to provide many more functions (covering numbers, time and formatted
  62     IO) in the near future.
  63
  64     @library{wxbase}
  65     @category{misc}
  66
  67     @see wxLocale
  68 */
  69 class wxXLocale
  70 {
  71 public:
  72     //@{
  73     /**
  74         Creates the locale object corresponding to the specified locale string. The
  75         locale string is system-dependent, use constructor taking wxLanguage for better
  76         portability.
  77     */
  78     wxLocale();
  79     wxLocale(wxLanguage lang);
  80     wxLocale(const char* loc);
  81     //@}
  82
  83     /**
  84         This class is fully implemented only under the platforms where xlocale POSIX
  85         API or equivalent is available. Currently the xlocale API is available under
  86         most of the recent Unix systems (including Linux, various BSD and Mac OS X) and
  87         Microsoft Visual C++ standard library provides a similar API starting from
  88         version 8 (Visual Studio 2005).
  89         If neither POSIX API nor Microsoft proprietary equivalent are available, this
  90         class is still available but works in degraded mode: the only supported locale
  91         is the C one and attempts to create wxXLocale object for any other locale will
  92         fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to
  93         test if full xlocale API is available or only skeleton C locale support is
  94         present.
  95         Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if
  96         @c wxUSE_XLOCALE was set to 0 during the library compilation.
  97     */
  98
  99
 100     /**
 101         Returns the global object representing the "C" locale. For an even shorter
 102         access to this object a global @c wxCLocale variable (implemented as a
 103         macro) is provided and can be used instead of calling this method.
 104     */
 105     static wxXLocale GetCLocale();
 106
 107     /**
 108         This class represents a locale object used by so-called xlocale API. Unlike
 109         wxLocale it doesn't provide any non-trivial operations but
 110         simply provides a portable wrapper for POSIX @c locale_t type. It exists
 111         solely to be provided as an argument to various @c wxFoo_l() functions
 112         which are the extensions of the standard locale-dependent functions (hence the
 113         name xlocale). These functions do exactly the same thing as the corresponding
 114         standard @c foo() except that instead of using the global program locale
 115         they use the provided wxXLocale object. For example, if the user runs the
 116         program in French locale, the standard @c printf() function will output
 117         floating point numbers using decimal comma instead of decimal period. If the
 118         program needs to format a floating-point number in a standard format it can
 119         use @c wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) to do it.
 120         Conversely, if a program wanted to output the number in French locale, even if
 121         the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH).
 122     */
 123
 124
 125     /**
 126         Returns @true if this object is initialized, i.e. represents a valid locale
 127         or
 128         @false otherwise.
 129     */
 130     bool IsOk() const;
 131
 132     /**
 133         Currently the following @c _l-functions are available:
 134         Character classification functions: @c wxIsxxx_l(), e.g.
 135             @c wxIsalpha_l(), @c wxIslower_l() and all the others.
 136         Character transformation functions: @c wxTolower_l() and
 137             @c wxToupper_l()
 138         We hope to provide many more functions (covering numbers, time and formatted
 139         IO) in the near future.
 140
 141         @see wxLocale
 142     */
 143 };