/////////////////////////////////////////////////////////////////////////////
// Name: intl.h
-// Purpose: documentation for wxLocale class
+// Purpose: interface of wxLocale
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
# ....
# use the functions
- print gettext( ``Panic!'' );
+ print gettext( "Panic!" );
- button = Wx::Button-new( window, -1, gettext( ``Label'' ) );
+ button = Wx::Button-new( window, -1, gettext( "Label" ) );
@endcode
If you need to translate a lot of strings, then adding gettext( ) around
# ...
# use the functions
- print t( ``Panic!!'' );
+ print t( "Panic!!" );
# ...
@endcode
@library{wxbase}
@category{FIXME}
- @seealso
- @ref overview_internationalization, @ref overview_sampleinternat "Internat
+ @see @ref overview_internationalization, @ref overview_sampleinternat "Internat
sample", wxXLocale
*/
class wxLocale
@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
+ 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
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.
-
+
@see GetLanguageInfo()
*/
static wxLanguageInfo* FindLanguageInfo(const wxString& locale);
This form is internally used when looking up message catalogs.
Compare GetSysName().
*/
- wxString GetCanonicalName();
+ wxString GetCanonicalName() const;
/**
Returns the header value for header @e header. The search for @a header is case
The return value is the value of the header if found. Else this will be empty.
*/
wxString GetHeaderValue(const wxString& header,
- const wxString& domain = wxEmptyString);
+ const wxString& domain = wxEmptyString) const;
/**
- Returns wxLanguage constant of current language.
+ Returns wxLanguage() constant of current language.
Note that you can call this function only if you used the form of
Init() that takes wxLanguage argument.
*/
- int GetLanguage();
+ int GetLanguage() const;
/**
Returns a pointer to wxLanguageInfo structure containing information about 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);
+ static wxLanguageInfo* GetLanguageInfo(int lang) const;
/**
Returns English name of the given language or empty string if this
See GetLanguageInfo() for a remark about
special meaning of @c wxLANGUAGE_DEFAULT.
*/
- static wxString GetLanguageName(int lang);
+ static wxString GetLanguageName(int lang) const;
/**
Returns the locale name as passed to the constructor or
Init(). This is full, human-readable name,
e.g. "English" or "French".
*/
- const wxString GetLocale();
+ 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 wxString GetName() const;
//@{
/**
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.
-
+ 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.
*/
const wxString GetString(const wxString& origString,
- const wxString& domain = wxEmptyString);
- const wxString GetString(const wxString& origString,
- const wxString& origString2,
- size_t n,
- const wxString& domain = NULL);
+ const wxString& domain = wxEmptyString) const;
+ const const wxString& GetString(const wxString& origString,
+ const wxString& origString2,
+ size_t n,
+ const wxString& domain = NULL) const;
//@}
/**
Returns current platform-specific locale name as passed to setlocale().
Compare GetCanonicalName().
*/
- wxString GetSysName();
+ wxString GetSysName() const;
/**
Tries to detect the user's default font encoding.
- Returns wxFontEncoding value or
+ Returns wxFontEncoding() value or
@b wxFONTENCODING_SYSTEM if it couldn't be determined.
*/
- static wxFontEncoding GetSystemEncoding();
+ static wxFontEncoding GetSystemEncoding() const;
/**
Tries to detect the name of the user's default font encoding. This string isn't
Returns a user-readable string value or an empty string if it couldn't be
determined.
*/
- static wxString GetSystemEncodingName();
+ static wxString GetSystemEncodingName() const;
/**
Tries to detect the user's default language setting.
- Returns wxLanguage value or
+ Returns wxLanguage() value or
@b wxLANGUAGE_UNKNOWN if the language-guessing algorithm failed.
*/
- static int GetSystemLanguage();
+ 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
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_CONV_ENCODING
-
-
-
-
+
+
+
+
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
FindLanguageInfo() to obtain its
wxLanguageInfo structure. See AddLanguage() for
the wxLanguageInfo description.
- This function is new since wxWidgets version 2.7.1.
+
+ @wxsince{2.7.1}.
*/
static bool IsAvailable(int lang);
normally corresponds to 'domain' which is more or less the application name.
See also: AddCatalog()
*/
- bool IsLoaded(const char* domain);
+ bool IsLoaded(const char* domain) const;
/**
Returns @true if the locale could be set successfully.
*/
- bool IsOk();
+ bool IsOk() const;
/**
See @ref overview_languagecodes "list of recognized language constants".
};
+
/**
@class wxXLocale
@wxheader{intl.h}
@library{wxbase}
@category{FIXME}
- @seealso
- wxLocale
+ @see wxLocale
*/
class wxXLocale
{
or
@false otherwise.
*/
- bool IsOk();
+ bool IsOk() const;
/**
Currently the following @c _l-functions are available:
@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.
+ This macro is identical to _() but for the plural variant of
+ wxGetTranslation().
+
+ @returns A const wxString.
+
+ @header{wx/intl.h}
*/
-#define const wxString wxPLURAL(const wxString& sing,
-const wxString& plur,
-size_t n) /* implementation is private */
+#define wxPLURAL(string, plural, n)
/**
- This macro doesn't do anything in the program code -- it simply expands to the
- value of its argument.
+ 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 function call which means that it
- cannot be used in some situations, notably for static array
+ 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
+ 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
+ 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"), ...,
// use wxGetTranslation(weekdays[n])
@endcode
- here.
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.
+ 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.
+
+ @returns A const wxChar*.
+
+ @header{wx/intl.h}
*/
-#define const wxChar* wxTRANSLATE(const char* s) /* implementation is private */
+#define wxTRANSLATE(string)
/**
- This macro expands into a call to wxGetTranslation
- function, 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 macro with _T!
+ 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 _(const wxString& s);
+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 function returns the translation of string @a str in the current
- locale. If the string is not found in any of the loaded
- message catalogs (see @ref overview_internationalization "internationalization
- overview"), 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.
- 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: as above, @e str
- 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 strPlural 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 str is returned if 'n == 1',
- otherwise @e strPlural.
- See GNU gettext manual
- for additional information on plural forms handling. For a shorter alternative
- see the wxPLURAL macro.
- Both versions call wxLocale::GetString.
- Note that 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.
+ 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 wxGetTranslation(const wxString& str,
- const wxString& domain = wxEmptyString);
-const wxString wxGetTranslation(const wxString& str,
- const wxString& strPlural,
- size_t n,
- const wxString& domain = wxEmptyString);
+const wxString _(const wxString& string);
+
//@}
projects / wxWidgets.git / blobdiff