From 969daeea660b2b85391309d927d496e0926d4246 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Fri, 17 Oct 2008 20:27:36 +0000 Subject: [PATCH] revision of wxLocale; documented the list of language constants into the wxLanguage enum; modified genlang.py to generate a .h with doxygen comments and removed generation of a .tex script; moved docs for wxXlocale to the right header (xlocale.h) git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56411 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/mainpages/const_langcodes.h | 26 - docs/doxygen/mainpages/constants.h | 1 - interface/wx/intl.h | 740 ++++++++++++++--------- interface/wx/xlocale.h | 143 +++++ misc/languages/genlang.py | 60 +- 5 files changed, 605 insertions(+), 365 deletions(-) delete mode 100644 docs/doxygen/mainpages/const_langcodes.h create mode 100644 interface/wx/xlocale.h diff --git a/docs/doxygen/mainpages/const_langcodes.h b/docs/doxygen/mainpages/const_langcodes.h deleted file mode 100644 index 2f9816d0bd..0000000000 --- a/docs/doxygen/mainpages/const_langcodes.h +++ /dev/null @@ -1,26 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: const_langcodes.h -// Purpose: Language values enumerated -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - -@page page_languagecodes Language identifiers - -The following wxLanguage constants may be used to specify the language -in wxLocale::Init and are returned by wxLocale::GetSystemLanguage: - - - -@todo ADAPT THE PYTHON SCRIPTS TO GENERATE HERE THE LIST - -This enum is generated by misc/languages/genlang.py -When making changes, please put them into misc/languages/langtabl.txt - - - -*/ diff --git a/docs/doxygen/mainpages/constants.h b/docs/doxygen/mainpages/constants.h index 89fdf3cd60..021a4185b0 100644 --- a/docs/doxygen/mainpages/constants.h +++ b/docs/doxygen/mainpages/constants.h @@ -15,7 +15,6 @@ This chapter describes the constants defined by wxWidgets. @li @subpage page_keycodes @li @subpage page_keymodifiers -@li @subpage page_languagecodes @li @subpage page_stdevtid @li @subpage page_stockitems @li @subpage page_cppconst diff --git a/interface/wx/intl.h b/interface/wx/intl.h index 12e9f6a21a..5339b0617d 100644 --- a/interface/wx/intl.h +++ b/interface/wx/intl.h @@ -6,6 +6,289 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + +// --- --- --- generated code begins here --- --- --- + +/** + The languages supported by wxLocale. + + This enum is generated by misc/languages/genlang.py + When making changes, please put them into misc/languages/langtabl.txt +*/ +enum wxLanguage +{ + /// User's default/preffered language as got from OS. + wxLANGUAGE_DEFAULT, + + /// Unknown language, returned if wxLocale::GetSystemLanguage fails. + wxLANGUAGE_UNKNOWN, + + wxLANGUAGE_ABKHAZIAN, + wxLANGUAGE_AFAR, + wxLANGUAGE_AFRIKAANS, + wxLANGUAGE_ALBANIAN, + wxLANGUAGE_AMHARIC, + wxLANGUAGE_ARABIC, + wxLANGUAGE_ARABIC_ALGERIA, + wxLANGUAGE_ARABIC_BAHRAIN, + wxLANGUAGE_ARABIC_EGYPT, + wxLANGUAGE_ARABIC_IRAQ, + wxLANGUAGE_ARABIC_JORDAN, + wxLANGUAGE_ARABIC_KUWAIT, + wxLANGUAGE_ARABIC_LEBANON, + wxLANGUAGE_ARABIC_LIBYA, + wxLANGUAGE_ARABIC_MOROCCO, + wxLANGUAGE_ARABIC_OMAN, + wxLANGUAGE_ARABIC_QATAR, + wxLANGUAGE_ARABIC_SAUDI_ARABIA, + wxLANGUAGE_ARABIC_SUDAN, + wxLANGUAGE_ARABIC_SYRIA, + wxLANGUAGE_ARABIC_TUNISIA, + wxLANGUAGE_ARABIC_UAE, + wxLANGUAGE_ARABIC_YEMEN, + wxLANGUAGE_ARMENIAN, + wxLANGUAGE_ASSAMESE, + wxLANGUAGE_AYMARA, + wxLANGUAGE_AZERI, + wxLANGUAGE_AZERI_CYRILLIC, + wxLANGUAGE_AZERI_LATIN, + wxLANGUAGE_BASHKIR, + wxLANGUAGE_BASQUE, + wxLANGUAGE_BELARUSIAN, + wxLANGUAGE_BENGALI, + wxLANGUAGE_BHUTANI, + wxLANGUAGE_BIHARI, + wxLANGUAGE_BISLAMA, + wxLANGUAGE_BRETON, + wxLANGUAGE_BULGARIAN, + wxLANGUAGE_BURMESE, + wxLANGUAGE_CAMBODIAN, + wxLANGUAGE_CATALAN, + wxLANGUAGE_CHINESE, + wxLANGUAGE_CHINESE_SIMPLIFIED, + wxLANGUAGE_CHINESE_TRADITIONAL, + wxLANGUAGE_CHINESE_HONGKONG, + wxLANGUAGE_CHINESE_MACAU, + wxLANGUAGE_CHINESE_SINGAPORE, + wxLANGUAGE_CHINESE_TAIWAN, + wxLANGUAGE_CORSICAN, + wxLANGUAGE_CROATIAN, + wxLANGUAGE_CZECH, + wxLANGUAGE_DANISH, + wxLANGUAGE_DUTCH, + wxLANGUAGE_DUTCH_BELGIAN, + wxLANGUAGE_ENGLISH, + wxLANGUAGE_ENGLISH_UK, + wxLANGUAGE_ENGLISH_US, + wxLANGUAGE_ENGLISH_AUSTRALIA, + wxLANGUAGE_ENGLISH_BELIZE, + wxLANGUAGE_ENGLISH_BOTSWANA, + wxLANGUAGE_ENGLISH_CANADA, + wxLANGUAGE_ENGLISH_CARIBBEAN, + wxLANGUAGE_ENGLISH_DENMARK, + wxLANGUAGE_ENGLISH_EIRE, + wxLANGUAGE_ENGLISH_JAMAICA, + wxLANGUAGE_ENGLISH_NEW_ZEALAND, + wxLANGUAGE_ENGLISH_PHILIPPINES, + wxLANGUAGE_ENGLISH_SOUTH_AFRICA, + wxLANGUAGE_ENGLISH_TRINIDAD, + wxLANGUAGE_ENGLISH_ZIMBABWE, + wxLANGUAGE_ESPERANTO, + wxLANGUAGE_ESTONIAN, + wxLANGUAGE_FAEROESE, + wxLANGUAGE_FARSI, + wxLANGUAGE_FIJI, + wxLANGUAGE_FINNISH, + wxLANGUAGE_FRENCH, + wxLANGUAGE_FRENCH_BELGIAN, + wxLANGUAGE_FRENCH_CANADIAN, + wxLANGUAGE_FRENCH_LUXEMBOURG, + wxLANGUAGE_FRENCH_MONACO, + wxLANGUAGE_FRENCH_SWISS, + wxLANGUAGE_FRISIAN, + wxLANGUAGE_GALICIAN, + wxLANGUAGE_GEORGIAN, + wxLANGUAGE_GERMAN, + wxLANGUAGE_GERMAN_AUSTRIAN, + wxLANGUAGE_GERMAN_BELGIUM, + wxLANGUAGE_GERMAN_LIECHTENSTEIN, + wxLANGUAGE_GERMAN_LUXEMBOURG, + wxLANGUAGE_GERMAN_SWISS, + wxLANGUAGE_GREEK, + wxLANGUAGE_GREENLANDIC, + wxLANGUAGE_GUARANI, + wxLANGUAGE_GUJARATI, + wxLANGUAGE_HAUSA, + wxLANGUAGE_HEBREW, + wxLANGUAGE_HINDI, + wxLANGUAGE_HUNGARIAN, + wxLANGUAGE_ICELANDIC, + wxLANGUAGE_INDONESIAN, + wxLANGUAGE_INTERLINGUA, + wxLANGUAGE_INTERLINGUE, + wxLANGUAGE_INUKTITUT, + wxLANGUAGE_INUPIAK, + wxLANGUAGE_IRISH, + wxLANGUAGE_ITALIAN, + wxLANGUAGE_ITALIAN_SWISS, + wxLANGUAGE_JAPANESE, + wxLANGUAGE_JAVANESE, + wxLANGUAGE_KANNADA, + wxLANGUAGE_KASHMIRI, + wxLANGUAGE_KASHMIRI_INDIA, + wxLANGUAGE_KAZAKH, + wxLANGUAGE_KERNEWEK, + wxLANGUAGE_KINYARWANDA, + wxLANGUAGE_KIRGHIZ, + wxLANGUAGE_KIRUNDI, + wxLANGUAGE_KONKANI, + wxLANGUAGE_KOREAN, + wxLANGUAGE_KURDISH, + wxLANGUAGE_LAOTHIAN, + wxLANGUAGE_LATIN, + wxLANGUAGE_LATVIAN, + wxLANGUAGE_LINGALA, + wxLANGUAGE_LITHUANIAN, + wxLANGUAGE_MACEDONIAN, + wxLANGUAGE_MALAGASY, + wxLANGUAGE_MALAY, + wxLANGUAGE_MALAYALAM, + wxLANGUAGE_MALAY_BRUNEI_DARUSSALAM, + wxLANGUAGE_MALAY_MALAYSIA, + wxLANGUAGE_MALTESE, + wxLANGUAGE_MANIPURI, + wxLANGUAGE_MAORI, + wxLANGUAGE_MARATHI, + wxLANGUAGE_MOLDAVIAN, + wxLANGUAGE_MONGOLIAN, + wxLANGUAGE_NAURU, + wxLANGUAGE_NEPALI, + wxLANGUAGE_NEPALI_INDIA, + wxLANGUAGE_NORWEGIAN_BOKMAL, + wxLANGUAGE_NORWEGIAN_NYNORSK, + wxLANGUAGE_OCCITAN, + wxLANGUAGE_ORIYA, + wxLANGUAGE_OROMO, + wxLANGUAGE_PASHTO, + wxLANGUAGE_POLISH, + wxLANGUAGE_PORTUGUESE, + wxLANGUAGE_PORTUGUESE_BRAZILIAN, + wxLANGUAGE_PUNJABI, + wxLANGUAGE_QUECHUA, + wxLANGUAGE_RHAETO_ROMANCE, + wxLANGUAGE_ROMANIAN, + wxLANGUAGE_RUSSIAN, + wxLANGUAGE_RUSSIAN_UKRAINE, + wxLANGUAGE_SAMI, + wxLANGUAGE_SAMOAN, + wxLANGUAGE_SANGHO, + wxLANGUAGE_SANSKRIT, + wxLANGUAGE_SCOTS_GAELIC, + wxLANGUAGE_SERBIAN, + wxLANGUAGE_SERBIAN_CYRILLIC, + wxLANGUAGE_SERBIAN_LATIN, + wxLANGUAGE_SERBO_CROATIAN, + wxLANGUAGE_SESOTHO, + wxLANGUAGE_SETSWANA, + wxLANGUAGE_SHONA, + wxLANGUAGE_SINDHI, + wxLANGUAGE_SINHALESE, + wxLANGUAGE_SISWATI, + wxLANGUAGE_SLOVAK, + wxLANGUAGE_SLOVENIAN, + wxLANGUAGE_SOMALI, + wxLANGUAGE_SPANISH, + wxLANGUAGE_SPANISH_ARGENTINA, + wxLANGUAGE_SPANISH_BOLIVIA, + wxLANGUAGE_SPANISH_CHILE, + wxLANGUAGE_SPANISH_COLOMBIA, + wxLANGUAGE_SPANISH_COSTA_RICA, + wxLANGUAGE_SPANISH_DOMINICAN_REPUBLIC, + wxLANGUAGE_SPANISH_ECUADOR, + wxLANGUAGE_SPANISH_EL_SALVADOR, + wxLANGUAGE_SPANISH_GUATEMALA, + wxLANGUAGE_SPANISH_HONDURAS, + wxLANGUAGE_SPANISH_MEXICAN, + wxLANGUAGE_SPANISH_MODERN, + wxLANGUAGE_SPANISH_NICARAGUA, + wxLANGUAGE_SPANISH_PANAMA, + wxLANGUAGE_SPANISH_PARAGUAY, + wxLANGUAGE_SPANISH_PERU, + wxLANGUAGE_SPANISH_PUERTO_RICO, + wxLANGUAGE_SPANISH_URUGUAY, + wxLANGUAGE_SPANISH_US, + wxLANGUAGE_SPANISH_VENEZUELA, + wxLANGUAGE_SUNDANESE, + wxLANGUAGE_SWAHILI, + wxLANGUAGE_SWEDISH, + wxLANGUAGE_SWEDISH_FINLAND, + wxLANGUAGE_TAGALOG, + wxLANGUAGE_TAJIK, + wxLANGUAGE_TAMIL, + wxLANGUAGE_TATAR, + wxLANGUAGE_TELUGU, + wxLANGUAGE_THAI, + wxLANGUAGE_TIBETAN, + wxLANGUAGE_TIGRINYA, + wxLANGUAGE_TONGA, + wxLANGUAGE_TSONGA, + wxLANGUAGE_TURKISH, + wxLANGUAGE_TURKMEN, + wxLANGUAGE_TWI, + wxLANGUAGE_UIGHUR, + wxLANGUAGE_UKRAINIAN, + wxLANGUAGE_URDU, + wxLANGUAGE_URDU_INDIA, + wxLANGUAGE_URDU_PAKISTAN, + wxLANGUAGE_UZBEK, + wxLANGUAGE_UZBEK_CYRILLIC, + wxLANGUAGE_UZBEK_LATIN, + wxLANGUAGE_VALENCIAN, + wxLANGUAGE_VIETNAMESE, + wxLANGUAGE_VOLAPUK, + wxLANGUAGE_WELSH, + wxLANGUAGE_WOLOF, + wxLANGUAGE_XHOSA, + wxLANGUAGE_YIDDISH, + wxLANGUAGE_YORUBA, + wxLANGUAGE_ZHUANG, + wxLANGUAGE_ZULU, + + /// For custom, user-defined languages. + wxLANGUAGE_USER_DEFINED +}; + +// --- --- --- generated code ends here --- --- --- + + + +/** + wxLanguageInfo: encapsulates wxLanguage to OS native lang.desc. + translation information +*/ +struct WXDLLIMPEXP_BASE wxLanguageInfo +{ + /// wxLanguage id. It should be greater than wxLANGUAGE_USER_DEFINED. + int Language; + wxString CanonicalName; //!< Canonical name, e.g. fr_FR. +#ifdef __WXMSW__ + wxUint32 WinLang, //!< Win32 language identifiers (LANG_xxxx, SUBLANG_xxxx). + WinSublang; +#endif // __WXMSW__ + wxString Description; //!< Human-readable name of the language. + wxLayoutDirection LayoutDirection; + +#ifdef __WXMSW__ + /// Return the LCID corresponding to this language. + wxUint32 GetLCID() const; +#endif // __WXMSW__ + + /// Return the locale name corresponding to this language usable with + /// setlocale() on the current system + wxString GetLocaleName() const; +}; + + /** @class wxLocale @@ -15,12 +298,17 @@ In wxWidgets this class manages message catalogs which contain the translations of the strings used to the current language. - @b wxPerl note: In wxPerl you can't use the '_' function name, so + 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. + + @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); @@ -38,7 +326,6 @@ a shorter name for gettext: @code - # use Wx::Locale 'gettext' = 't', 'gettext_noop' = 'gettext_noop'; @@ -49,41 +336,47 @@ # ... @endcode + @endWxPerlOnly @library{wxbase} - @category{FIXME} + @category{misc} - @see @ref overview_internationalization, @ref overview_sampleinternat "Internat - sample", wxXLocale + @see @ref overview_internationalization, @ref page_samples_internat, wxXLocale */ 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 | wxLOCALE_CONV_ENCODING); + /** 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& locale = wxEmptyString, bool bLoadDefault = true, bool bConvertEncoding = false); - //@} /** 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. */ virtual ~wxLocale(); @@ -92,53 +385,51 @@ public: /** 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. + 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 and @a 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. + (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 + 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". + If you have to deal with non-English strings or 8-bit characters in the + source code, see the instructions in @ref overview_nonenglish. */ bool AddCatalog(const wxString& domain); - bool AddCatalog(const wxString& domain, - wxLanguage msgIdLanguage, + 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 + 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(). */ 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); @@ -147,9 +438,10 @@ 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() */ @@ -166,10 +458,11 @@ 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 + Returns the header value for header @a header. + The search for @a header is case sensitive. If an @a 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. */ wxString GetHeaderValue(const wxString& header, @@ -177,74 +470,90 @@ public: /** 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() 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; /** 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) const; /** - 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 + Retrieves the translation for a string in all loaded domains unless the @a domain 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. + + 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). + + @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; + + /** + Retrieves the translation for a string in all loaded domains unless the @a domain + 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). + + This 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: @a 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. + + 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 @a 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; - const const wxString& GetString(const wxString& origString, - const wxString& origString2, - size_t n, - const wxString& domain = NULL) const; - //@} + const wxString& GetString(const wxString& origString, + const wxString& origString2, + size_t n, + const wxString& domain = wxEmptyString) const; /** Returns current platform-specific locale name as passed to setlocale(). @@ -254,16 +563,16 @@ 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; /** - 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. */ @@ -271,86 +580,70 @@ public: /** Tries to detect the user's default language setting. - Returns wxLanguage() value or - @b wxLANGUAGE_UNKNOWN if the language-guessing algorithm failed. + 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. + Initializes the wxLocale instance. + + 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. - wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's - default - language (see GetSystemLanguage). + @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_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 - 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. + - 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 + iso8859-2 and windows-1250. See @ref overview_nonenglish 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 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. + 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 @ref overview_nonenglish for detailed description of this behaviour. + + @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 | wxLOCALE_CONV_ENCODING); + int flags = wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); + + /** + @deprecated + This form is deprecated, use the other one unless you know what you are doing. + */ bool Init(const wxString& name, const wxString& short = wxEmptyString, const wxString& locale = wxEmptyString, bool bLoadDefault = true, bool bConvertEncoding = false); - //@} /** Check whether the operating system and/or C run time environment supports @@ -369,9 +662,11 @@ public: /** 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() + + According to GNU gettext tradition, each catalog normally corresponds to + 'domain' which is more or less the application name. + + @see AddCatalog() */ bool IsLoaded(const char* domain) const; @@ -379,157 +674,10 @@ public: 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 - - - 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 @@ -614,7 +762,7 @@ public: @header{wx/intl.h} */ -const wxString wxGetTranslation(const wxString& string, +const wxString& wxGetTranslation(const wxString& string, const wxString& domain = wxEmptyString); /** @@ -639,7 +787,7 @@ const wxString wxGetTranslation(const wxString& string, @header{wx/intl.h} */ -const wxString wxGetTranslation(const wxString& string, +const wxString& wxGetTranslation(const wxString& string, const wxString& plural, size_t n, const wxString& domain = wxEmptyString); @@ -653,7 +801,7 @@ const wxString wxGetTranslation(const wxString& string, @header{wx/intl.h} */ -const wxString _(const wxString& string); +const wxString& _(const wxString& string); //@} diff --git a/interface/wx/xlocale.h b/interface/wx/xlocale.h new file mode 100644 index 0000000000..bf26cb8712 --- /dev/null +++ b/interface/wx/xlocale.h @@ -0,0 +1,143 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: xlocale.h +// Purpose: interface of wxXLocale +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + @class wxXLocale + + 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: + @code wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) @endcode + 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). + + + @section xlocale_avail 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. + + + @section xlocale_func 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{misc} + + @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 + */ +}; diff --git a/misc/languages/genlang.py b/misc/languages/genlang.py index 878dfd37da..54617a8c42 100755 --- a/misc/languages/genlang.py +++ b/misc/languages/genlang.py @@ -23,15 +23,20 @@ def GenEnum(table): // --- --- --- generated code begins here --- --- --- -// This enum is generated by misc/languages/genlang.py -// When making changes, please put them into misc/languages/langtabl.txt +/** + The languages supported by wxLocale. + + This enum is generated by misc/languages/genlang.py + When making changes, please put them into misc/languages/langtabl.txt +*/ enum wxLanguage { - // user's default/preffered language as got from OS: - wxLANGUAGE_DEFAULT, - // unknown language, if wxLocale::GetSystemLanguage fails: - wxLANGUAGE_UNKNOWN, - + /// User's default/preffered language as got from OS. + wxLANGUAGE_DEFAULT, + + /// Unknown language, returned if wxLocale::GetSystemLanguage fails. + wxLANGUAGE_UNKNOWN, + """); knownLangs = [] for i in table: @@ -39,7 +44,7 @@ enum wxLanguage f.write(' %s,\n' % i[0]) knownLangs.append(i[0]) f.write(""" - // for custom, user-defined languages: + /// For custom, user-defined languages. wxLANGUAGE_USER_DEFINED }; @@ -49,41 +54,13 @@ enum wxLanguage f.close() -def GenDocs(table): - f = open('_wxlang.tex', 'wt') - f.write(""" - -%% --- --- --- generated code begins here --- --- --- - -%% This enum is generated by misc/languages/genlang.py -%% When making changes, please put them into misc/languages/langtabl.txt -\\begin{twocollist}\\itemsep=0pt -\\twocolitem{wxLANGUAGE\\_DEFAULT}{user's default language as obtained from the operating system} -\\twocolitem{wxLANGUAGE\\_UNKNOWN}{returned by \\helpref{GetSystemLanguage}{wxlocalegetsystemlanguage} if it fails to detect the default language} -\\twocolitem{wxLANGUAGE\\_USER\\_DEFINED}{user defined languages' integer identifiers should start from this} -"""); - knownLangs = [] - for i in table: - if i[0] not in knownLangs: - f.write('\\twocolitem{%s}{}\n' % (i[0].replace('_','\\_'))) - knownLangs.append(i[0]) - f.write("""\\end{twocollist}\itemsep=0pt - -%% --- --- --- generated code ends here --- --- --- - -""") - f.close() - - - - def GenTable(table): all_langs = [] all_sublangs = [] - + lngtable = '' - ifdefs = '' - + ifdefs = '' + for i in table: ican = '"%s"' % i[1] if ican == '"-"': ican = '""' @@ -106,7 +83,7 @@ def GenTable(table): if s != '0': ifdefs += '#ifndef %s\n#define %s (0)\n#endif\n' % (s, s) for s in all_sublangs: - if s != '0' and s != 'SUBLANG_DEFAULT': + if s != '0' and s != 'SUBLANG_DEFAULT': ifdefs += '#ifndef %s\n#define %s SUBLANG_DEFAULT\n#endif\n' % (s, s) f = open('_wxlang.cpp', 'wt') @@ -156,6 +133,5 @@ void wxLocale::InitLanguagesDB() table = ReadTable() -GenEnum(table) +GenEnum(table) # the enum is used also (thanks to doxygen) in the docs GenTable(table) -GenDocs(table) -- 2.45.2