Fix wrong wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK name in the docs.

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

diff --git a/interface/wx/translation.h b/interface/wx/translation.h
index 0e102ee704fd70dfeac2a7ab581b49ecc0d4b682..e0f258794004eecabb0bf888d955ed9c8652262d 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

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


@@ -58,7 +58,7 @@ public:
 
         Deletes previous loader and takes ownership of @a loader.
 
 
         Deletes previous loader and takes ownership of @a loader.
 

-        @see wxTranslationsLoader, wxFileTranslationsLoader
+        @see wxTranslationsLoader, wxFileTranslationsLoader, wxResourceTranslationsLoader

      */
     void SetLoader(wxTranslationsLoader *loader);
 
      */
     void SetLoader(wxTranslationsLoader *loader);
 


@@ -79,6 +79,15 @@ 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.
+     */
+    wxArrayString GetAvailableTranslations(const wxString& domain) const;
+

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


@@ -169,20 +178,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 +221,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;
 
     /**


@@ -251,21 +246,23 @@ public:
 
     Implementations must implement the LoadCatalog() method.
 
 
     Implementations must implement the LoadCatalog() method.
 

-    @see wxFileTranslationsLoader
+    @see wxFileTranslationsLoader, wxResourceTranslationsLoader
+
+    @since 2.9.1

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


@@ -273,10 +270,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;

 };
 
 /**
 };
 
 /**


@@ -289,6 +291,8 @@ public:
     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 (current directory first, then
     the system one), but you may also prepend additional directories to the
     search path with AddCatalogLookupPathPrefix().

+
+    @since 2.9.1

  */
 class wxFileTranslationsLoader : public wxTranslationsLoader
 {
  */
 class wxFileTranslationsLoader : public wxTranslationsLoader
 {


@@ -304,6 +308,88 @@ public:
     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 };
 
     static void AddCatalogLookupPathPrefix(const wxString& prefix);
 };
 

+/**
+    This loader makes it possible to load translations from Windows
+    resources.
+
+    If you wish to store translation MO files in resources, you have to
+    enable this loader before calling wxTranslations::AddCatalog() or
+    wxLocale::AddCatalog():
+
+    @code
+    wxTranslations::Get()->SetLoader(new wxResourceTranslationsLoader);
+    @endcode
+
+    Translations are stored in resources as compiled MO files, with type
+    set to "MOFILE" (unless you override GetResourceType()) and name
+    consisting of the domain, followed by underscore, followed by language
+    identification. For example, the relevant part of .rc file would look
+    like this:
+
+    @code
+    myapp_de     MOFILE   "catalogs/de/myapp.mo"
+    myapp_fr     MOFILE   "catalogs/fr/myapp.mo"
+    myapp_en_GB  MOFILE   "catalogs/en_GB/myapp.mo"
+    @endcode
+
+    This class is only available on Windows.
+
+    @since 2.9.1
+ */
+class wxResourceTranslationsLoader : public wxTranslationsLoader
+{
+protected:
+    /**
+        Returns resource type to use for translations.
+
+        Default type is "MOFILE".
+     */
+    virtual wxString GetResourceType() const;
+
+    /**
+        Returns handle of the module to load resources from.
+
+        By default, the main executable is used.
+     */
+    virtual WXHINSTANCE GetModule() const;
+};
+
+
+/**
+    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);
+};

 
 
 // ============================================================================
 
 
 // ============================================================================


@@ -380,12 +466,12 @@ public:
     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}
 */


@@ -415,17 +501,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);