-
-
-
-/**
- @class wxXLocale
- @wxheader{intl.h}
-
-
- wxXLocale::wxXLocale
- wxXLocale::GetCLocale
- wxXLocale::IsOk
-
-
- Introduction
-
- This class represents a locale object used by so-called xlocale API. Unlike
- wxLocale it doesn't provide any non-trivial operations but
- simply provides a portable wrapper for POSIX @c locale_t type. It exists
- solely to be provided as an argument to various @c 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 @c 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 @c 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 @c 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).
-
-
- 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 @c 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
- @c wxUSE_XLOCALE was set to 0 during the library compilation.
-
-
- Locale-dependent functions
-
- Currently the following @c _l-functions are available:
-
- Character classification functions: @c wxIsxxx_l(), e.g.
- @c wxIsalpha_l(), @c wxIslower_l() and all the others.
- Character transformation functions: @c wxTolower_l() and
- @c wxToupper_l()
-
- We hope to provide many more functions (covering numbers, time and formatted
- IO) in the near future.
-
- @library{wxbase}
- @category{FIXME}
-
- @see wxLocale
-*/
-class wxXLocale
-{
-public:
- //@{
- /**
- Creates the locale object corresponding to the specified locale string. The
- locale string is system-dependent, use constructor taking wxLanguage for better
- portability.
- */
- wxLocale();
- wxLocale(wxLanguage lang);
- wxLocale(const char* loc);
- //@}
-
- /**
- 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 @c 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
- @c wxUSE_XLOCALE was set to 0 during the library compilation.
- */
-
-
- /**
- Returns the global object representing the "C" locale. For an even shorter
- access to this object a global @c wxCLocale variable (implemented as a
- macro) is provided and can be used instead of calling this method.
- */
- static wxXLocale GetCLocale();
-
- /**
- This class represents a locale object used by so-called xlocale API. Unlike
- wxLocale it doesn't provide any non-trivial operations but
- simply provides a portable wrapper for POSIX @c locale_t type. It exists
- solely to be provided as an argument to various @c 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 @c 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 @c 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 @c 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).
- */
-
-
- /**
- Returns @true if this object is initialized, i.e. represents a valid locale
- or
- @false otherwise.
- */
- bool IsOk() const;
-
- /**
- Currently the following @c _l-functions are available:
- Character classification functions: @c wxIsxxx_l(), e.g.
- @c wxIsalpha_l(), @c wxIslower_l() and all the others.
- Character transformation functions: @c wxTolower_l() and
- @c wxToupper_l()
- We hope to provide many more functions (covering numbers, time and formatted
- IO) in the near future.
-
- @see wxLocale
- */
-};
-
-
-
-// ============================================================================
-// Global functions/macros
-// ============================================================================
-
-/** @ingroup group_funcmacro_string */
-//@{
-
-/**
- This macro is identical to _() but for the plural variant of
- wxGetTranslation().
-
- @return A const wxString.
-
- @header{wx/intl.h}
-*/
-#define wxPLURAL(string, plural, n)
-
-/**
- This macro doesn't do anything in the program code -- it simply expands to
- the value of its argument.
-
- However it does have a purpose which is to mark the literal strings for the
- extraction into the message catalog created by @c xgettext program. Usually
- this is achieved using _() but that macro not only marks the string for
- extraction but also expands into a wxGetTranslation() call which means that
- it cannot be used in some situations, notably for static array
- initialization.
-
- Here is an example which should make it more clear: suppose that you have a
- static array of strings containing the weekday names and which have to be
- translated (note that it is a bad example, really, as wxDateTime already
- can be used to get the localized week day names already). If you write:
-
- @code
- static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
- ...
- // use weekdays[n] as usual
- @endcode
-
- The code wouldn't compile because the function calls are forbidden in the
- array initializer. So instead you should do this:
-
- @code
- static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
- wxTRANSLATE("Sun") };
- ...
- // use wxGetTranslation(weekdays[n])
- @endcode
-
- Note that although the code @b would compile if you simply omit
- wxTRANSLATE() in the above, it wouldn't work as expected because there
- would be no translations for the weekday names in the program message
- catalog and wxGetTranslation() wouldn't find them.
-
- @return A const wxChar*.
-
- @header{wx/intl.h}
-*/
-#define wxTRANSLATE(string)
-
-/**
- This function returns the translation of @a string in the current
- @c locale(). If the string is not found in any of the loaded message
- catalogs (see @ref overview_i18n), the original string is returned. In
- debug build, an error message is logged -- this should help to find the
- strings which were not yet translated. If @a domain is specified then only
- that domain/catalog is searched for a matching string. As this function is
- used very often, an alternative (and also common in Unix world) syntax is
- provided: the _() macro is defined to do the same thing as
- wxGetTranslation().
-
- This function calls wxLocale::GetString().
-
- @note This function is not suitable for literal strings in Unicode builds
- since the literal strings must be enclosed into _T() or wxT() macro
- which makes them unrecognised by @c xgettext, and so they are not
- extracted to the message catalog. Instead, use the _() and wxPLURAL()
- macro for all literal strings.
-
- @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
-
- @header{wx/intl.h}
-*/
-const wxString wxGetTranslation(const wxString& string,
- const wxString& domain = wxEmptyString);
-
-/**
- This is an overloaded version of
- wxGetTranslation(const wxString&, const wxString&), please see its
- documentation for general information.
-
- This version is used when retrieving translation of string that has
- different singular and plural forms in English or different plural forms in
- some other language. Like wxGetTranslation(const wxString&,const wxString&),
- the @a string parameter must contain the singular form of the string to be
- converted and is used as the key for the search in the catalog. The
- @a plural parameter is the plural form (in English). The parameter @a n is
- used to determine the plural form. If no message catalog is found,
- @a string is returned if "n == 1", otherwise @a plural is returned.
-
- See GNU gettext Manual for additional information on plural forms handling:
- <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
- For a shorter alternative see the wxPLURAL() macro.
-
- This function calls wxLocale::GetString().
-
- @header{wx/intl.h}
-*/
-const wxString wxGetTranslation(const wxString& string,
- const wxString& plural, size_t n,
- const wxString& domain = wxEmptyString);
-
-/**
- This macro expands into a call to wxGetTranslation(), so it marks the
- message for the extraction by @c xgettext just as wxTRANSLATE() does, but
- also returns the translation of the string for the current locale during
- execution.
-
- Don't confuse this with _T()!
-
- @header{wx/intl.h}
-*/
-const wxString _(const wxString& string);
-
-//@}
-
projects / wxWidgets.git / blobdiff