X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/intl.h?ds=sidebyside diff --git a/interface/wx/intl.h b/interface/wx/intl.h index e71e3ef00f..e34f200bac 100644 --- a/interface/wx/intl.h +++ b/interface/wx/intl.h @@ -2,26 +2,179 @@ // Name: intl.h // Purpose: interface of wxLocale // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/** + This is the layout direction stored in wxLanguageInfo and returned by + wxApp::GetLayoutDirection(), wxWindow::GetLayoutDirection(), + wxDC::GetLayoutDirection() for RTL (right-to-left) languages support. +*/ +enum wxLayoutDirection +{ + wxLayout_Default, + wxLayout_LeftToRight, + wxLayout_RightToLeft +}; + +/** + Encapsulates a ::wxLanguage identifier together with OS-specific information + related to that language. + + @beginWxPerlOnly + In wxPerl @c Wx::LanguageInfo has only one method: + - Wx::LanguageInfo->new(language, canonicalName, WinLang, WinSubLang, Description) + @endWxPerlOnly +*/ +struct wxLanguageInfo +{ + /// ::wxLanguage id. + /// It should be greater than @c wxLANGUAGE_USER_DEFINED when defining your own + /// language info structure. + int Language; + + /// Canonical name of the language, e.g. @c fr_FR. + wxString CanonicalName; + + //@{ + /** + Win32 language identifiers (LANG_xxxx, SUBLANG_xxxx). + + @onlyfor{wxmsw} + */ + wxUint32 WinLang, WinSublang; + //@} + + /// Human-readable name of the language. + wxString Description; + + /// The layout direction used for this language. + wxLayoutDirection LayoutDirection; + + /// Return the LCID corresponding to this language. + /// @onlyfor{wxmsw} + wxUint32 GetLCID() const; + + /// Return the locale name corresponding to this language usable with + /// @c setlocale() on the current system. + wxString GetLocaleName() const; +}; + + +/** + The category of locale settings. + + @see wxLocale::GetInfo() +*/ +enum wxLocaleCategory +{ + /// Number formatting. + wxLOCALE_CAT_NUMBER, + + /// Date/time formatting. + wxLOCALE_CAT_DATE, + + /// Monetary values formatting. + wxLOCALE_CAT_MONEY, + + /** + Default category for the wxLocaleInfo value. + + This category can be used for values which only make sense for a single + category, e.g. wxLOCALE_SHORT_DATE_FMT which can only be used with + wxLOCALE_CAT_DATE. As this is the default value of the second parameter + of wxLocale::GetInfo(), wxLOCALE_CAT_DATE can be omitted when asking + for wxLOCALE_SHORT_DATE_FMT value. + + @since 2.9.0 + */ + wxLOCALE_CAT_DEFAULT +}; + +/** + The values understood by wxLocale::GetInfo(). + + Note that for the @c wxLOCALE_*_FMT constants (the date and time formats), + the strings returned by wxLocale::GetInfo() use strftime() or, + equivalently, wxDateTime::Format() format. If the relevant format + couldn't be determined, an empty string is returned -- there is no + fallback value so that the application could determine the best course + of actions itself in such case. + + All of these values are used with @c wxLOCALE_CAT_DATE in wxLocale::GetInfo() or, + more typically, with @c wxLOCALE_CAT_DEFAULT as they only apply to a single category. +*/ +enum wxLocaleInfo +{ + /** + The thousands separator. + + This value can be used with either wxLOCALE_CAT_NUMBER or + wxLOCALE_CAT_MONEY categories. + */ + wxLOCALE_THOUSANDS_SEP, + + /** + The character used as decimal point. + + This value can be used with either wxLOCALE_CAT_NUMBER or + wxLOCALE_CAT_MONEY categories. + */ + wxLOCALE_DECIMAL_POINT, + + /** + Short date format. + + Notice that short and long date formats may be the same under POSIX + systems currently but may, and typically are, different under MSW or OS X. + + @since 2.9.0 + */ + wxLOCALE_SHORT_DATE_FMT, + + /** + Long date format. + + @since 2.9.0 + */ + wxLOCALE_LONG_DATE_FMT, + + /** + Date and time format. + + @since 2.9.0 + */ + wxLOCALE_DATE_TIME_FMT, + + /** + Time format. + + @since 2.9.0 + */ + wxLOCALE_TIME_FMT +}; + + /** @class wxLocale - @wxheader{intl.h} wxLocale class encapsulates all language-dependent settings and is a generalization of the C locale concept. - In wxWidgets this class manages message catalogs which contain the translations - of the strings used to the current language. + In wxWidgets this class manages current locale. It also initializes and + activates wxTranslations object that manages message catalogs. + + For a list of the supported languages, please see ::wxLanguage enum values. + These constants may be used to specify the language in wxLocale::Init and + are returned by wxLocale::GetSystemLanguage. - @b wxPerl note: In wxPerl you can't use the '_' function name, so + @beginWxPerlOnly + In wxPerl you can't use the '_' function name, so the @c Wx::Locale module can export the @c gettext and @c gettext_noop under any given name. @code - # this imports gettext ( equivalent to Wx::GetTranslation + # this imports gettext ( equivalent to Wx::GetTranslation # and gettext_noop ( a noop ) # into your module use Wx::Locale qw(:default); @@ -39,7 +192,6 @@ a shorter name for gettext: @code - # use Wx::Locale 'gettext' = 't', 'gettext_noop' = 'gettext_noop'; @@ -50,96 +202,73 @@ # ... @endcode + @endWxPerlOnly @library{wxbase} - @category{FIXME} + @category{cfg} - @see @ref overview_internationalization, @ref overview_sampleinternat "Internat - sample", wxXLocale + @see @ref overview_i18n, @ref page_samples_internat, wxXLocale, wxTranslations */ class wxLocale { public: - //@{ + /** + This is the default constructor and it does nothing to initialize the object: + Init() must be used to do that. + */ + wxLocale(); + /** See Init() for parameters description. + */ + wxLocale(int language, int flags = wxLOCALE_LOAD_DEFAULT); + + /** + See Init() for parameters description. + The call of this function has several global side effects which you should understand: first of all, the application locale is changed - note that this will affect many of standard C library functions such as printf() or strftime(). Second, this wxLocale object becomes the new current global locale for the - application and so all subsequent calls to wxGetTranslation() will try to + application and so all subsequent calls to ::wxGetTranslation() will try to translate the messages using the message catalogs for this locale. */ - wxLocale(); - wxLocale(int language, - int flags = - wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); wxLocale(const wxString& name, - const wxString& short = wxEmptyString, + const wxString& shortName = wxEmptyString, const wxString& locale = wxEmptyString, - bool bLoadDefault = true, - bool bConvertEncoding = false); - //@} + bool bLoadDefault = true); /** The destructor, like the constructor, also has global side effects: the - previously - set locale is restored and so the changes described in + previously set locale is restored and so the changes described in Init() documentation are rolled back. */ - ~wxLocale(); + virtual ~wxLocale(); - //@{ /** - Add a catalog for use with the current locale: it is searched for in standard - places (current directory first, then the system one), but you may also prepend - additional directories to the search path with - AddCatalogLookupPathPrefix(). - All loaded catalogs will be used for message lookup by - GetString() for the current locale. - Returns @true if catalog was successfully loaded, @false otherwise (which might - mean that the catalog is not found or that it isn't in the correct format). - The second form of this method takes two additional arguments, - @a msgIdLanguage and @e msgIdCharset. - @a msgIdLanguage specifies the language of "msgid" strings in source code - (i.e. arguments to GetString(), - wxGetTranslation() and the - _() macro). It is used if AddCatalog cannot find any - catalog for current language: if the language is same as source code language, - then strings from source code are used instead. - @a msgIdCharset lets you specify the charset used for msgids in sources - in case they use 8-bit characters (e.g. German or French strings). This - argument has no effect in Unicode build, because literals in sources are - Unicode strings; you have to use compiler-specific method of setting the right - charset when compiling with Unicode. - By default (i.e. when you use the first form), msgid strings are assumed - to be in English and written only using 7-bit ASCII characters. - If you have to deal with non-English strings or 8-bit characters in the source - code, see the instructions in - @ref overview_nonenglishoverview "Writing non-English applications". + Calls wxTranslations::AddCatalog(const wxString&). */ bool AddCatalog(const wxString& domain); - bool AddCatalog(const wxString& domain, - wxLanguage msgIdLanguage, + + /** + Calls wxTranslations::AddCatalog(const wxString&, wxLanguage). + */ + bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage); + + /** + Calls wxTranslations::AddCatalog(const wxString&, wxLanguage, const wxString&). + */ + bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage, const wxString& msgIdCharset); - //@} /** - Add a prefix to the catalog lookup path: the message catalog files will be - looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix - (in this order). - This only applies to subsequent invocations of AddCatalog(). + Calls wxFileTranslationsLoader::AddCatalogLookupPathPrefix(). */ - void AddCatalogLookupPathPrefix(const wxString& prefix); + static void AddCatalogLookupPathPrefix(const wxString& prefix); /** - Adds custom, user-defined language to the database of known languages. This - database is used in conjunction with the first form of - Init(). - wxLanguageInfo is defined as follows: - @e Language should be greater than wxLANGUAGE_USER_DEFINED. - Wx::LanguageInfo-new( language, canonicalName, WinLang, WinSubLang, Description - ) + Adds custom, user-defined language to the database of known languages. + This database is used in conjunction with the first form of Init(). */ static void AddLanguage(const wxLanguageInfo& info); @@ -148,13 +277,14 @@ public: given locale, specified either as a two letter ISO language code (for example, "pt"), a language code followed by the country code ("pt_BR") or a full, human readable, language description ("Portuguese-Brazil"). + Returns the information for the given language or @NULL if this language - is unknown. Note that even if the returned pointer is valid, the caller should - @e not delete it. + is unknown. Note that even if the returned pointer is valid, the caller + should @e not delete it. @see GetLanguageInfo() */ - static wxLanguageInfo* FindLanguageInfo(const wxString& locale); + static const wxLanguageInfo* FindLanguageInfo(const wxString& locale); /** Returns the canonical form of current locale name. Canonical form is the @@ -167,85 +297,74 @@ public: wxString GetCanonicalName() const; /** - Returns the header value for header @e header. The search for @a header is case - sensitive. If an @e domain - is passed, this domain is searched. Else all domains will be searched until a - header has been found. - The return value is the value of the header if found. Else this will be empty. + Calls wxTranslations::GetHeaderValue(). */ wxString GetHeaderValue(const wxString& header, const wxString& domain = wxEmptyString) const; /** - Returns wxLanguage() constant of current language. + Returns the ::wxLanguage constant of current language. + Note that you can call this function only if you used the form of - Init() that takes wxLanguage argument. + Init() that takes ::wxLanguage argument. */ int GetLanguage() const; /** - Returns a pointer to wxLanguageInfo structure containing information about the - given language or @NULL if this language is unknown. Note that even if the - returned pointer is valid, the caller should @e not delete it. - See AddLanguage() for the wxLanguageInfo - description. - As with Init(), @c wxLANGUAGE_DEFAULT has the - special meaning if passed as an argument to this function and in this case the - result of GetSystemLanguage() is used. + Returns a pointer to wxLanguageInfo structure containing information about + the given language or @NULL if this language is unknown. Note that even if + the returned pointer is valid, the caller should @e not delete it. + + See AddLanguage() for the wxLanguageInfo description. + As with Init(), @c wxLANGUAGE_DEFAULT has the special meaning if passed + as an argument to this function and in this case the result of + GetSystemLanguage() is used. */ - static wxLanguageInfo* GetLanguageInfo(int lang) const; + static const wxLanguageInfo* GetLanguageInfo(int lang); /** Returns English name of the given language or empty string if this language is unknown. - See GetLanguageInfo() for a remark about - special meaning of @c wxLANGUAGE_DEFAULT. + + See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT. + */ + static wxString GetLanguageName(int lang); + + /** + Returns canonical name (see GetCanonicalName()) of the given language + or empty string if this language is unknown. + + See GetLanguageInfo() for a remark about special meaning of @c wxLANGUAGE_DEFAULT. + + @since 2.9.1 */ - static wxString GetLanguageName(int lang) const; + static wxString GetLanguageCanonicalName(int lang); /** - Returns the locale name as passed to the constructor or - Init(). This is full, human-readable name, - e.g. "English" or "French". + Returns the locale name as passed to the constructor or Init(). + + This is a full, human-readable name, e.g. "English" or "French". */ - const wxString GetLocale() const; + const wxString& GetLocale() const; /** Returns the current short name for the locale (as given to the constructor or the Init() function). */ - const wxString GetName() const; + const wxString& GetName() const; - //@{ /** - Retrieves the translation for a string in all loaded domains unless the szDomain - parameter is specified (and then only this catalog/domain is searched). - Returns original string if translation is not available - (in this case an error message is generated the first time - a string is not found; use wxLogNull to suppress it). - The second form is used when retrieving translation of string that has - different singular and plural form in English or different plural forms in some - other language. It takes two extra arguments: @e origString - parameter must contain the singular form of the string to be converted. - It is also used as the key for the search in the catalog. - The @a origString2 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 origString is returned if 'n == 1', - otherwise @e origString2. - See GNU gettext manual for additional information on plural forms handling. - This method is called by the wxGetTranslation() - function and _() macro. - - @remarks Domains are searched in the last to first order, i.e. catalogs - added later override those added before. + Calls wxTranslations::GetString(const wxString&, const wxString&) const. */ - const wxString GetString(const wxString& origString, - const wxString& domain = wxEmptyString) const; - const const wxString& GetString(const wxString& origString, - const wxString& origString2, - size_t n, - const wxString& domain = NULL) const; - //@} + virtual const wxString& GetString(const wxString& origString, + const wxString& domain = wxEmptyString) const; + + /** + Calls wxTranslations::GetString(const wxString&, const wxString&, unsigned, const wxString&) const. + */ + virtual const wxString& GetString(const wxString& origString, + const wxString& origString2, unsigned n, + const wxString& domain = wxEmptyString) const; /** Returns current platform-specific locale name as passed to setlocale(). @@ -255,407 +374,122 @@ public: /** Tries to detect the user's default font encoding. - Returns wxFontEncoding() value or - @b wxFONTENCODING_SYSTEM if it couldn't be determined. + Returns wxFontEncoding() value or @c wxFONTENCODING_SYSTEM if it + couldn't be determined. */ - static wxFontEncoding GetSystemEncoding() const; + static wxFontEncoding GetSystemEncoding(); /** - Tries to detect the name of the user's default font encoding. This string isn't - particularly useful for the application as its form is platform-dependent and - so you should probably use - GetSystemEncoding() instead. + Tries to detect the name of the user's default font encoding. + This string isn't particularly useful for the application as its form is + platform-dependent and so you should probably use GetSystemEncoding() instead. + Returns a user-readable string value or an empty string if it couldn't be determined. */ - static wxString GetSystemEncodingName() const; + static wxString GetSystemEncodingName(); /** - Tries to detect the user's default language setting. - Returns wxLanguage() value or - @b wxLANGUAGE_UNKNOWN if the language-guessing algorithm failed. - */ - static int GetSystemLanguage() const; - - //@{ - /** - The second form is deprecated, use the first one unless you know what you are - doing. - - @param language - wxLanguage identifier of the locale. - wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's - default - language (see GetSystemLanguage). - @param flags - Combination of the following: - - - - - + Tries to detect the user's default locale setting. + Returns the ::wxLanguage value or @c wxLANGUAGE_UNKNOWN if the language-guessing + algorithm failed. - wxLOCALE_LOAD_DEFAULT - - - - - Load the message catalog - for the given locale containing the translations of standard wxWidgets - messages - automatically. - + @note This function works with @em locales and returns the user's default + locale. This may be, and usually is, the same as their preferred UI + language, but it's not the same thing. Use wxTranslation to obtain + @em language information. + @see wxTranslations::GetBestTranslation(). + */ + static int GetSystemLanguage(); + /** + Get the values of the given locale-dependent datum. + + This function returns the value of the locale-specific option specified + by the given @a index. + + @param index + One of the elements of wxLocaleInfo enum. + @param cat + The category to use with the given index or wxLOCALE_CAT_DEFAULT if + the index can only apply to a single category. + @return + The option value or empty string if the function failed. + */ + static wxString GetInfo(wxLocaleInfo index, + wxLocaleCategory cat = wxLOCALE_CAT_DEFAULT); + /** + Initializes the wxLocale instance. - wxLOCALE_CONV_ENCODING + The call of this function has several global side effects which you should + understand: first of all, the application locale is changed - note that + this will affect many of standard C library functions such as printf() + or strftime(). + Second, this wxLocale object becomes the new current global locale for + the application and so all subsequent calls to wxGetTranslation() will + try to translate the messages using the message catalogs for this locale. + @param language + ::wxLanguage identifier of the locale. + @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's + default language (see GetSystemLanguage()). + @param flags + Combination of the following: + - wxLOCALE_LOAD_DEFAULT: Load the message catalog for the given locale + containing the translations of standard wxWidgets messages + automatically. + - wxLOCALE_DONT_LOAD_DEFAULT: Negation of wxLOCALE_LOAD_DEFAULT. + @return @true on success or @false if the given locale couldn't be set. + */ + bool Init(int language = wxLANGUAGE_DEFAULT, + int flags = wxLOCALE_LOAD_DEFAULT); + /** + @deprecated + This form is deprecated, use the other one unless you know what you are doing. - Automatically convert message - catalogs to platform's default encoding. Note that it will do only basic - conversion between well-known pair like iso8859-1 and windows-1252 or - iso8859-2 and windows-1250. See Writing non-English applications for - detailed - description of this behaviour. Note that this flag is meaningless in - Unicode build. @param name The name of the locale. Only used in diagnostic messages. - @param short + @param shortName The standard 2 letter locale abbreviation; it is used as the directory prefix when looking for the message catalog files. @param locale - The parameter for the call to setlocale(). Note that it is - platform-specific. + The parameter for the call to setlocale(). + Note that it is platform-specific. @param bLoadDefault - May be set to @false to prevent loading of the message catalog - for the given locale containing the translations of standard wxWidgets - messages. + May be set to @false to prevent loading of the message catalog for the + given locale containing the translations of standard wxWidgets messages. This parameter would be rarely used in normal circumstances. - @param bConvertEncoding - May be set to @true to do automatic conversion of message - catalogs to platform's native encoding. Note that it will do only basic - conversion between well-known pair like iso8859-1 and windows-1252 or - iso8859-2 and windows-1250. - See Writing non-English applications for detailed - description of this behaviour. */ - bool Init(int language = wxLANGUAGE_DEFAULT, - int flags = - wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); - bool Init(const wxString& name, - const wxString& short = wxEmptyString, - const wxString& locale = wxEmptyString, - bool bLoadDefault = true, - bool bConvertEncoding = false); - //@} + bool Init(const wxString& name, const wxString& shortName = wxEmptyString, + const wxString& locale = wxEmptyString, bool bLoadDefault = true); /** Check whether the operating system and/or C run time environment supports this locale. For example in Windows 2000 and Windows XP, support for many locales is not installed by default. Returns @true if the locale is supported. - The argument @a lang is the wxLanguage identifier. To obtain this for a - given a two letter ISO language code, use - FindLanguageInfo() to obtain its - wxLanguageInfo structure. See AddLanguage() for - the wxLanguageInfo description. + + The argument @a lang is the ::wxLanguage identifier. To obtain this for a + given a two letter ISO language code, use FindLanguageInfo() to obtain its + wxLanguageInfo structure. + See AddLanguage() for the wxLanguageInfo description. @since 2.7.1. */ static bool IsAvailable(int lang); /** - Check if the given catalog is loaded, and returns @true if it is. - According to GNU gettext tradition, each catalog - normally corresponds to 'domain' which is more or less the application name. - See also: AddCatalog() + Calls wxTranslations::IsLoaded(). */ - bool IsLoaded(const char* domain) const; + bool IsLoaded(const wxString& domain) const; /** Returns @true if the locale could be set successfully. */ bool IsOk() const; - - /** - See @ref overview_languagecodes "list of recognized language constants". - These constants may be used to specify the language - in Init() and are returned by - GetSystemLanguage(): - */ }; - - - -/** - @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: - - 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); - -//@} -