// Purpose: interface of wxFont
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
- Standard font families: these may be used only for the font creation, it
- doesn't make sense to query an existing font for its font family as,
- especially if the font had been created from a native font description, it
- may be unknown.
+ Standard font families: these are used mainly during wxFont creation to specify
+ the generic properties of the font without hardcoding in the sources a specific
+ face name.
+
+ wxFontFamily thus allows to group the font face names of fonts with similar
+ properties. Most wxWidgets ports use lists of fonts for each font family
+ inspired by the data taken from http://www.codestyle.org/css/font-family.
*/
enum wxFontFamily
{
wxFONTFAMILY_DEFAULT = wxDEFAULT, //!< Chooses a default font.
+
wxFONTFAMILY_DECORATIVE = wxDECORATIVE, //!< A decorative font.
wxFONTFAMILY_ROMAN = wxROMAN, //!< A formal, serif font.
wxFONTFAMILY_SCRIPT = wxSCRIPT, //!< A handwriting font.
wxFONTFAMILY_SWISS = wxSWISS, //!< A sans-serif font.
- wxFONTFAMILY_MODERN = wxMODERN, //!< A fixed pitch font.
- wxFONTFAMILY_TELETYPE = wxTELETYPE, //!< A teletype font.
+
+ /// A fixed pitch font. Note that wxFont currently does not make distinctions
+ /// between @c wxFONTFAMILY_MODERN and @c wxFONTFAMILY_TELETYPE.
+ wxFONTFAMILY_MODERN = wxMODERN,
+
+ /// A teletype (i.e. monospaced) font.
+ /// Monospace fonts have a fixed width like typewriters and often have strong angular
+ /// or block serifs. Monospace font faces are often used code samples and have a simple,
+ /// functional font style.
+ /// See also wxFont::IsFixedWidth() for an easy way to test for monospace property.
+ wxFONTFAMILY_TELETYPE = wxTELETYPE,
+
wxFONTFAMILY_MAX,
+ /// Invalid font family value, returned by wxFont::GetFamily() when the
+ /// font is invalid for example.
wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX
};
*/
enum wxFontStyle
{
+ /// The font is drawn without slant.
wxFONTSTYLE_NORMAL = wxNORMAL,
+
+ /// The font is slanted in an italic style.
wxFONTSTYLE_ITALIC = wxITALIC,
+
+ /// The font is slanted, but in a roman style.
+ /// Note that under wxMSW this style is the same as @c wxFONTSTYLE_ITALIC.
wxFONTSTYLE_SLANT = wxSLANT,
+
wxFONTSTYLE_MAX
};
wxFONTWEIGHT_MAX
};
+/**
+ Symbolic font sizes.
+
+ The elements of this enum correspond to CSS absolute size specifications,
+ see http://www.w3.org/TR/CSS21/fonts.html#font-size-props
+
+ @see wxFont::SetSymbolicSize()
+
+ @since 2.9.2
+ */
+enum wxFontSymbolicSize
+{
+ wxFONTSIZE_XX_SMALL = -3, //!< Extra small.
+ wxFONTSIZE_X_SMALL, //!< Very small.
+ wxFONTSIZE_SMALL, //!< Small.
+ wxFONTSIZE_MEDIUM, //!< Normal.
+ wxFONTSIZE_LARGE, //!< Large.
+ wxFONTSIZE_X_LARGE, //!< Very large.
+ wxFONTSIZE_XX_LARGE //!< Extra large.
+};
+
/**
The font flag bits for the new font ctor accepting one combined flags word.
*/
wxFONTFLAG_ANTIALIASED = 1 << 4,
wxFONTFLAG_NOT_ANTIALIASED = 1 << 5,
- /// underlined/strikethrough flags (default: no lines)
+ /// Underlined style (not underlined by default).
wxFONTFLAG_UNDERLINED = 1 << 6,
+
+ /// Strike-through style (only supported in wxMSW and wxGTK currently).
wxFONTFLAG_STRIKETHROUGH = 1 << 7,
/// the mask of all currently used flags
/**
Font encodings.
+
+ See wxFont::SetEncoding().
*/
enum wxFontEncoding
{
wxFONTENCODING_DEFAULT, // current default encoding
// ISO8859 standard defines a number of single-byte charsets
- wxFONTENCODING_ISO8859_1, // West European (Latin1)
- wxFONTENCODING_ISO8859_2, // Central and East European (Latin2)
- wxFONTENCODING_ISO8859_3, // Esperanto (Latin3)
- wxFONTENCODING_ISO8859_4, // Baltic (old) (Latin4)
- wxFONTENCODING_ISO8859_5, // Cyrillic
- wxFONTENCODING_ISO8859_6, // Arabic
- wxFONTENCODING_ISO8859_7, // Greek
- wxFONTENCODING_ISO8859_8, // Hebrew
- wxFONTENCODING_ISO8859_9, // Turkish (Latin5)
- wxFONTENCODING_ISO8859_10, // Variation of Latin4 (Latin6)
- wxFONTENCODING_ISO8859_11, // Thai
- wxFONTENCODING_ISO8859_12, // doesn't exist currently, but put it
- // here anyhow to make all ISO8859
- // consecutive numbers
- wxFONTENCODING_ISO8859_13, // Baltic (Latin7)
- wxFONTENCODING_ISO8859_14, // Latin8
- wxFONTENCODING_ISO8859_15, // Latin9 (a.k.a. Latin0, includes euro)
+ wxFONTENCODING_ISO8859_1, //!< West European (Latin1)
+ wxFONTENCODING_ISO8859_2, //!< Central and East European (Latin2)
+ wxFONTENCODING_ISO8859_3, //!< Esperanto (Latin3)
+ wxFONTENCODING_ISO8859_4, //!< Baltic (old) (Latin4)
+ wxFONTENCODING_ISO8859_5, //!< Cyrillic
+ wxFONTENCODING_ISO8859_6, //!< Arabic
+ wxFONTENCODING_ISO8859_7, //!< Greek
+ wxFONTENCODING_ISO8859_8, //!< Hebrew
+ wxFONTENCODING_ISO8859_9, //!< Turkish (Latin5)
+ wxFONTENCODING_ISO8859_10, //!< Variation of Latin4 (Latin6)
+ wxFONTENCODING_ISO8859_11, //!< Thai
+ wxFONTENCODING_ISO8859_12, //!< doesn't exist currently, but put it
+ //!< here anyhow to make all ISO8859
+ //!< consecutive numbers
+ wxFONTENCODING_ISO8859_13, //!< Baltic (Latin7)
+ wxFONTENCODING_ISO8859_14, //!< Latin8
+ wxFONTENCODING_ISO8859_15, //!< Latin9 (a.k.a. Latin0, includes euro)
wxFONTENCODING_ISO8859_MAX,
// Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
- wxFONTENCODING_KOI8, // KOI8 Russian
- wxFONTENCODING_KOI8_U, // KOI8 Ukrainian
- wxFONTENCODING_ALTERNATIVE, // same as MS-DOS CP866
- wxFONTENCODING_BULGARIAN, // used under Linux in Bulgaria
+ wxFONTENCODING_KOI8, //!< KOI8 Russian
+ wxFONTENCODING_KOI8_U, //!< KOI8 Ukrainian
+ wxFONTENCODING_ALTERNATIVE, //!< same as MS-DOS CP866
+ wxFONTENCODING_BULGARIAN, //!< used under Linux in Bulgaria
// what would we do without Microsoft? They have their own encodings
// for DOS
- wxFONTENCODING_CP437, // original MS-DOS codepage
- wxFONTENCODING_CP850, // CP437 merged with Latin1
- wxFONTENCODING_CP852, // CP437 merged with Latin2
- wxFONTENCODING_CP855, // another cyrillic encoding
- wxFONTENCODING_CP866, // and another one
+ wxFONTENCODING_CP437, //!< original MS-DOS codepage
+ wxFONTENCODING_CP850, //!< CP437 merged with Latin1
+ wxFONTENCODING_CP852, //!< CP437 merged with Latin2
+ wxFONTENCODING_CP855, //!< another cyrillic encoding
+ wxFONTENCODING_CP866, //!< and another one
// and for Windows
- wxFONTENCODING_CP874, // WinThai
- wxFONTENCODING_CP932, // Japanese (shift-JIS)
- wxFONTENCODING_CP936, // Chinese simplified (GB)
- wxFONTENCODING_CP949, // Korean (Hangul charset)
- wxFONTENCODING_CP950, // Chinese (traditional - Big5)
- wxFONTENCODING_CP1250, // WinLatin2
- wxFONTENCODING_CP1251, // WinCyrillic
- wxFONTENCODING_CP1252, // WinLatin1
- wxFONTENCODING_CP1253, // WinGreek (8859-7)
- wxFONTENCODING_CP1254, // WinTurkish
- wxFONTENCODING_CP1255, // WinHebrew
- wxFONTENCODING_CP1256, // WinArabic
- wxFONTENCODING_CP1257, // WinBaltic (same as Latin 7)
+ wxFONTENCODING_CP874, //!< WinThai
+ wxFONTENCODING_CP932, //!< Japanese (shift-JIS)
+ wxFONTENCODING_CP936, //!< Chinese simplified (GB)
+ wxFONTENCODING_CP949, //!< Korean (Hangul charset)
+ wxFONTENCODING_CP950, //!< Chinese (traditional - Big5)
+ wxFONTENCODING_CP1250, //!< WinLatin2
+ wxFONTENCODING_CP1251, //!< WinCyrillic
+ wxFONTENCODING_CP1252, //!< WinLatin1
+ wxFONTENCODING_CP1253, //!< WinGreek (8859-7)
+ wxFONTENCODING_CP1254, //!< WinTurkish
+ wxFONTENCODING_CP1255, //!< WinHebrew
+ wxFONTENCODING_CP1256, //!< WinArabic
+ wxFONTENCODING_CP1257, //!< WinBaltic (same as Latin 7)
+ wxFONTENCODING_CP1258, //!< WinVietnamese (since 2.9.4)
+ wxFONTENCODING_CP1361, //!< Johab Korean character set (since 2.9.4)
wxFONTENCODING_CP12_MAX,
- wxFONTENCODING_UTF7, // UTF-7 Unicode encoding
- wxFONTENCODING_UTF8, // UTF-8 Unicode encoding
- wxFONTENCODING_EUC_JP, // Extended Unix Codepage for Japanese
- wxFONTENCODING_UTF16BE, // UTF-16 Big Endian Unicode encoding
- wxFONTENCODING_UTF16LE, // UTF-16 Little Endian Unicode encoding
- wxFONTENCODING_UTF32BE, // UTF-32 Big Endian Unicode encoding
+ wxFONTENCODING_UTF7, //!< UTF-7 Unicode encoding
+ wxFONTENCODING_UTF8, //!< UTF-8 Unicode encoding
+ wxFONTENCODING_EUC_JP, //!< Extended Unix Codepage for Japanese
+ wxFONTENCODING_UTF16BE, //!< UTF-16 Big Endian Unicode encoding
+ wxFONTENCODING_UTF16LE, //!< UTF-16 Little Endian Unicode encoding
+ wxFONTENCODING_UTF32BE, //!< UTF-32 Big Endian Unicode encoding
wxFONTENCODING_UTF32LE, // UTF-32 Little Endian Unicode encoding
- wxFONTENCODING_MACROMAN, // the standard mac encodings
+ wxFONTENCODING_MACROMAN, //!< the standard mac encodings
wxFONTENCODING_MACJAPANESE,
wxFONTENCODING_MACCHINESETRAD,
wxFONTENCODING_MACKOREAN,
// more CJK encodings (for historical reasons some are already declared
// above)
- wxFONTENCODING_ISO2022_JP, // ISO-2022-JP JIS encoding
+ wxFONTENCODING_ISO2022_JP, //!< ISO-2022-JP JIS encoding
- wxFONTENCODING_MAX, // highest enumerated encoding value
+ wxFONTENCODING_MAX, //!< highest enumerated encoding value
wxFONTENCODING_MACMIN = wxFONTENCODING_MACROMAN ,
wxFONTENCODING_MACMAX = wxFONTENCODING_MACKEYBOARD ,
// aliases for endian-dependent UTF encodings
-#ifdef WORDS_BIGENDIAN
- wxFONTENCODING_UTF16 = wxFONTENCODING_UTF16BE, // native UTF-16
- wxFONTENCODING_UTF32 = wxFONTENCODING_UTF32BE, // native UTF-32
-#else // WORDS_BIGENDIAN
- wxFONTENCODING_UTF16 = wxFONTENCODING_UTF16LE, // native UTF-16
- wxFONTENCODING_UTF32 = wxFONTENCODING_UTF32LE, // native UTF-32
-#endif // WORDS_BIGENDIAN
-
- // alias for the native Unicode encoding on this platform
- // (this is used by wxEncodingConverter and wxUTFFile only for now)
-#if SIZEOF_WCHAR_T == 2
- wxFONTENCODING_UNICODE = wxFONTENCODING_UTF16,
-#else // SIZEOF_WCHAR_T == 4
- wxFONTENCODING_UNICODE = wxFONTENCODING_UTF32,
-#endif
-
- // alternative names for Far Eastern encodings
- // Chinese
- wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, // Simplified Chinese
- wxFONTENCODING_BIG5 = wxFONTENCODING_CP950, // Traditional Chinese
-
- // Japanese (see http://zsigri.tripod.com/fontboard/cjk/jis.html)
- wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932 // Shift JIS
+ wxFONTENCODING_UTF16, //!< native UTF-16
+ wxFONTENCODING_UTF32, //!< native UTF-32
+
+ /// Alias for the native Unicode encoding on this platform
+ /// (this is used by wxEncodingConverter and wxUTFFile only for now)
+ wxFONTENCODING_UNICODE,
+
+ wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese
+ wxFONTENCODING_BIG5 = wxFONTENCODING_CP950, //!< Traditional Chinese
+ wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932, //!< Shift JIS
+ wxFONTENCODING_EUC_KR = wxFONTENCODING_CP949, //!< Korean
+ wxFONTENCODING_JOHAB = wxFONTENCODING_CP1361, //!< Korean Johab (since 2.9.4)
+ wxFONTENCODING_VIETNAMESE = wxFONTENCODING_CP1258 //!< Vietnamese (since 2.9.4)
};
+/**
+ @class wxFontInfo
+
+ This class is a helper used for wxFont creation using named parameter
+ idiom: it allows to specify various wxFont attributes using the chained
+ calls to its clearly named methods instead of passing them in the fixed
+ order to wxFont constructors.
+
+ For example, to create an italic font with the given face name and size you
+ could use:
+ @code
+ wxFont font(wxFontInfo(12).FaceName("Helvetica").Italic());
+ @endcode
+
+ Notice that all of the methods of this object return a reference to the
+ object itself, allowing the calls to them to be chained as in the example
+ above.
+
+ All methods taking boolean parameters can be used to turn the specified
+ font attribute on or off and turn it on by default.
+
+ @since 2.9.5
+ */
+class wxFontInfo
+{
+public:
+ /**
+ Default constructor uses the default font size for the current
+ platform.
+ */
+ wxFontInfo();
+
+ /**
+ Constructor setting the font size in points to use.
+
+ @see wxFont::SetPointSize()
+ */
+ explicit wxFontInfo(int pointSize);
+
+ /**
+ Constructor setting the font size in pixels to use.
+
+ @see wxFont::SetPixelSize()
+ */
+ explicit wxFontInfo(const wxSize& pixelSize);
+
+ /**
+ Set the font family.
+
+ The family is a generic portable way of referring to fonts without
+ specifying a precise face name. This parameter must be one of the
+ ::wxFontFamily enumeration values.
+
+ If the FaceName() is used, then it overrides the font family.
+
+ @see wxFont::SetFamily()
+ */
+ wxFontInfo& Family(wxFontFamily family);
+
+ /**
+ Set the font face name to use.
+
+ Face names are not portable, so prefer to use Family() in portable
+ code.
+
+ @see wxFont::SetFaceName()
+ */
+ wxFontInfo& FaceName(const wxString& faceName);
+
+ /**
+ Use a bold version of the font.
+
+ @see ::wxFontWeight, wxFont::SetWeight()
+ */
+ wxFontInfo& Bold(bool bold = true);
+
+ /**
+ Use a lighter version of the font.
+
+ @see ::wxFontWeight, wxFont::SetWeight()
+ */
+ wxFontInfo& Light(bool light = true);
+
+ /**
+ Use an italic version of the font.
+
+ @see ::wxFontStyle, wxFont::SetStyle()
+ */
+ wxFontInfo& Italic(bool italic = true);
+
+ /**
+ Use a slanted version of the font.
+
+ @see ::wxFontStyle, wxFont::SetStyle()
+ */
+ wxFontInfo& Slant(bool slant = true);
+
+ /**
+ Set anti-aliasing flag.
+
+ Force the use of anti-aliasing on or off.
+
+ Currently this is not implemented, i.e. using this method doesn't do
+ anything.
+ */
+ wxFontInfo& AntiAliased(bool antiAliased = true);
+
+ /**
+ Use an underlined version of the font.
+ */
+ wxFontInfo& Underlined(bool underlined = true);
+
+ /**
+ Use a strike-through version of the font.
+
+ Currently this is only implemented in wxMSW and wxGTK.
+ */
+ wxFontInfo& Strikethrough(bool strikethrough = true);
+
+ /**
+ Set the font encoding to use.
+
+ This is mostly unneeded in Unicode builds of wxWidgets.
+
+ @see ::wxFontEncoding, wxFont::SetEncoding()
+ */
+ wxFontInfo& Encoding(wxFontEncoding encoding);
+
+ /**
+ Set all the font attributes at once.
+
+ See ::wxFontFlag for the various flags that can be used.
+ */
+ wxFontInfo& AllFlags(int flags);
+};
/**
@class wxFont
A font is an object which determines the appearance of text.
+
Fonts are used for drawing text to a device context, and setting the appearance
- of a window's text.
+ of a window's text, see wxDC::SetFont() and wxWindow::SetFont().
+
+ The easiest way to create a custom font is to use wxFontInfo object to
+ specify the font attributes and then use wxFont::wxFont(const wxFontInfo&)
+ constructor. Alternatively, you could start with one of the pre-defined
+ fonts or use wxWindow::GetFont() and modify the font, e.g. by increasing
+ its size using MakeLarger() or changing its weight using MakeBold().
This class uses @ref overview_refcount "reference counting and copy-on-write"
internally so that assignments between two instances of this class are very
class wxFont : public wxGDIObject
{
public:
- //@{
/**
Default ctor.
*/
wxFont(const wxFont& font);
/**
- Creates a font object with the specified attributes.
+ Creates a font object using the specified font description.
+
+ This is the preferred way to create font objects as using this ctor
+ results in more readable code and it is also extensible, e.g. it could
+ continue to be used if support for more font attributes is added in the
+ future. For example, this constructor provides the only way of creating
+ fonts with strike-through style.
+
+ Example of creating a font using this ctor:
+ @code
+ wxFont font(wxFontInfo(10).Bold().Underlined());
+ @endcode
+
+ @since 2.9.5
+ */
+ wxFont(const wxFontInfo& font);
+
+ /**
+ Creates a font object with the specified attributes and size in points.
+
+ Notice that the use of this constructor is often more verbose and less
+ readable than the use of constructor from wxFontInfo, e.g. the example
+ in that constructor documentation would need to be written as
+ @code
+ wxFont font(10, wxFONTFAMILY_DEFAULT, wxFONTSTYLE_NORMAL,
+ wxFONTWEIGHT_BOLD, true);
+ @endcode
+ which is longer and less clear.
@param pointSize
- Size in points.
+ Size in points. See SetPointSize() for more info.
@param family
- Font family, a generic way of referring to fonts without specifying actual
- facename. One of the ::wxFontFamily enumeration values.
+ The font family: a generic portable way of referring to fonts without specifying a
+ facename. This parameter must be one of the ::wxFontFamily enumeration values.
+ If the @a faceName argument is provided, then it overrides the font family.
@param style
- One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC.
+ One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
@param weight
- Font weight, sometimes also referred to as font boldness. One of
- the ::wxFontWeight enumeration values.
+ Font weight, sometimes also referred to as font boldness.
+ One of the ::wxFontWeight enumeration values.
@param underline
The value can be @true or @false.
At present this has an effect on Windows and Motif 2.x only.
@param faceName
- An optional string specifying the actual typeface to be used.
- If it is an empty string, a default typeface will be chosen based on the family.
+ An optional string specifying the face name to be used.
+ If it is an empty string, a default face name will be chosen based on the family.
@param encoding
An encoding which may be one of the enumeration values of ::wxFontEncoding.
Briefly these can be summed up as:
<TABLE>
- <TR><TD>wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
- <TR><TD>wxFONTENCODING_DEFAULT</TD><TD>
- Default application encoding: this
- is the encoding set by calls to
- SetDefaultEncoding and which may be set to,
- say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the
- default application encoding is the same as default system encoding.</TD></TR>
- <TR><TD>wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
- <TR><TD>wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
- <TR><TD>wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
+ <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
+ <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
+ Default application encoding: this is the encoding set by calls to
+ SetDefaultEncoding() and which may be set to, say, KOI8 to create all
+ fonts by default with KOI8 encoding. Initially, the default application
+ encoding is the same as default system encoding.</TD></TR>
+ <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
+ <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
+ <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
</TABLE>
If the specified encoding isn't available, no font is created
- (see also font encoding overview).
+ (see also @ref overview_fontencoding).
@remarks If the desired font does not exist, the closest match will be
chosen. Under Windows, only scalable TrueType fonts are used.
*/
- wxFont(int pointSize, wxFontFamily family, int style,
+ wxFont(int pointSize, wxFontFamily family, wxFontStyle style,
wxFontWeight weight,
- const bool underline = false,
- const wxString& faceName = "",
+ bool underline = false,
+ const wxString& faceName = wxEmptyString,
wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
/**
- Creates a font object with the specified attributes.
+ Creates a font object with the specified attributes and size in pixels.
+
+ Notice that the use of this constructor is often more verbose and less
+ readable than the use of constructor from wxFontInfo, consider using
+ that constructor instead.
@param pixelSize
- Size in pixels: this is directly supported only under MSW currently
- where this constructor can be used directly, under other platforms a
- font with the closest size to the given one is found using binary search
- and the static New method must be used.
+ Size in pixels. See SetPixelSize() for more info.
@param family
- Font family, a generic way of referring to fonts without specifying actual
- facename. One of ::wxFontFamily enumeration values.
+ The font family: a generic portable way of referring to fonts without specifying a
+ facename. This parameter must be one of the ::wxFontFamily enumeration values.
+ If the @a faceName argument is provided, then it overrides the font family.
@param style
- One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC.
+ One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
@param weight
Font weight, sometimes also referred to as font boldness.
One of the ::wxFontWeight enumeration values.
The value can be @true or @false.
At present this has an effect on Windows and Motif 2.x only.
@param faceName
- An optional string specifying the actual typeface to be used.
- If it is an empty string, a default typeface will be chosen based on the family.
+ An optional string specifying the face name to be used.
+ If it is an empty string, a default face name will be chosen based on the family.
@param encoding
An encoding which may be one of the enumeration values of ::wxFontEncoding.
Briefly these can be summed up as:
<TABLE>
- <TR><TD>wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
- <TR><TD>wxFONTENCODING_DEFAULT</TD><TD>
- Default application encoding: this
- is the encoding set by calls to
- SetDefaultEncoding and which may be set to,
- say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the
- default application encoding is the same as default system encoding.</TD></TR>
- <TR><TD>wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
- <TR><TD>wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
- <TR><TD>wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
+ <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
+ <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
+ Default application encoding: this is the encoding set by calls to
+ SetDefaultEncoding() and which may be set to, say, KOI8 to create all
+ fonts by default with KOI8 encoding. Initially, the default application
+ encoding is the same as default system encoding.</TD></TR>
+ <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
+ <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
+ <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
</TABLE>
If the specified encoding isn't available, no font is created
- (see also font encoding overview).
+ (see also @ref overview_fontencoding).
@remarks If the desired font does not exist, the closest match will be
chosen. Under Windows, only scalable TrueType fonts are used.
*/
wxFont(const wxSize& pixelSize, wxFontFamily family,
- int style, wxFontWeight weight,
- const bool underline = false,
- const wxString& faceName = "",
+ wxFontStyle style, wxFontWeight weight,
+ bool underline = false,
+ const wxString& faceName = wxEmptyString,
wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
- //@}
+
+ /**
+ Constructor from font description string.
+
+ This constructor uses SetNativeFontInfo() to initialize the font.
+ If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
+ will return @false.
+ */
+ wxFont(const wxString& nativeInfoString);
+
+ /**
+ Construct font from a native font info structure.
+ */
+ wxFont(const wxNativeFontInfo& nativeInfo);
/**
Destructor.
*/
virtual ~wxFont();
+
/**
- Returns the current application's default encoding.
+ @name Getters
+ */
+ //@{
- @see @ref overview_fontencoding, SetDefaultEncoding()
+ /**
+ Returns the encoding of this font.
+
+ Note that under wxGTK the returned value is always @c wxFONTENCODING_UTF8.
+
+ @see SetEncoding()
*/
- static wxFontEncoding GetDefaultEncoding();
+ virtual wxFontEncoding GetEncoding() const;
/**
- Returns the typeface name associated with the font, or the empty string if
- there is no typeface information.
+ Returns the face name associated with the font, or the empty string if
+ there is no face information.
@see SetFaceName()
*/
virtual wxString GetFaceName() const;
/**
- Gets the font family. See SetFamily() for a list of valid
- family identifiers.
+ Gets the font family if possible.
+
+ As described in ::wxFontFamily docs the returned value acts as a rough,
+ basic classification of the main font properties (look, spacing).
+
+ If the current font face name is not recognized by wxFont or by the
+ underlying system, @c wxFONTFAMILY_DEFAULT is returned.
+
+ Note that currently this function is not very precise and so not
+ particularly useful. Font families mostly make sense only for font
+ creation, see SetFamily().
@see SetFamily()
*/
- wxFontFamily GetFamily() const;
+ virtual wxFontFamily GetFamily() const;
/**
Returns the platform-dependent string completely describing this font.
- Returned string is always non-empty.
+
+ Returned string is always non-empty unless the font is invalid (in
+ which case an assert is triggered).
Note that the returned string is not meant to be shown or edited by the user: a
typical use of this function is for serializing in string-form a wxFont object.
- @see SetNativeFontInfo(),GetNativeFontInfoUserDesc()
+ @see SetNativeFontInfo(), GetNativeFontInfoUserDesc()
*/
wxString GetNativeFontInfoDesc() const;
/**
Returns a user-friendly string for this font object.
- Returned string is always non-empty.
+
+ Returned string is always non-empty unless the font is invalid (in
+ which case an assert is triggered).
+
+ The string does not encode all wxFont infos under all platforms;
+ e.g. under wxMSW the font family is not present in the returned string.
Some examples of the formats of returned strings (which are platform-dependent)
are in SetNativeFontInfoUserDesc().
- @see GetNativeFontInfoDesc()
+ @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()
*/
wxString GetNativeFontInfoUserDesc() const;
+ const wxNativeFontInfo *GetNativeFontInfo() const;
+
/**
Gets the point size.
virtual int GetPointSize() const;
/**
- Gets the font style. See wxFontStyle for a list of valid styles.
+ Gets the pixel size.
+
+ Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
+ a wxSize object with a null width value, you'll get a null width in
+ the returned object.
+
+ @see SetPixelSize()
+ */
+ virtual wxSize GetPixelSize() const;
+
+ /**
+ Gets the font style. See ::wxFontStyle for a list of valid styles.
@see SetStyle()
*/
- wxFontStyle GetStyle() const;
+ virtual wxFontStyle GetStyle() const;
/**
Returns @true if the font is underlined, @false otherwise.
virtual bool GetUnderlined() const;
/**
- Gets the font weight. See wxFontWeight for a list of valid weight identifiers.
+ Returns @true if the font is stricken-through, @false otherwise.
+
+ @see SetStrikethrough()
+
+ @since 2.9.4
+ */
+ virtual bool GetStrikethrough() const;
+
+ /**
+ Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
@see SetWeight()
*/
- wxFontWeight GetWeight() const;
+ virtual wxFontWeight GetWeight() const;
/**
Returns @true if the font is a fixed width (or monospaced) font,
@false if it is a proportional one or font is invalid.
+
+ Note that this function under some platforms is different than just testing
+ for the font family being equal to @c wxFONTFAMILY_TELETYPE because native
+ platform-specific functions are used for the check (resulting in a more
+ accurate return value).
*/
virtual bool IsFixedWidth() const;
*/
virtual bool IsOk() const;
+ //@}
+
+
+ /**
+ @name Similar fonts creation
+
+ The functions in this section either modify the font in place or create
+ a new font similar to the given one but with its weight, style or size
+ changed.
+ */
//@{
+
/**
- These functions take the same parameters as
- @ref wxFont::wxFont "wxFont constructors" and return a new font
- object allocated on the heap.
+ Returns a bold version of this font.
+
+ @see MakeBold()
+
+ @since 2.9.1
+ */
+ wxFont Bold() const;
+
+ /**
+ Returns an italic version of this font.
+
+ @see MakeItalic()
+
+ @since 2.9.1
+ */
+ wxFont Italic() const;
+
+ /**
+ Returns a larger version of this font.
+
+ The font size is multiplied by @c 1.2, the factor of @c 1.2 being
+ inspired by the W3C CSS specification.
+
+ @see MakeLarger(), Smaller(), Scaled()
+
+ @since 2.9.1
+ */
+ wxFont Larger() const;
+
+ /**
+ Returns a smaller version of this font.
+
+ The font size is divided by @c 1.2, the factor of @c 1.2 being
+ inspired by the W3C CSS specification.
+
+ @see MakeSmaller(), Larger(), Scaled()
- Using @c New() is currently the only way to directly create a font with
- the given size in pixels on platforms other than wxMSW.
+ @since 2.9.1
+ */
+ wxFont Smaller() const;
+
+ /**
+ Returns underlined version of this font.
+
+ @see MakeUnderlined()
+
+ @since 2.9.2
+ */
+ wxFont Underlined() const;
+
+ /**
+ Returns stricken-through version of this font.
+
+ Currently stricken-through fonts are only supported in wxMSW and wxGTK.
+
+ @see MakeStrikethrough()
+
+ @since 2.9.4
+ */
+ wxFont Strikethrough() const;
+
+ /**
+ Changes this font to be bold.
+
+ @see Bold()
+
+ @since 2.9.1
+ */
+ wxFont& MakeBold();
+
+ /**
+ Changes this font to be italic.
+
+ @see Italic()
+
+ @since 2.9.1
+ */
+ wxFont& MakeItalic();
+
+ /**
+ Changes this font to be larger.
+
+ The font size is multiplied by @c 1.2, the factor of @c 1.2 being
+ inspired by the W3C CSS specification.
+
+ @see Larger(), MakeSmaller(), Scale()
+
+ @since 2.9.1
+ */
+ wxFont& MakeLarger();
+
+ /**
+ Changes this font to be smaller.
+
+ The font size is divided by @c 1.2, the factor of @c 1.2 being
+ inspired by the W3C CSS specification.
+
+ @see Smaller(), MakeLarger(), Scale()
+
+ @since 2.9.1
+ */
+ wxFont& MakeSmaller();
+
+ /**
+ Changes this font to be underlined.
+
+ @see Underlined()
+
+ @since 2.9.2
+ */
+ wxFont& MakeUnderlined();
+
+ /**
+ Changes this font to be stricken-through.
+
+ Currently stricken-through fonts are only supported in wxMSW and wxGTK.
+
+ @see Strikethrough()
+
+ @since 2.9.4
*/
- static wxFont* New(int pointSize, wxFontFamily family, int style,
- wxFontWeight weight,
- const bool underline = false,
- const wxString& faceName = "",
- wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
- static wxFont* New(int pointSize, wxFontFamily family,
- int flags = wxFONTFLAG_DEFAULT,
- const wxString& faceName = "",
- wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
- static wxFont* New(const wxSize& pixelSize,
- wxFontFamily family,
- int style,
- wxFontWeight weight,
- const bool underline = false,
- const wxString& faceName = "",
- wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
- static wxFont* New(const wxSize& pixelSize,
- wxFontFamily family,
- int flags = wxFONTFLAG_DEFAULT,
- const wxString& faceName = "",
- wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+ wxFont& MakeStrikethrough();
+
+ /**
+ Changes the size of this font.
+
+ The font size is multiplied by the given factor (which may be less than
+ 1 to create a smaller version of the font).
+
+ @see Scaled(), MakeLarger(), MakeSmaller()
+
+ @since 2.9.1
+ */
+ wxFont& Scale(float x);
+
+ /**
+ Returns a scaled version of this font.
+
+ The font size is multiplied by the given factor (which may be less than
+ 1 to create a smaller version of the font).
+
+ @see Scale(), Larger(), Smaller()
+
+ @since 2.9.1
+ */
+ wxFont Scaled(float x) const;
+
//@}
/**
- Sets the default font encoding.
+ @name Setters
- @see @ref overview_fontencoding, GetDefaultEncoding()
+ These functions internally recreate the native font object with the new
+ specified property.
*/
- static void SetDefaultEncoding(wxFontEncoding encoding);
+ //@{
+
+ /**
+ Sets the encoding for this font.
+
+ Note that under wxGTK this function has no effect (because the underlying
+ Pango library always uses @c wxFONTENCODING_UTF8).
+
+ @see GetEncoding()
+ */
+ virtual void SetEncoding(wxFontEncoding encoding);
/**
Sets the facename for the font.
- Returns @true if the given face name exists; @false otherwise.
@param faceName
A valid facename, which should be on the end-user's system.
@remarks To avoid portability problems, don't rely on a specific face,
- but specify the font family instead or as well.
- A suitable font will be found on the end-user's system.
- If both the family and the facename are specified,
- wxWidgets will first search for the specific face, and
- then for a font belonging to the same family.
+ but specify the font family instead (see ::wxFontFamily and SetFamily()).
+
+ @return @true if the given face name exists; if the face name doesn't exist
+ in the user's system then the font is invalidated (so that IsOk() will
+ return @false) and @false is returned.
@see GetFaceName(), SetFamily()
*/
/**
Sets the font family.
+ As described in ::wxFontFamily docs the given @a family value acts as a rough,
+ basic indication of the main font properties (look, spacing).
+
+ Note that changing the font family results in changing the font face name.
+
@param family
One of the ::wxFontFamily values.
@see GetFamily(), SetFaceName()
*/
- void SetFamily(wxFontFamily family);
+ virtual void SetFamily(wxFontFamily family);
/**
Creates the font corresponding to the given native font description string
@beginTable
@hdr3col{platform, generic syntax, example}
- @row3col{wxGTK2, @c [FACE-NAME] [bold] [oblique|italic] [POINTSIZE], Monospace bold 10}
- @row3col{wxMSW, @c [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING], Tahoma 10 WINDOWS-1252}
+ @row3col{wxGTK2, <tt>[underlined] [strikethrough] [FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
+ @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
@endTable
@todo add an example for wxMac
For more detailed information about the allowed syntaxes you can look at the
documentation of the native API used for font-rendering
- (e.g. @c pango_font_description_from_string on GTK).
+ (e.g. @c pango_font_description_from_string under GTK, although notice
+ that it doesn't support the "underlined" and "strikethrough" attributes
+ and so those are handled by wxWidgets itself).
+
+ Note that unlike SetNativeFontInfo(), this function doesn't always restore all
+ attributes of the wxFont object under all platforms; e.g. on wxMSW the font family
+ is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW).
+ If you want to serialize/deserialize a font in string form, you should use
+ GetNativeFontInfoDesc() and SetNativeFontInfo() instead.
@see SetNativeFontInfo()
*/
bool SetNativeFontInfoUserDesc(const wxString& info);
+ void SetNativeFontInfo(const wxNativeFontInfo& info);
+
/**
Sets the point size.
+ The <em>point size</em> is defined as 1/72 of the Anglo-Saxon inch
+ (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
+
@param pointSize
Size in points.
*/
virtual void SetPointSize(int pointSize);
+ /**
+ Sets the pixel size.
+
+ The height parameter of @a pixelSize must be positive while the width
+ parameter may also be zero (to indicate that you're not interested in the
+ width of the characters: a suitable width will be chosen for best rendering).
+
+ This feature (specifying the font pixel size) is directly supported only
+ under wxMSW and wxGTK currently; under other platforms a font with the
+ closest size to the given one is found using binary search (this maybe slower).
+
+ @see GetPixelSize()
+ */
+ virtual void SetPixelSize(const wxSize& pixelSize);
+
/**
Sets the font style.
@see GetStyle()
*/
- void SetStyle(wxFontStyle style);
+ virtual void SetStyle(wxFontStyle style);
+
+ /**
+ Sets the font size using a predefined symbolic size name.
+
+ This function allows to change font size to be (very) large or small
+ compared to the standard font size.
+
+ @see SetSymbolicSizeRelativeTo().
+
+ @since 2.9.2
+ */
+ void SetSymbolicSize(wxFontSymbolicSize size);
+
+ /**
+ Sets the font size compared to the base font size.
+
+ This is the same as SetSymbolicSize() except that it uses the given
+ font size as the normal font size instead of the standard font size.
+
+ @since 2.9.2
+ */
+ void SetSymbolicSizeRelativeTo(wxFontSymbolicSize size, int base);
/**
Sets underlining.
@see GetUnderlined()
*/
- void SetUnderlined(const bool underlined);
+ virtual void SetUnderlined(bool underlined);
+
+ /**
+ Sets strike-through attribute of the font.
+
+ Currently stricken-through fonts are only supported in wxMSW and wxGTK.
+
+ @param strikethrough
+ @true to add strike-through style, @false to remove it.
+
+ @see GetStrikethrough()
+
+ @since 2.9.4
+ */
+ virtual void SetStrikethrough(bool strikethrough);
/**
Sets the font weight.
@see GetWeight()
*/
- void SetWeight(wxFontWeight weight);
+ virtual void SetWeight(wxFontWeight weight);
+
+ //@}
+
/**
Inequality operator.
Assignment operator, using @ref overview_refcount "reference counting".
*/
wxFont& operator =(const wxFont& font);
+
+
+ // statics
+
+ /**
+ Returns the current application's default encoding.
+
+ @see @ref overview_fontencoding, SetDefaultEncoding()
+ */
+ static wxFontEncoding GetDefaultEncoding();
+
+ /**
+ Sets the default font encoding.
+
+ @see @ref overview_fontencoding, GetDefaultEncoding()
+ */
+ static void SetDefaultEncoding(wxFontEncoding encoding);
+
+ //@{
+ /**
+ This function takes the same parameters as the relative
+ @ref wxFont::wxFont "wxFont constructor" and returns a new font
+ object allocated on the heap.
+
+ Their use is discouraged, use wxFont constructor from wxFontInfo
+ instead.
+ */
+ static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
+ wxFontWeight weight,
+ bool underline = false,
+ const wxString& faceName = wxEmptyString,
+ wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+ static wxFont* New(int pointSize, wxFontFamily family,
+ int flags = wxFONTFLAG_DEFAULT,
+ const wxString& faceName = wxEmptyString,
+ wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+ static wxFont* New(const wxSize& pixelSize,
+ wxFontFamily family,
+ wxFontStyle style,
+ wxFontWeight weight,
+ bool underline = false,
+ const wxString& faceName = wxEmptyString,
+ wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+ static wxFont* New(const wxSize& pixelSize,
+ wxFontFamily family,
+ int flags = wxFONTFLAG_DEFAULT,
+ const wxString& faceName = wxEmptyString,
+ wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
+
+
+ static wxFont *New(const wxNativeFontInfo& nativeInfo);
+ static wxFont *New(const wxString& nativeInfoString);
+
+ //@}
};
/**
Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
+
+ @see wxSystemSettings
*/
-wxFont wxNORMAL_FONT;
+wxFont* wxNORMAL_FONT;
/**
- A font using the wxFONTFAMILY_SWISS family and 2 points smaller than
+ A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
::wxNORMAL_FONT.
*/
-wxFont wxSMALL_FONT;
+wxFont* wxSMALL_FONT;
/**
- A font using the wxFONTFAMILY_ROMAN family and wxFONTSTYLE_ITALIC style and
+ A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
of the same size of ::wxNORMAL_FONT.
*/
-wxFont wxITALIC_FONT;
+wxFont* wxITALIC_FONT;
/**
A font identic to ::wxNORMAL_FONT except for the family used which is
- wxFONTFAMILY_SWISS.
+ @c wxFONTFAMILY_SWISS.
*/
-wxFont wxSWISS_FONT;
+wxFont* wxSWISS_FONT;
/**
@see wxFont
*/
-class wxFontList : public wxList
+class wxFontList
{
public:
/**
Finds a font of the given specification, or creates one and adds it to the
list. See the @ref wxFont "wxFont constructor" for details of the arguments.
*/
- wxFont* FindOrCreateFont(int point_size, int family, int style,
- int weight,
- bool underline = false,
- const wxString& facename = NULL,
+ wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
+ wxFontWeight weight, bool underline = false,
+ const wxString& facename = wxEmptyString,
wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
};
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */
//@{
/**
projects / wxWidgets.git / blobdiff