Implement monitoring of file descriptors in wxMotif event loop.

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

diff --git a/interface/wx/translation.h b/interface/wx/translation.h
index 2416dca5974c0b7df4879f2b7299cb0e2e7ffdf4..532dec723972b2e74246abc7c143c2ebb4d82d72 100644 (file)
--- a/interface/wx/translation.h
+++ b/interface/wx/translation.h
@@ -3,7 +3,7 @@
 // Purpose:     wxTranslation class
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     wxTranslation class
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -30,7 +30,7 @@
 
     @since 2.9.1
 
 
     @since 2.9.1
 

-    @see wxLocale
+    @see wxLocale, wxTranslationsLoader, wxFileTranslationsLoader

  */
 class wxTranslations
 {
  */
 class wxTranslations
 {


@@ -79,6 +79,64 @@ public:
      */
     void SetLanguage(const wxString& lang);
 
      */
     void SetLanguage(const wxString& lang);
 

+    /**
+        Returns list of all translations of @a domain that were found.
+
+        This method can be used e.g. to populate list of application's
+        translations offered to the user. To do this, pass the app's main
+        catalog as @a domain.
+
+        @see GetBestTranslation()
+     */
+    wxArrayString GetAvailableTranslations(const wxString& domain) const;
+
+    /**
+        Returns the best UI language for the @a domain.
+
+        The language is determined from the preferred UI language or languages
+        list the user configured in the OS. Notice that this may or may not
+        correspond to the default @em locale as obtained from
+        wxLocale::GetSystemLanguage(); modern operation systems (Windows
+        Vista+, OS X) have separate language and regional (= locale) settings.
+
+        @param domain
+            The catalog domain to look for.
+
+        @param msgIdLanguage
+            Specifies the language of "msgid" strings in source code
+            (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
+
+        @return Language code if a suitable match was found, empty string
+                otherwise.
+
+        @since 2.9.5
+     */
+    wxString GetBestTranslation(const wxString& domain, wxLanguage msgIdLanguage);
+
+    /**
+        Returns the best UI language for the @a domain.
+
+        The language is determined from the preferred UI language or languages
+        list the user configured in the OS. Notice that this may or may not
+        correspond to the default @em locale as obtained from
+        wxLocale::GetSystemLanguage(); modern operation systems (Windows
+        Vista+, OS X) have separate language and regional (= locale) settings.
+
+        @param domain
+            The catalog domain to look for.
+
+        @param msgIdLanguage
+            Specifies the language of "msgid" strings in source code
+            (i.e. arguments to GetString(), wxGetTranslation() and the _() macro).
+
+        @return Language code if a suitable match was found, empty string
+                otherwise.
+
+        @since 2.9.5
+     */
+    wxString GetBestTranslation(const wxString& domain,
+                                const wxString& msgIdLanguage = "en");
+

     /**
         Add standard wxWidgets catalogs ("wxstd" and possible port-specific
         catalogs).
     /**
         Add standard wxWidgets catalogs ("wxstd" and possible port-specific
         catalogs).


@@ -169,20 +227,6 @@ public:
      */
     bool IsLoaded(const wxString& domain) const;
 
      */
     bool IsLoaded(const wxString& domain) const;
 

-    /**
-        Directly loads catalog from a file.
-
-        It is caller's responsibility to ensure that the catalog contains
-        correct language. This function is primarily intended for
-        wxTranslationsLoader implementations.
-
-        @param filename  Name of the MO file to load.
-        @param domain    Domain to load the translations into (typically
-                         matches file's basename).
-     */
-    bool LoadCatalogFile(const wxString& filename,
-                         const wxString& domain = wxEmptyString);
-

     /**
         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).
     /**
         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).


@@ -226,7 +270,7 @@ public:
     */
     const wxString& GetString(const wxString& origString,
                               const wxString& origString2,
     */
     const wxString& GetString(const wxString& origString,
                               const wxString& origString2,

-                              size_t n,
+                              unsigned n,

                               const wxString& domain = wxEmptyString) const;
 
     /**
                               const wxString& domain = wxEmptyString) const;
 
     /**


@@ -258,16 +302,16 @@ public:
 class wxTranslationsLoader
 {
 public:
 class wxTranslationsLoader
 {
 public:

-    /// Constructor
-    wxTranslationsLoader() {}
+    /// Trivial default constructor.
+    wxTranslationsLoader();

 
     /**
         Called to load requested catalog.
 
 
     /**
         Called to load requested catalog.
 

-        If the catalog is found, LoadCatalog() should call LoadCatalogFile()
-        on @a translations to add the translation.
+        If the catalog is found, LoadCatalog() should create wxMsgCatalog
+        instance with its data and return it. The caller will take ownership
+        of the catalog.

 
 

-        @param translations  wxTranslations requesting loading.

         @param domain        Domain to load.
         @param lang          Language to look for. This is "canonical name"
                              (see wxLocale::GetCanonicalName()), i.e. ISO 639
         @param domain        Domain to load.
         @param lang          Language to look for. This is "canonical name"
                              (see wxLocale::GetCanonicalName()), i.e. ISO 639


@@ -275,10 +319,15 @@ public:
                              additional modifiers (e.g. "fr", "en_GB" or
                              "ca@valencia").
 
                              additional modifiers (e.g. "fr", "en_GB" or
                              "ca@valencia").
 

-        @return @true on successful load, @false otherwise
+        @return Loaded catalog or NULL on failure.
+     */
+    virtual wxMsgCatalog *LoadCatalog(const wxString& domain,
+                                      const wxString& lang) = 0;
+
+    /**
+        Implements wxTranslations::GetAvailableTranslations().

      */
      */

-    virtual bool LoadCatalog(wxTranslations *translations,
-                             const wxString& domain, const wxString& lang) = 0;
+    virtual wxArrayString GetAvailableTranslations(const wxString& domain) const = 0;

 };
 
 /**
 };
 
 /**


@@ -288,9 +337,11 @@ public:
     This is the default unless you change the loader with
     wxTranslations::SetLoader().
 
     This is the default unless you change the loader with
     wxTranslations::SetLoader().
 

-    Catalogs are 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().
+    Catalogs are searched for in standard places (system locales directory,
+    `LC_PATH` on Unix systems, Resources subdirectory of the application bundle
+    on OS X, executable's directory on Windows), but you may also prepend
+    additional directories to the search path with
+    AddCatalogLookupPathPrefix().

 
     @since 2.9.1
  */
 
     @since 2.9.1
  */


@@ -299,7 +350,7 @@ class wxFileTranslationsLoader : public wxTranslationsLoader
 public:
     /**
         Add a prefix to the catalog lookup path: the message catalog files will
 public:
     /**
         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
+        be looked up under prefix/lang/LC_MESSAGES and prefix/lang directories

         (in this order).
 
         This only applies to subsequent invocations of
         (in this order).
 
         This only applies to subsequent invocations of


@@ -335,7 +386,6 @@ public:
     This class is only available on Windows.
 
     @since 2.9.1
     This class is only available on Windows.
 
     @since 2.9.1

-

  */
 class wxResourceTranslationsLoader : public wxTranslationsLoader
 {
  */
 class wxResourceTranslationsLoader : public wxTranslationsLoader
 {


@@ -356,6 +406,42 @@ protected:
 };
 
 
 };
 
 

+/**
+    Represents a loaded translations message catalog.
+
+    This class should only be used directly by wxTranslationsLoader
+    implementations.
+
+    @since 2.9.1
+ */
+class wxMsgCatalog
+{
+public:
+    /**
+        Creates catalog loaded from a MO file.
+
+        @param filename  Path to the MO file to load.
+        @param domain    Catalog's domain. This typically matches
+                         the @a filename.
+
+        @return Successfully loaded catalog or NULL on failure.
+     */
+    static wxMsgCatalog *CreateFromFile(const wxString& filename,
+                                        const wxString& domain);
+
+    /**
+        Creates catalog from MO file data in memory buffer.
+
+        @param data      Data in MO file format.
+        @param domain    Catalog's domain. This typically matches
+                         the @a filename.
+
+        @return Successfully loaded catalog or NULL on failure.
+     */
+    static wxMsgCatalog *CreateFromData(const wxScopedCharBuffer& data,
+                                        const wxString& domain);
+};
+

 
 // ============================================================================
 // Global functions/macros
 
 // ============================================================================
 // Global functions/macros


@@ -431,12 +517,12 @@ protected:
     This function calls wxTranslations::GetString().
 
     @note This function is not suitable for literal strings in Unicode builds
     This function calls wxTranslations::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.
+          since the literal strings must be enclosed in 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&)
+    @see wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&)

 
     @header{wx/intl.h}
 */
 
     @header{wx/intl.h}
 */


@@ -466,17 +552,17 @@ const wxString& wxGetTranslation(const wxString& string,
     @header{wx/intl.h}
 */
 const wxString& wxGetTranslation(const wxString& string,
     @header{wx/intl.h}
 */
 const wxString& wxGetTranslation(const wxString& string,

-                                 const wxString& plural, size_t n,
+                                 const wxString& plural, unsigned n,

                                  const wxString& domain = wxEmptyString);
 
 /**
                                  const wxString& domain = wxEmptyString);
 
 /**

+    Macro to be used around all literal strings that should be translated.
+

     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.
 
     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);
     @header{wx/intl.h}
 */
 const wxString& _(const wxString& string);