Fix typo in wxStandardPathsBase::ResourceCat description and document it.

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

diff --git a/interface/wx/translation.h b/interface/wx/translation.h
index 3e96b37b70f92edb92a97b40f13216c284a722d5..919121cce701175bbd5fc921e65d2e9519f49a04 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$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -79,6 +79,15 @@ public:
      */
     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.
+     */
+    wxArrayString GetAvailableTranslations(const wxString& domain) const;
+
     /**
         Add standard wxWidgets catalogs ("wxstd" and possible port-specific
         catalogs).
@@ -169,20 +178,6 @@ public:
      */
     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).
@@ -264,10 +259,10 @@ public:
     /**
         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
@@ -275,10 +270,15 @@ public:
                              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;
 };
 
 /**
@@ -335,7 +335,6 @@ public:
     This class is only available on Windows.
 
     @since 2.9.1
-
  */
 class wxResourceTranslationsLoader : public wxTranslationsLoader
 {
@@ -356,6 +355,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