X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..574be073c070a9bbe81ad68e98187b0b9e82c2df:/interface/wx/fontmap.h

diff --git a/interface/wx/fontmap.h b/interface/wx/fontmap.h
index 8adbc85135..104a5ec81a 100644
--- a/interface/wx/fontmap.h
+++ b/interface/wx/fontmap.h
@@ -8,7 +8,6 @@
 
 /**
     @class wxFontMapper
-    @wxheader{fontmap.h}
 
     wxFontMapper manages user-definable correspondence between logical font
     names and the fonts present on the machine.
@@ -25,31 +24,60 @@
 
     In case everything else fails (i.e. there is no record in config file
     and "interactive" is @false or user denied to choose any replacement),
-    the class queries wxEncodingConverter
-    for "equivalent" encodings (e.g. iso8859-2 and cp1250) and tries them.
+    the class queries wxEncodingConverter for "equivalent" encodings
+    (e.g. iso8859-2 and cp1250) and tries them.
+
+
+    @section fontmapper_mbconv Using wxFontMapper in conjunction with wxMBConv classes
+
+    If you need to display text in encoding which is not available at host
+    system (see wxFontMapper::IsEncodingAvailable), you may use these two
+    classes to find font in some similar encoding (see wxFontMapper::GetAltForEncoding)
+    and convert the text to this encoding (wxMBConv classes).
+    Following code snippet demonstrates it:
+
+    @code
+    if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename))
+    {
+        wxFontEncoding alternative;
+        if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative,
+                                                    facename, false))
+        {
+            wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc));
+            wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative));
+            text = wxString(text.mb_str(convFrom), convTo);
+        }
+        else
+            ...failure (or we may try iso8859-1/7bit ASCII)...
+    }
+    ...display text...
+    @endcode
 
     @library{wxcore}
-    @category{misc}
+    @category{cfg}
 
-    @see wxEncodingConverter, @ref overview_nonenglishoverview "Writing non-English
-    applications"
+    @see wxEncodingConverter, @ref overview_nonenglish
 */
 class wxFontMapper
 {
 public:
     /**
         Default ctor.
+
+        @note
+        The preferred way of creating a wxFontMapper instance is to call wxFontMapper::Get().
     */
     wxFontMapper();
 
     /**
-        Virtual dtor for a base class.
+        Virtual dtor.
     */
-    ~wxFontMapper();
+    virtual ~wxFontMapper();
 
     /**
         Returns the encoding for the given charset (in the form of RFC 2046) or
         @c wxFONTENCODING_SYSTEM if couldn't decode it.
+
         Be careful when using this function with @a interactive set to @true
         (default value) as the function then may show a dialog box to the user which
         may lead to unexpected reentrancies and may also take a significantly longer
@@ -57,21 +85,21 @@ public:
         idea to call this function from the event handlers for repeatedly generated
         events such as @c EVT_PAINT.
     */
-    wxFontEncoding CharsetToEncoding(const wxString& charset,
-                                     bool interactive = true);
+    virtual wxFontEncoding CharsetToEncoding(const wxString& charset,
+                                             bool interactive = true);
 
     /**
-        Get the current font mapper object. If there is no current object, creates
-        one.
+        Get the current font mapper object. If there is no current object, creates one.
 
         @see Set()
     */
     static wxFontMapper* Get();
 
     /**
-        Returns the array of all possible names for the given encoding. The array is
-        @NULL-terminated. IF it isn't empty, the first name in it is the canonical
-        encoding name, i.e. the same string as returned by
+        Returns the array of all possible names for the given encoding.
+
+        The array is @NULL-terminated. IF it isn't empty, the first name in it is
+        the canonical encoding name, i.e. the same string as returned by
         GetEncodingName().
     */
     static const wxChar** GetAllEncodingNames(wxFontEncoding encoding);
@@ -82,6 +110,7 @@ public:
         available on this system). If successful, return @true and fill info
         structure with the parameters required to create the font, otherwise
         return @false.
+
         The first form is for wxWidgets' internal use while the second one
         is better suitable for general use -- it returns wxFontEncoding which
         can consequently be passed to wxFont constructor.
@@ -97,9 +126,10 @@ public:
     //@}
 
     /**
-        Returns the @e n-th supported encoding. Together with
-        GetSupportedEncodingsCount()
-        this method may be used to get all supported encodings.
+        Returns the @e n-th supported encoding.
+
+        Together with GetSupportedEncodingsCount() this method may be used
+        to get all supported encodings.
     */
     static wxFontEncoding GetEncoding(size_t n);
 
@@ -109,27 +139,26 @@ public:
     static wxString GetEncodingDescription(wxFontEncoding encoding);
 
     /**
-        Return the encoding corresponding to the given internal name. This function is
-        the inverse of GetEncodingName() and is
-        intentionally less general than
-        CharsetToEncoding(), i.e. it doesn't
-        try to make any guesses nor ever asks the user. It is meant just as a way of
-        restoring objects previously serialized using
-        GetEncodingName().
+        Return the encoding corresponding to the given internal name.
+
+        This function is the inverse of GetEncodingName() and is intentionally
+        less general than CharsetToEncoding(), i.e. it doesn't try to make any
+        guesses nor ever asks the user. It is meant just as a way of restoring
+        objects previously serialized using GetEncodingName().
     */
     static wxFontEncoding GetEncodingFromName(const wxString& encoding);
 
     /**
         Return internal string identifier for the encoding (see also
-        wxFontMapper::GetEncodingDescription)
+        wxFontMapper::GetEncodingDescription).
 
         @see GetEncodingFromName()
     */
     static wxString GetEncodingName(wxFontEncoding encoding);
 
     /**
-        Returns the number of the font encodings supported by this class. Together with
-        GetEncoding() this method may be used to get
+        Returns the number of the font encodings supported by this class.
+        Together with GetEncoding() this method may be used to get
         all supported encodings.
     */
     static size_t GetSupportedEncodingsCount();
@@ -138,8 +167,8 @@ public:
         Check whether given encoding is available in given face or not.
         If no facename is given, find @e any font in this encoding.
     */
-    bool IsEncodingAvailable(wxFontEncoding encoding,
-                             const wxString& facename = wxEmptyString);
+    virtual bool IsEncodingAvailable(wxFontEncoding encoding,
+                                     const wxString& facename = wxEmptyString);
 
     /**
         Set the current font mapper object and return previous one (may be @NULL).
@@ -153,8 +182,8 @@ public:
     /**
         Set the config object to use (may be @NULL to use default).
         By default, the global one (from wxConfigBase::Get() will be used)
-        and the default root path for the config settings is the string returned by
-        GetDefaultConfigPath().
+        and the default root path for the config settings is the string returned
+        by GetDefaultConfigPath().
     */
     void SetConfig(wxConfigBase* config);