X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/fadc2df6823d988f7a264b94e69a7e1bbcac1337..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/font.h diff --git a/interface/wx/font.h b/interface/wx/font.h index 3a405db322..d0a0b368a9 100644 --- a/interface/wx/font.h +++ b/interface/wx/font.h @@ -2,27 +2,42 @@ // Name: font.h // 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 }; @@ -31,9 +46,16 @@ enum wxFontFamily */ 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 }; @@ -48,6 +70,27 @@ enum wxFontWeight 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. */ @@ -68,8 +111,10 @@ enum wxFontFlag 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 @@ -87,6 +132,8 @@ enum wxFontFlag /** Font encodings. + + See wxFont::SetEncoding(). */ enum wxFontEncoding { @@ -97,63 +144,65 @@ 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, @@ -196,47 +245,179 @@ enum wxFontEncoding // 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 @@ -259,7 +440,6 @@ enum wxFontEncoding class wxFont : public wxGDIObject { public: - //@{ /** Default ctor. */ @@ -271,64 +451,93 @@ public: 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: - - - - - + + + + +
wxFONTENCODING_SYSTEMDefault system encoding.
wxFONTENCODING_DEFAULT - 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.
wxFONTENCODING_ISO8859_1...15ISO8859 encodings.
wxFONTENCODING_KOI8The standard Russian encoding for Internet.
wxFONTENCODING_CP1250...1252Windows encodings similar to ISO8859 (but not identical).
@c wxFONTENCODING_SYSTEMDefault system encoding.
@c wxFONTENCODING_DEFAULT + 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.
@c wxFONTENCODING_ISO8859_1...15ISO8859 encodings.
@c wxFONTENCODING_KOI8The standard Russian encoding for Internet.
@c wxFONTENCODING_CP1250...1252Windows encodings similar to ISO8859 (but not identical).
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. @@ -336,35 +545,47 @@ public: 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: - - - - - + + + + +
wxFONTENCODING_SYSTEMDefault system encoding.
wxFONTENCODING_DEFAULT - 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.
wxFONTENCODING_ISO8859_1...15ISO8859 encodings.
wxFONTENCODING_KOI8The standard Russian encoding for Internet.
wxFONTENCODING_CP1250...1252Windows encodings similar to ISO8859 (but not identical).
@c wxFONTENCODING_SYSTEMDefault system encoding.
@c wxFONTENCODING_DEFAULT + 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.
@c wxFONTENCODING_ISO8859_1...15ISO8859 encodings.
@c wxFONTENCODING_KOI8The standard Russian encoding for Internet.
@c wxFONTENCODING_CP1250...1252Windows encodings similar to ISO8859 (but not identical).
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. @@ -380,51 +601,77 @@ public: */ 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. @@ -433,11 +680,22 @@ public: 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. @@ -447,15 +705,29 @@ public: 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; @@ -464,58 +736,198 @@ public: */ 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() */ @@ -524,12 +936,17 @@ public: /** 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 @@ -554,23 +971,36 @@ public: @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, [underlined] [strikethrough] [FACE-NAME] [bold] [oblique|italic] [POINTSIZE], Monospace bold 10} + @row3col{wxMSW, [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING], 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 point size 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. @@ -578,6 +1008,21 @@ public: */ 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. @@ -586,7 +1031,29 @@ public: @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. @@ -596,7 +1063,21 @@ public: @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. @@ -606,7 +1087,10 @@ public: @see GetWeight() */ - void SetWeight(wxFontWeight weight); + virtual void SetWeight(wxFontWeight weight); + + //@} + /** Inequality operator. @@ -628,6 +1112,60 @@ public: 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); + + //@} }; @@ -638,26 +1176,28 @@ wxFont wxNullFont; /** 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; /** @@ -679,7 +1219,7 @@ wxFont wxSWISS_FONT; @see wxFont */ -class wxFontList : public wxList +class wxFontList { public: /** @@ -692,10 +1232,9 @@ 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); }; @@ -710,7 +1249,7 @@ wxFontList* wxTheFontList; // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_misc */ +/** @addtogroup group_funcmacro_misc */ //@{ /**