added GetEncodingFromName(); documented it and rearranged the methods in alphaabetical order

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

docs/latex/wx/fontmap.tex

@@ -67,6 +67,7 @@ No base class
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+
 \membersection{wxFontMapper::wxFontMapper}\label{wxfontmapperwxfontmapper}
 
 \func{}{wxFontMapper}{\void}
@@ -78,12 +79,29 @@ Default ctor.
 The preferred way of creating a wxFontMapper instance is to call 
 \helpref{wxFontMapper::Get}{wxfontmapperget}.
 
+
 \membersection{wxFontMapper::\destruct{wxFontMapper}}\label{wxfontmapperdtor}
 
 \func{}{\destruct{wxFontMapper}}{\void}
 
 Virtual dtor for a base class.
 
+
+\membersection{wxFontMapper::CharsetToEncoding}\label{wxfontmappercharsettoencoding}
+
+\func{wxFontEncoding}{CharsetToEncoding}{\param{const wxString\& }{charset}, \param{bool }{interactive = true}}
+
+Returns the encoding for the given charset (in the form of RFC 2046) or
+\texttt{wxFONTENCODING\_SYSTEM} if couldn't decode it.
+
+Be careful when using this function with \arg{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
+time than a simple function call. For these reasons, it is almost always a bad
+idea to call this function from the event handlers for repeatedly generated
+events such as \texttt{EVT\_PAINT}.
+
+
 \membersection{wxFontMapper::Get}\label{wxfontmapperget}
 
 \func{static wxFontMapper *}{Get}{\void}
@@ -95,6 +113,7 @@ one.
 
 \helpref{wxFontMapper::Set}{wxfontmapperset}
 
+
 \membersection{wxFontMapper::GetAltForEncoding}\label{wxfontmappergetaltforencoding}
 
 \func{bool}{GetAltForEncoding}{\param{wxFontEncoding }{encoding}, \param{wxNativeEncodingInfo* }{info}, \param{const wxString\& }{facename = wxEmptyString}, \param{bool }{interactive = true}}
@@ -110,19 +129,6 @@ The first form is for wxWindows' internal use while the second one
 is better suitable for general use -- it returns wxFontEncoding which
 can consequently be passed to wxFont constructor.
 
-\membersection{wxFontMapper::IsEncodingAvailable}\label{wxfontmapperisencodingavailable}
-
-\func{bool}{IsEncodingAvailable}{\param{wxFontEncoding }{encoding}, \param{const wxString\& }{facename = wxEmptyString}}
-
-Check whether given encoding is available in given face or not.
-If no facename is given, find {\it any} font in this encoding.
-
-\membersection{wxFontMapper::CharsetToEncoding}\label{wxfontmappercharsettoencoding}
-
-\func{wxFontEncoding}{CharsetToEncoding}{\param{const wxString\& }{charset}, \param{bool }{interactive = true}}
-
-Returns the encoding for the given charset (in the form of RFC 2046) or
-wxFONTENCODING\_SYSTEM if couldn't decode it.
 
 \membersection{wxFontMapper::GetEncoding}\label{wxfontmappergetencoding}
 
@@ -133,6 +139,26 @@ Returns the {\it n}-th supported encoding. Together with
 this method may be used to get all supported encodings.
 
 
+\membersection{wxFontMapper::GetEncodingDescription}\label{wxfontmappergetencodingdescription}
+
+\func{static wxString}{GetEncodingDescription}{\param{wxFontEncoding }{encoding}}
+
+Return user-readable string describing the given encoding.
+
+
+\membersection{wxFontMapper::GetEncodingFromName}\label{wxfontmappergetencodingfromname}
+
+\func{static wxFontEncoding}{GetEncodingFromName}{\param{const wxString\& }{encoding}}
+
+Return the encoding corresponding to the given internal name. This function is
+the inverse of \helpref{GetEncodingName}{wxfontmappergetencodingname} and is
+intentionally less general than 
+\helpref{CharsetToEncoding}{wxfontmappercharsettoencoding}, 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 
+\helpref{GetEncodingName}{wxfontmappergetencodingname}.
+
+
 \membersection{wxFontMapper::GetEncodingName}\label{wxfontmappergetencodingname}
 
 \func{static wxString}{GetEncodingName}{\param{wxFontEncoding }{encoding}}
@@ -140,11 +166,10 @@ this method may be used to get all supported encodings.
 Return internal string identifier for the encoding (see also 
 \helpref{GetEncodingDescription()}{wxfontmappergetencodingdescription})
 
-\membersection{wxFontMapper::GetEncodingDescription}\label{wxfontmappergetencodingdescription}
+\wxheading{See also}
 
-\func{static wxString}{GetEncodingDescription}{\param{wxFontEncoding }{encoding}}
+\helpref{GetEncodingFromName}{wxfontmappergetencodingfromname}
 
-Return user-readable string describing the given encoding.
 
 \membersection{wxFontMapper::GetSupportedEncodingsCount}\label{wxfontmappergetsupportedencodingscount}
 
@@ -155,18 +180,28 @@ Returns the number of the font encodings supported by this class. Together with
 all supported encodings.
 
 
+\membersection{wxFontMapper::IsEncodingAvailable}\label{wxfontmapperisencodingavailable}
+
+\func{bool}{IsEncodingAvailable}{\param{wxFontEncoding }{encoding}, \param{const wxString\& }{facename = wxEmptyString}}
+
+Check whether given encoding is available in given face or not.
+If no facename is given, find {\it any} font in this encoding.
+
+
 \membersection{wxFontMapper::SetDialogParent}\label{wxfontmappersetdialogparent}
 
 \func{void}{SetDialogParent}{\param{wxWindow* }{parent}}
 
 The parent window for modal dialogs.
 
+
 \membersection{wxFontMapper::SetDialogTitle}\label{wxfontmappersetdialogtitle}
 
 \func{void}{SetDialogTitle}{\param{const wxString\& }{title}}
 
 The title for the dialogs (note that default is quite reasonable).
 
+
 \membersection{wxFontMapper::Set}\label{wxfontmapperset}
 
 \func{static wxFontMapper *}{Set}{\param{wxFontMapper *}{mapper}}
@@ -179,6 +214,7 @@ into wxWindows.
 
 \helpref{wxFontMapper::Get}{wxfontmapperget}
 
+
 \membersection{wxFontMapper::SetConfig}\label{wxfontmappersetconfig}
 
 \func{void}{SetConfig}{\param{wxConfigBase* }{config}}
@@ -189,6 +225,7 @@ 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().
 
+
 \membersection{wxFontMapper::SetConfigPath}\label{wxfontmappersetconfigpath}
 
 \func{void}{SetConfigPath}{\param{const wxString\& }{prefix}}

include/wx/fontmap.h

@@ -94,6 +94,12 @@ public:
     // NB: hard-coded now, but might change later (read it from config?)
     static wxString GetEncodingDescription(wxFontEncoding encoding);
 
+    // find the encoding corresponding to the given name, inverse of
+    // GetEncodingName() and less general than CharsetToEncoding()
+    //
+    // returns wxFONTENCODING_MAX if the name is not a supported encoding
+    static wxFontEncoding GetEncodingFromName(const wxString& name);
+
 
     // functions which allow to configure the config object used: by default,
     // the global one (from wxConfigBase::Get() will be used) and the default
@@ -206,7 +212,9 @@ public:
                            bool interactive = true);
 
     // checks whether given encoding is available in given face or not.
-    // If no facename is given, 
+    //
+    // if no facename is given (default), return true if it's available in any
+    // facename at alll.
     virtual bool IsEncodingAvailable(wxFontEncoding encoding,
                                      const wxString& facename = wxEmptyString);
 

src/common/fmapbase.cpp

@@ -706,5 +706,26 @@ wxString wxFontMapperBase::GetEncodingName(wxFontEncoding encoding)
     return str;
 }
 
+/* static */
+wxFontEncoding wxFontMapperBase::GetEncodingFromName(const wxString& name)
+{
+    const size_t count = WXSIZEOF(gs_encodingNames);
+
+    for ( size_t i = 0; i < count; i++ )
+    {
+        if ( gs_encodingNames[i] == name )
+        {
+            return gs_encodings[i];
+        }
+    }
+
+    if ( name == _("default") )
+    {
+        return wxFONTENCODING_DEFAULT;
+    }
+
+    return wxFONTENCODING_MAX;
+}
+
 #endif // wxUSE_FONTMAP