undo the last change as it results in buildbot configuration error

[wxWidgets.git] / interface / wx / intl.h

diff --git a/interface/wx/intl.h b/interface/wx/intl.h
index e0d3d4899a7ca320f38629658947b5d74eaf9cd6..f5d4c24722fdf882b2d870ed68f1094c71dd89aa 100644 (file)
--- a/interface/wx/intl.h
+++ b/interface/wx/intl.h
@@ -17,7 +17,7 @@
 */
 enum wxLanguage
 {
 */
 enum wxLanguage
 {

-    /// User's default/preffered language as got from OS.
+    /// User's default/preferred language as got from OS.

     wxLANGUAGE_DEFAULT,
 
     /// Unknown language, returned if wxLocale::GetSystemLanguage fails.
     wxLANGUAGE_DEFAULT,
 
     /// Unknown language, returned if wxLocale::GetSystemLanguage fails.


@@ -263,32 +263,150 @@ enum wxLanguage
 
 
 /**
 
 
 /**

-    wxLanguageInfo: encapsulates wxLanguage to OS native lang.desc.
-                    translation information
+    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 indentifier together with OS-specific information
+    related to that language.

 */
 struct WXDLLIMPEXP_BASE wxLanguageInfo
 {
 */
 struct WXDLLIMPEXP_BASE wxLanguageInfo
 {

-    /// wxLanguage id. It should be greater than wxLANGUAGE_USER_DEFINED.
+    /// ::wxLanguage id.
+    /// It should be greater than @c wxLANGUAGE_USER_DEFINED when defining your own
+    /// language info structure.

     int Language;
     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.
+
+    /// 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;
 
     wxLayoutDirection LayoutDirection;
 

-#ifdef __WXMSW__

     /// Return the LCID corresponding to this language.
     /// Return the LCID corresponding to this language.

+    /// @onlyfor{wxmsw}

     wxUint32 GetLCID() const;
     wxUint32 GetLCID() const;

-#endif // __WXMSW__

 
     /// Return the locale name corresponding to this language usable with
 
     /// Return the locale name corresponding to this language usable with

-    /// setlocale() on the current system
+    /// @c setlocale() on the current system.

     wxString GetLocaleName() const;
 };
 
 
     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
 
 /**
     @class wxLocale
 


@@ -339,7 +457,7 @@ struct WXDLLIMPEXP_BASE wxLanguageInfo
     @endWxPerlOnly
 
     @library{wxbase}
     @endWxPerlOnly
 
     @library{wxbase}

-    @category{misc}
+    @category{cfg}

 
     @see @ref overview_i18n, @ref page_samples_internat, wxXLocale
 */
 
     @see @ref overview_i18n, @ref page_samples_internat, wxXLocale
 */


@@ -381,7 +499,6 @@ public:
     */
     virtual ~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
     /**
         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


@@ -390,33 +507,50 @@ public:
         All loaded catalogs will be used for message lookup by GetString() for
         the current locale.
 
         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 @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.
-
-        @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
+        In this overload, @c 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_nonenglish.
         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_nonenglish.

+
+        @return
+            @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).

     */
     bool AddCatalog(const wxString& domain);
     */
     bool AddCatalog(const wxString& domain);

+
+    /**
+        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.
+
+        This overload takes two additional arguments, @a msgIdLanguage and @a msgIdCharset.
+
+        @param domain
+            The catalog domain to add.
+
+        @param 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.
+
+        @param 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.
+
+        @return
+            @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).
+    */

     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage,
                     const wxString& msgIdCharset);
     bool AddCatalog(const wxString& domain, wxLanguage msgIdLanguage,
                     const wxString& msgIdCharset);

-    //@}

 
     /**
         Add a prefix to the catalog lookup path: the message catalog files will
 
     /**
         Add a prefix to the catalog lookup path: the message catalog files will


@@ -445,7 +579,7 @@ public:
 
         @see GetLanguageInfo()
     */
 
         @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
 
     /**
         Returns the canonical form of current locale name. Canonical form is the


@@ -469,10 +603,10 @@ public:
                             const wxString& domain = wxEmptyString) const;
 
     /**
                             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
 
         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;
 
     */
     int GetLanguage() const;
 


@@ -486,7 +620,7 @@ public:
         as an argument to this function and in this case the result of
         GetSystemLanguage() is used.
     */
         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
 
     /**
         Returns English name of the given language or empty string if this


@@ -494,7 +628,7 @@ public:
 
         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;
+    static wxString GetLanguageName(int lang);

 
     /**
         Returns the locale name as passed to the constructor or Init().
 
     /**
         Returns the locale name as passed to the constructor or Init().


@@ -520,8 +654,8 @@ public:
         @remarks Domains are searched in the last to first order, i.e. catalogs
                  added later override those added before.
     */
         @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;
+    virtual 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
 
     /**
         Retrieves the translation for a string in all loaded domains unless the @a domain


@@ -550,10 +684,9 @@ public:
         @remarks Domains are searched in the last to first order, i.e. catalogs
                  added later override those added before.
     */
         @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& origString2,
-                              size_t n,
-                              const wxString& domain = wxEmptyString) const;
+    virtual 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().
 
     /**
         Returns current platform-specific locale name as passed to setlocale().


@@ -566,7 +699,7 @@ public:
         Returns wxFontEncoding() value or @c 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.
 
     /**
         Tries to detect the name of the user's default font encoding.


@@ -576,14 +709,32 @@ public:
         Returns a user-readable string value or an empty string if it couldn't be
         determined.
     */
         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.
 
     /**
         Tries to detect the user's default language setting.

-        Returns wxLanguage value or @b wxLANGUAGE_UNKNOWN if the language-guessing
+
+        Returns the ::wxLanguage value or @c wxLANGUAGE_UNKNOWN if the language-guessing

         algorithm failed.
     */
         algorithm failed.
     */

-    static int GetSystemLanguage() const;
+    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.
 
     /**
         Initializes the wxLocale instance.


@@ -597,7 +748,7 @@ public:
         try to translate the messages using the message catalogs for this locale.
 
         @param language
         try to translate the messages using the message catalogs for this locale.
 
         @param language

-            wxLanguage identifier of the locale.
+            ::wxLanguage identifier of the locale.

             @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's
             default language (see GetSystemLanguage()).
         @param flags
             @c wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's
             default language (see GetSystemLanguage()).
         @param flags


@@ -640,10 +791,8 @@ public:
             and windows-1250.
             See @ref overview_nonenglish for detailed description of this behaviour.
     */
             and windows-1250.
             See @ref overview_nonenglish for detailed description of this behaviour.
     */

-    bool Init(const wxString& name,
-              const wxString& short = wxEmptyString,
-              const wxString& locale = wxEmptyString,
-              bool bLoadDefault = true,
+    bool Init(const wxString& name, const wxString& short = wxEmptyString,
+              const wxString& locale = wxEmptyString, bool bLoadDefault = true,

               bool bConvertEncoding = false);
 
     /**
               bool bConvertEncoding = false);
 
     /**


@@ -651,11 +800,11 @@ public:
         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.
         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.
     */
 
         @since 2.7.1.
     */


@@ -669,7 +818,7 @@ public:
 
         @see AddCatalog()
     */
 
         @see AddCatalog()
     */

-    bool IsLoaded(const char* domain) const;
+    bool IsLoaded(const wxString& domain) const;

 
     /**
         Returns @true if the locale could be set successfully.
 
     /**
         Returns @true if the locale could be set successfully.


@@ -684,7 +833,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_string */
+/** @addtogroup group_funcmacro_string */

 //@{
 
 /**
 //@{
 
 /**