Add wxTranslations::GetTranslatedString().

Replace GetString(), which always returns something (possibly the
original string) with GetTranslatedString() that returns either a
pointer to translated string or NULL.

This simplifies the code a bit, all handling of missing translations is
now done in wxGetTranslation().

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@74836 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/translation.h

@@ -153,12 +153,11 @@ public:
     bool IsLoaded(const wxString& domain) const;
 
     // access to translations
-    const wxString& GetString(const wxString& origString,
+    const wxString *GetTranslatedString(const wxString& origString,
-                              const wxString& domain = wxEmptyString) const;
+                                        const wxString& domain = wxEmptyString) const;
-    const wxString& GetString(const wxString& origString,
+    const wxString *GetTranslatedString(const wxString& origString,
-                              const wxString& origString2,
+                                        unsigned n,
-                              unsigned n,
+                                        const wxString& domain = wxEmptyString) const;
-                              const wxString& domain = wxEmptyString) const;
 
     wxString GetHeaderValue(const wxString& header,
                             const wxString& domain = wxEmptyString) const;
@@ -242,11 +241,13 @@ protected:
 
 // get the translation of the string in the current locale
 inline const wxString& wxGetTranslation(const wxString& str,
-                                        const wxString& domain = wxEmptyString)
+                                        const wxString& domain = wxString())
 {
     wxTranslations *trans = wxTranslations::Get();
-    if ( trans )
+    const wxString *transStr = trans ? trans->GetTranslatedString(str, domain)
-        return trans->GetString(str, domain);
+                                     : NULL;
+    if ( transStr )
+        return *transStr;
     else
         // NB: this function returns reference to a string, so we have to keep
         //     a copy of it somewhere
@@ -256,11 +257,13 @@ inline const wxString& wxGetTranslation(const wxString& str,
 inline const wxString& wxGetTranslation(const wxString& str1,
                                         const wxString& str2,
                                         unsigned n,
-                                        const wxString& domain = wxEmptyString)
+                                        const wxString& domain = wxString())
 {
     wxTranslations *trans = wxTranslations::Get();
-    if ( trans )
+    const wxString *transStr = trans ? trans->GetTranslatedString(str1, n, domain)
-        return trans->GetString(str1, str2, n, domain);
+                                     : NULL;
+    if ( transStr )
+        return *transStr;
     else
         // NB: this function returns reference to a string, so we have to keep
         //     a copy of it somewhere

interface/wx/intl.h

@@ -354,13 +354,13 @@ public:
     const wxString& GetName() const;
 
     /**
-        Calls wxTranslations::GetString(const wxString&, const wxString&) const.
+        Calls wxGetTranslation(const wxString&, const wxString&).
     */
     virtual const wxString& GetString(const wxString& origString,
                                       const wxString& domain = wxEmptyString) const;
 
     /**
-        Calls wxTranslations::GetString(const wxString&, const wxString&, unsigned, const wxString&) const.
+        Calls wxGetTranslation(const wxString&, const wxString&, unsigned, const wxString&).
     */
     virtual const wxString& GetString(const wxString& origString,
                                       const wxString& origString2, unsigned n,

interface/wx/translation.h

@@ -230,38 +230,33 @@ public:
         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
+        Returns @NULL if translation is not available.
-        error message is generated the first time a string is not found; use
-        wxLogNull to suppress it).
 
         This function is thread-safe.
 
         @remarks Domains are searched in the last to first order, i.e. catalogs
                  added later override those added before.
+
+        @since 3.0
     */
-    const wxString& GetString(const wxString& origString,
+    const wxString *GetTranslatedString(const wxString& origString,
-                              const wxString& domain = wxEmptyString) const;
+                                        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
+        Returns @NULL if translation is not available.
-        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.
+        @param origString  The singular form of the string to be converted.
-        The @a origString2 parameter is the plural form (in English).
+        @param n           The number on which the plural form choice depends on.
-
+                           (In some languages, there are different plural forms
-        The parameter @a n is used to determine the plural form.
+                           for e.g. n=2 and n=3 etc., in addition to the singlular
-        If no message catalog is found @a origString is returned if 'n == 1',
+                           form (n=1) being different.)
-        otherwise @a origString2.
 
         See GNU gettext manual for additional information on plural forms handling.
         This method is called by the wxGetTranslation() function and _() macro.
@@ -270,11 +265,12 @@ public:
 
         @remarks Domains are searched in the last to first order, i.e. catalogs
                  added later override those added before.
+
+        @since 3.0
     */
-    const wxString& GetString(const wxString& origString,
+    const wxString *GetTranslatedString(const wxString& origString,
-                              const wxString& origString2,
+                                        unsigned n,
-                              unsigned n,
+                                        const wxString& domain = wxEmptyString) const;
-                              const wxString& domain = wxEmptyString) const;
 
     /**
         Returns the header value for header @a header.
@@ -517,8 +513,6 @@ public:
     provided: the _() macro is defined to do the same thing as
     wxGetTranslation().
 
-    This function calls wxTranslations::GetString().
-
     This function is thread-safe.
 
     @note This function is not suitable for literal strings in Unicode builds
@@ -552,8 +546,6 @@ const wxString& wxGetTranslation(const wxString& string,
     <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
     For a shorter alternative see the wxPLURAL() macro.
 
-    This function calls wxTranslation::GetString().
-
     This function is thread-safe.
 
     @header{wx/intl.h}

src/common/translation.cpp

@@ -1618,19 +1618,18 @@ const wxString& wxTranslations::GetUntranslatedString(const wxString& str)
 }
 
 
-const wxString& wxTranslations::GetString(const wxString& origString,
+const wxString *wxTranslations::GetTranslatedString(const wxString& origString,
-                                          const wxString& domain) const
+                                                    const wxString& domain) const
 {
-    return GetString(origString, origString, UINT_MAX, domain);
+    return GetTranslatedString(origString, UINT_MAX, domain);
 }
 
-const wxString& wxTranslations::GetString(const wxString& origString,
+const wxString *wxTranslations::GetTranslatedString(const wxString& origString,
-                                          const wxString& origString2,
+                                                    unsigned n,
-                                          unsigned n,
+                                                    const wxString& domain) const
-                                          const wxString& domain) const
 {
     if ( origString.empty() )
-        return GetUntranslatedString(origString);
+        return NULL;
 
     const wxString *trans = NULL;
     wxMsgCatalog *pMsgCat;
@@ -1665,14 +1664,9 @@ const wxString& wxTranslations::GetString(const wxString& origString,
             (!domain.empty() ? wxString::Format("domain '%s' ", domain) : wxString()),
             m_lang
         );
-
-        if (n == UINT_MAX)
-            return GetUntranslatedString(origString);
-        else
-            return GetUntranslatedString(n == 1 ? origString : origString2);
     }
 
-    return *trans;
+    return trans;
 }