final f*h interface header reviews

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55891 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-09-25 20:00:31 +00:00
parent 0b70c946a3
commit 674d80a76f
8 changed files with 145 additions and 86 deletions

View File

@@ -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}
@see wxEncodingConverter, @ref overview_nonenglishoverview "Writing non-English
applications"
@see wxEncodingConverter, @ref overview_nonenglish "Writing non-English applications"
*/
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
@@ -60,17 +89,17 @@ public:
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();
@@ -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);