X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..15fa4de377053c3c38f62593b2df941c217ea34b:/interface/wx/fontmap.h?ds=inline diff --git a/interface/wx/fontmap.h b/interface/wx/fontmap.h index 097fd17c37..7c1a27517b 100644 --- a/interface/wx/fontmap.h +++ b/interface/wx/fontmap.h @@ -3,7 +3,7 @@ // Purpose: interface of wxFontMapper // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -24,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 @@ -56,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); @@ -81,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. @@ -96,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); @@ -108,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(); @@ -137,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). @@ -152,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);