interface/wx/font.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        font.h
   3 // Purpose:     interface of wxFont
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 /**
  10     Standard font families: these are used mainly during wxFont creation to specify
  11     the generic properties of the font without hardcoding in the sources a specific
  12     face name.
  13
  14     wxFontFamily thus allows to group the font face names of fonts with similar
  15     properties. Most wxWidgets ports use lists of fonts for each font family
  16     inspired by the data taken from http://www.codestyle.org/css/font-family.
  17 */
  18 enum wxFontFamily
  19 {
  20     wxFONTFAMILY_DEFAULT = wxDEFAULT,           //!< Chooses a default font.
  21
  22     wxFONTFAMILY_DECORATIVE = wxDECORATIVE,     //!< A decorative font.
  23     wxFONTFAMILY_ROMAN = wxROMAN,               //!< A formal, serif font.
  24     wxFONTFAMILY_SCRIPT = wxSCRIPT,             //!< A handwriting font.
  25     wxFONTFAMILY_SWISS = wxSWISS,               //!< A sans-serif font.
  26
  27     /// A fixed pitch font. Note that wxFont currently does not make distinctions
  28     /// between @c wxFONTFAMILY_MODERN and @c wxFONTFAMILY_TELETYPE.
  29     wxFONTFAMILY_MODERN = wxMODERN,
  30
  31     /// A teletype (i.e. monospaced) font.
  32     /// Monospace fonts have a fixed width like typewriters and often have strong angular
  33     /// or block serifs. Monospace font faces are often used code samples and have a simple,
  34     /// functional font style.
  35     /// See also wxFont::IsFixedWidth() for an easy way to test for monospace property.
  36     wxFONTFAMILY_TELETYPE = wxTELETYPE,
  37
  38     wxFONTFAMILY_MAX,
  39     /// Invalid font family value, returned by wxFont::GetFamily() when the
  40     /// font is invalid for example.
  41     wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX
  42 };
  43
  44 /**
  45     Font styles.
  46 */
  47 enum wxFontStyle
  48 {
  49     /// The font is drawn without slant.
  50     wxFONTSTYLE_NORMAL = wxNORMAL,
  51
  52     /// The font is slanted in an italic style.
  53     wxFONTSTYLE_ITALIC = wxITALIC,
  54
  55     /// The font is slanted, but in a roman style.
  56     /// Note that under wxMSW this style is the same as @c wxFONTSTYLE_ITALIC.
  57     wxFONTSTYLE_SLANT = wxSLANT,
  58
  59     wxFONTSTYLE_MAX
  60 };
  61
  62 /**
  63     Font weights.
  64 */
  65 enum wxFontWeight
  66 {
  67     wxFONTWEIGHT_NORMAL = wxNORMAL,  //!< Normal font.
  68     wxFONTWEIGHT_LIGHT = wxLIGHT,    //!< Light font.
  69     wxFONTWEIGHT_BOLD = wxBOLD,      //!< Bold font.
  70     wxFONTWEIGHT_MAX
  71 };
  72
  73 /**
  74     Symbolic font sizes.
  75
  76     The elements of this enum correspond to CSS absolute size specifications,
  77     see http://www.w3.org/TR/CSS21/fonts.html#font-size-props
  78
  79     @see wxFont::SetSymbolicSize()
  80
  81     @since 2.9.2
  82  */
  83 enum wxFontSymbolicSize
  84 {
  85     wxFONTSIZE_XX_SMALL = -3,   //!< Extra small.
  86     wxFONTSIZE_X_SMALL,         //!< Very small.
  87     wxFONTSIZE_SMALL,           //!< Small.
  88     wxFONTSIZE_MEDIUM,          //!< Normal.
  89     wxFONTSIZE_LARGE,           //!< Large.
  90     wxFONTSIZE_X_LARGE,         //!< Very large.
  91     wxFONTSIZE_XX_LARGE         //!< Extra large.
  92 };
  93
  94 /**
  95     The font flag bits for the new font ctor accepting one combined flags word.
  96 */
  97 enum wxFontFlag
  98 {
  99     /// no special flags: font with default weight/slant/anti-aliasing
 100     wxFONTFLAG_DEFAULT          = 0,
 101
 102     /// slant flags (default: no slant)
 103     wxFONTFLAG_ITALIC           = 1 << 0,
 104     wxFONTFLAG_SLANT            = 1 << 1,
 105
 106     /// weight flags (default: medium)
 107     wxFONTFLAG_LIGHT            = 1 << 2,
 108     wxFONTFLAG_BOLD             = 1 << 3,
 109
 110     /// anti-aliasing flag: force on or off (default: the current system default)
 111     wxFONTFLAG_ANTIALIASED      = 1 << 4,
 112     wxFONTFLAG_NOT_ANTIALIASED  = 1 << 5,
 113
 114     /// Underlined style (not underlined by default).
 115     wxFONTFLAG_UNDERLINED       = 1 << 6,
 116
 117     /// Strike-through style (only supported in wxMSW and wxGTK currently).
 118     wxFONTFLAG_STRIKETHROUGH    = 1 << 7,
 119
 120     /// the mask of all currently used flags
 121     wxFONTFLAG_MASK = wxFONTFLAG_ITALIC             |
 122                       wxFONTFLAG_SLANT              |
 123                       wxFONTFLAG_LIGHT              |
 124                       wxFONTFLAG_BOLD               |
 125                       wxFONTFLAG_ANTIALIASED        |
 126                       wxFONTFLAG_NOT_ANTIALIASED    |
 127                       wxFONTFLAG_UNDERLINED         |
 128                       wxFONTFLAG_STRIKETHROUGH
 129 };
 130
 131
 132
 133 /**
 134     Font encodings.
 135
 136     See wxFont::SetEncoding().
 137 */
 138 enum wxFontEncoding
 139 {
 140     /// Default system encoding.
 141     wxFONTENCODING_SYSTEM = -1,     // system default
 142
 143     /// Default application encoding.
 144     wxFONTENCODING_DEFAULT,         // current default encoding
 145
 146     // ISO8859 standard defines a number of single-byte charsets
 147     wxFONTENCODING_ISO8859_1,       //!< West European (Latin1)
 148     wxFONTENCODING_ISO8859_2,       //!< Central and East European (Latin2)
 149     wxFONTENCODING_ISO8859_3,       //!< Esperanto (Latin3)
 150     wxFONTENCODING_ISO8859_4,       //!< Baltic (old) (Latin4)
 151     wxFONTENCODING_ISO8859_5,       //!< Cyrillic
 152     wxFONTENCODING_ISO8859_6,       //!< Arabic
 153     wxFONTENCODING_ISO8859_7,       //!< Greek
 154     wxFONTENCODING_ISO8859_8,       //!< Hebrew
 155     wxFONTENCODING_ISO8859_9,       //!< Turkish (Latin5)
 156     wxFONTENCODING_ISO8859_10,      //!< Variation of Latin4 (Latin6)
 157     wxFONTENCODING_ISO8859_11,      //!< Thai
 158     wxFONTENCODING_ISO8859_12,      //!< doesn't exist currently, but put it
 159                                     //!< here anyhow to make all ISO8859
 160                                     //!< consecutive numbers
 161     wxFONTENCODING_ISO8859_13,      //!< Baltic (Latin7)
 162     wxFONTENCODING_ISO8859_14,      //!< Latin8
 163     wxFONTENCODING_ISO8859_15,      //!< Latin9 (a.k.a. Latin0, includes euro)
 164     wxFONTENCODING_ISO8859_MAX,
 165
 166     // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
 167     wxFONTENCODING_KOI8,            //!< KOI8 Russian
 168     wxFONTENCODING_KOI8_U,          //!< KOI8 Ukrainian
 169     wxFONTENCODING_ALTERNATIVE,     //!< same as MS-DOS CP866
 170     wxFONTENCODING_BULGARIAN,       //!< used under Linux in Bulgaria
 171
 172     // what would we do without Microsoft? They have their own encodings
 173         // for DOS
 174     wxFONTENCODING_CP437,           //!< original MS-DOS codepage
 175     wxFONTENCODING_CP850,           //!< CP437 merged with Latin1
 176     wxFONTENCODING_CP852,           //!< CP437 merged with Latin2
 177     wxFONTENCODING_CP855,           //!< another cyrillic encoding
 178     wxFONTENCODING_CP866,           //!< and another one
 179         // and for Windows
 180     wxFONTENCODING_CP874,           //!< WinThai
 181     wxFONTENCODING_CP932,           //!< Japanese (shift-JIS)
 182     wxFONTENCODING_CP936,           //!< Chinese simplified (GB)
 183     wxFONTENCODING_CP949,           //!< Korean (Hangul charset)
 184     wxFONTENCODING_CP950,           //!< Chinese (traditional - Big5)
 185     wxFONTENCODING_CP1250,          //!< WinLatin2
 186     wxFONTENCODING_CP1251,          //!< WinCyrillic
 187     wxFONTENCODING_CP1252,          //!< WinLatin1
 188     wxFONTENCODING_CP1253,          //!< WinGreek (8859-7)
 189     wxFONTENCODING_CP1254,          //!< WinTurkish
 190     wxFONTENCODING_CP1255,          //!< WinHebrew
 191     wxFONTENCODING_CP1256,          //!< WinArabic
 192     wxFONTENCODING_CP1257,          //!< WinBaltic (same as Latin 7)
 193     wxFONTENCODING_CP1258,          //!< WinVietnamese (since 2.9.4)
 194     wxFONTENCODING_CP1361,          //!< Johab Korean character set (since 2.9.4)
 195     wxFONTENCODING_CP12_MAX,
 196
 197     wxFONTENCODING_UTF7,            //!< UTF-7 Unicode encoding
 198     wxFONTENCODING_UTF8,            //!< UTF-8 Unicode encoding
 199     wxFONTENCODING_EUC_JP,          //!< Extended Unix Codepage for Japanese
 200     wxFONTENCODING_UTF16BE,         //!< UTF-16 Big Endian Unicode encoding
 201     wxFONTENCODING_UTF16LE,         //!< UTF-16 Little Endian Unicode encoding
 202     wxFONTENCODING_UTF32BE,         //!< UTF-32 Big Endian Unicode encoding
 203     wxFONTENCODING_UTF32LE,         // UTF-32 Little Endian Unicode encoding
 204
 205     wxFONTENCODING_MACROMAN,        //!< the standard mac encodings
 206     wxFONTENCODING_MACJAPANESE,
 207     wxFONTENCODING_MACCHINESETRAD,
 208     wxFONTENCODING_MACKOREAN,
 209     wxFONTENCODING_MACARABIC,
 210     wxFONTENCODING_MACHEBREW,
 211     wxFONTENCODING_MACGREEK,
 212     wxFONTENCODING_MACCYRILLIC,
 213     wxFONTENCODING_MACDEVANAGARI,
 214     wxFONTENCODING_MACGURMUKHI,
 215     wxFONTENCODING_MACGUJARATI,
 216     wxFONTENCODING_MACORIYA,
 217     wxFONTENCODING_MACBENGALI,
 218     wxFONTENCODING_MACTAMIL,
 219     wxFONTENCODING_MACTELUGU,
 220     wxFONTENCODING_MACKANNADA,
 221     wxFONTENCODING_MACMALAJALAM,
 222     wxFONTENCODING_MACSINHALESE,
 223     wxFONTENCODING_MACBURMESE,
 224     wxFONTENCODING_MACKHMER,
 225     wxFONTENCODING_MACTHAI,
 226     wxFONTENCODING_MACLAOTIAN,
 227     wxFONTENCODING_MACGEORGIAN,
 228     wxFONTENCODING_MACARMENIAN,
 229     wxFONTENCODING_MACCHINESESIMP,
 230     wxFONTENCODING_MACTIBETAN,
 231     wxFONTENCODING_MACMONGOLIAN,
 232     wxFONTENCODING_MACETHIOPIC,
 233     wxFONTENCODING_MACCENTRALEUR,
 234     wxFONTENCODING_MACVIATNAMESE,
 235     wxFONTENCODING_MACARABICEXT,
 236     wxFONTENCODING_MACSYMBOL,
 237     wxFONTENCODING_MACDINGBATS,
 238     wxFONTENCODING_MACTURKISH,
 239     wxFONTENCODING_MACCROATIAN,
 240     wxFONTENCODING_MACICELANDIC,
 241     wxFONTENCODING_MACROMANIAN,
 242     wxFONTENCODING_MACCELTIC,
 243     wxFONTENCODING_MACGAELIC,
 244     wxFONTENCODING_MACKEYBOARD,
 245
 246     // more CJK encodings (for historical reasons some are already declared
 247     // above)
 248     wxFONTENCODING_ISO2022_JP,      //!< ISO-2022-JP JIS encoding
 249
 250     wxFONTENCODING_MAX,             //!< highest enumerated encoding value
 251
 252     wxFONTENCODING_MACMIN = wxFONTENCODING_MACROMAN ,
 253     wxFONTENCODING_MACMAX = wxFONTENCODING_MACKEYBOARD ,
 254
 255     // aliases for endian-dependent UTF encodings
 256     wxFONTENCODING_UTF16,  //!< native UTF-16
 257     wxFONTENCODING_UTF32,  //!< native UTF-32
 258
 259     /// Alias for the native Unicode encoding on this platform
 260     /// (this is used by wxEncodingConverter and wxUTFFile only for now)
 261     wxFONTENCODING_UNICODE,
 262
 263     wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese
 264     wxFONTENCODING_BIG5 = wxFONTENCODING_CP950,   //!< Traditional Chinese
 265     wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932, //!< Shift JIS
 266     wxFONTENCODING_EUC_KR = wxFONTENCODING_CP949, //!< Korean
 267     wxFONTENCODING_JOHAB = wxFONTENCODING_CP1361, //!< Korean Johab (since 2.9.4)
 268     wxFONTENCODING_VIETNAMESE = wxFONTENCODING_CP1258 //!< Vietnamese (since 2.9.4)
 269 };
 270
 271
 272 /**
 273     @class wxFontInfo
 274
 275     This class is a helper used for wxFont creation using named parameter
 276     idiom: it allows to specify various wxFont attributes using the chained
 277     calls to its clearly named methods instead of passing them in the fixed
 278     order to wxFont constructors.
 279
 280     For example, to create an italic font with the given face name and size you
 281     could use:
 282     @code
 283         wxFont font(wxFontInfo(12).FaceName("Helvetica").Italic());
 284     @endcode
 285
 286     Notice that all of the methods of this object return a reference to the
 287     object itself, allowing the calls to them to be chained as in the example
 288     above.
 289
 290     All methods taking boolean parameters can be used to turn the specified
 291     font attribute on or off and turn it on by default.
 292
 293     @since 2.9.5
 294  */
 295 class wxFontInfo
 296 {
 297 public:
 298     /**
 299         Default constructor uses the default font size for the current
 300         platform.
 301      */
 302     wxFontInfo();
 303
 304     /**
 305         Constructor setting the font size in points to use.
 306
 307         @see wxFont::SetPointSize()
 308      */
 309     explicit wxFontInfo(int pointSize);
 310
 311     /**
 312         Constructor setting the font size in pixels to use.
 313
 314         @see wxFont::SetPixelSize()
 315      */
 316     explicit wxFontInfo(const wxSize& pixelSize);
 317
 318     /**
 319         Set the font family.
 320
 321         The family is a generic portable way of referring to fonts without
 322         specifying a precise face name. This parameter must be one of the
 323         ::wxFontFamily enumeration values.
 324
 325         If the FaceName() is used, then it overrides the font family.
 326
 327         @see wxFont::SetFamily()
 328      */
 329     wxFontInfo& Family(wxFontFamily family);
 330
 331     /**
 332         Set the font face name to use.
 333
 334         Face names are not portable, so prefer to use Family() in portable
 335         code.
 336
 337         @see wxFont::SetFaceName()
 338      */
 339     wxFontInfo& FaceName(const wxString& faceName);
 340
 341     /**
 342         Use a bold version of the font.
 343
 344         @see ::wxFontWeight, wxFont::SetWeight()
 345      */
 346     wxFontInfo& Bold(bool bold = true);
 347
 348     /**
 349         Use a lighter version of the font.
 350
 351         @see ::wxFontWeight, wxFont::SetWeight()
 352      */
 353     wxFontInfo& Light(bool light = true);
 354
 355     /**
 356         Use an italic version of the font.
 357
 358         @see ::wxFontStyle, wxFont::SetStyle()
 359      */
 360     wxFontInfo& Italic(bool italic = true);
 361
 362     /**
 363         Use a slanted version of the font.
 364
 365         @see ::wxFontStyle, wxFont::SetStyle()
 366      */
 367     wxFontInfo& Slant(bool slant = true);
 368
 369     /**
 370         Set anti-aliasing flag.
 371
 372         Force the use of anti-aliasing on or off.
 373
 374         Currently this is not implemented, i.e. using this method doesn't do
 375         anything.
 376      */
 377     wxFontInfo& AntiAliased(bool antiAliased = true);
 378
 379     /**
 380         Use an underlined version of the font.
 381      */
 382     wxFontInfo& Underlined(bool underlined = true);
 383
 384     /**
 385         Use a strike-through version of the font.
 386
 387         Currently this is only implemented in wxMSW and wxGTK.
 388      */
 389     wxFontInfo& Strikethrough(bool strikethrough = true);
 390
 391     /**
 392         Set the font encoding to use.
 393
 394         This is mostly unneeded in Unicode builds of wxWidgets.
 395
 396         @see ::wxFontEncoding, wxFont::SetEncoding()
 397      */
 398     wxFontInfo& Encoding(wxFontEncoding encoding);
 399
 400     /**
 401         Set all the font attributes at once.
 402
 403         See ::wxFontFlag for the various flags that can be used.
 404      */
 405     wxFontInfo& AllFlags(int flags);
 406 };
 407
 408 /**
 409     @class wxFont
 410
 411     A font is an object which determines the appearance of text.
 412
 413     Fonts are used for drawing text to a device context, and setting the appearance
 414     of a window's text, see wxDC::SetFont() and wxWindow::SetFont().
 415
 416     The easiest way to create a custom font is to use wxFontInfo object to
 417     specify the font attributes and then use wxFont::wxFont(const wxFontInfo&)
 418     constructor. Alternatively, you could start with one of the pre-defined
 419     fonts or use wxWindow::GetFont() and modify the font, e.g. by increasing
 420     its size using MakeLarger() or changing its weight using MakeBold().
 421
 422     This class uses @ref overview_refcount "reference counting and copy-on-write"
 423     internally so that assignments between two instances of this class are very
 424     cheap. You can therefore use actual objects instead of pointers without
 425     efficiency problems. If an instance of this class is changed it will create
 426     its own data internally so that other instances, which previously shared the
 427     data using the reference counting, are not affected.
 428
 429     You can retrieve the current system font settings with wxSystemSettings.
 430
 431     @library{wxcore}
 432     @category{gdi}
 433
 434     @stdobjects
 435     ::wxNullFont, ::wxNORMAL_FONT, ::wxSMALL_FONT, ::wxITALIC_FONT, ::wxSWISS_FONT
 436
 437     @see @ref overview_font, wxDC::SetFont, wxDC::DrawText,
 438          wxDC::GetTextExtent, wxFontDialog, wxSystemSettings
 439 */
 440 class wxFont : public wxGDIObject
 441 {
 442 public:
 443     /**
 444         Default ctor.
 445     */
 446     wxFont();
 447
 448     /**
 449         Copy constructor, uses @ref overview_refcount "reference counting".
 450     */
 451     wxFont(const wxFont& font);
 452
 453     /**
 454         Creates a font object using the specified font description.
 455
 456         This is the preferred way to create font objects as using this ctor
 457         results in more readable code and it is also extensible, e.g. it could
 458         continue to be used if support for more font attributes is added in the
 459         future. For example, this constructor provides the only way of creating
 460         fonts with strike-through style.
 461
 462         Example of creating a font using this ctor:
 463         @code
 464             wxFont font(wxFontInfo(10).Bold().Underlined());
 465         @endcode
 466
 467         @since 2.9.5
 468      */
 469     wxFont(const wxFontInfo& font);
 470
 471     /**
 472         Creates a font object with the specified attributes and size in points.
 473
 474         Notice that the use of this constructor is often more verbose and less
 475         readable than the use of constructor from wxFontInfo, e.g. the example
 476         in that constructor documentation would need to be written as
 477         @code
 478             wxFont font(10, wxFONTFAMILY_DEFAULT, wxFONTSTYLE_NORMAL,
 479                         wxFONTWEIGHT_BOLD, true);
 480         @endcode
 481         which is longer and less clear.
 482
 483         @param pointSize
 484             Size in points. See SetPointSize() for more info.
 485         @param family
 486             The font family: a generic portable way of referring to fonts without specifying a
 487             facename. This parameter must be one of the ::wxFontFamily enumeration values.
 488             If the @a faceName argument is provided, then it overrides the font family.
 489         @param style
 490             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
 491         @param weight
 492             Font weight, sometimes also referred to as font boldness.
 493             One of the ::wxFontWeight enumeration values.
 494         @param underline
 495             The value can be @true or @false.
 496             At present this has an effect on Windows and Motif 2.x only.
 497         @param faceName
 498             An optional string specifying the face name to be used.
 499             If it is an empty string, a default face name will be chosen based on the family.
 500         @param encoding
 501             An encoding which may be one of the enumeration values of ::wxFontEncoding.
 502             Briefly these can be summed up as:
 503             <TABLE>
 504                 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
 505                 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
 506                     Default application encoding: this is the encoding set by calls to
 507                     SetDefaultEncoding() and which may be set to, say, KOI8 to create all
 508                     fonts by default with KOI8 encoding. Initially, the default application
 509                     encoding is the same as default system encoding.</TD></TR>
 510                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 511                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 512                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 513             </TABLE>
 514             If the specified encoding isn't available, no font is created
 515             (see also @ref overview_fontencoding).
 516
 517         @remarks If the desired font does not exist, the closest match will be
 518                  chosen. Under Windows, only scalable TrueType fonts are used.
 519     */
 520     wxFont(int pointSize, wxFontFamily family, wxFontStyle style,
 521            wxFontWeight weight,
 522            bool underline = false,
 523            const wxString& faceName = wxEmptyString,
 524            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 525
 526     /**
 527         Creates a font object with the specified attributes and size in pixels.
 528
 529         Notice that the use of this constructor is often more verbose and less
 530         readable than the use of constructor from wxFontInfo, consider using
 531         that constructor instead.
 532
 533         @param pixelSize
 534             Size in pixels. See SetPixelSize() for more info.
 535         @param family
 536             The font family: a generic portable way of referring to fonts without specifying a
 537             facename. This parameter must be one of the ::wxFontFamily enumeration values.
 538             If the @a faceName argument is provided, then it overrides the font family.
 539         @param style
 540             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
 541         @param weight
 542             Font weight, sometimes also referred to as font boldness.
 543             One of the ::wxFontWeight enumeration values.
 544         @param underline
 545             The value can be @true or @false.
 546             At present this has an effect on Windows and Motif 2.x only.
 547         @param faceName
 548             An optional string specifying the face name to be used.
 549             If it is an empty string, a default face name will be chosen based on the family.
 550         @param encoding
 551             An encoding which may be one of the enumeration values of ::wxFontEncoding.
 552             Briefly these can be summed up as:
 553             <TABLE>
 554                 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
 555                 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
 556                     Default application encoding: this is the encoding set by calls to
 557                     SetDefaultEncoding() and which may be set to, say, KOI8 to create all
 558                     fonts by default with KOI8 encoding. Initially, the default application
 559                     encoding is the same as default system encoding.</TD></TR>
 560                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 561                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 562                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 563             </TABLE>
 564             If the specified encoding isn't available, no font is created
 565             (see also @ref overview_fontencoding).
 566
 567         @remarks If the desired font does not exist, the closest match will be
 568                  chosen. Under Windows, only scalable TrueType fonts are used.
 569     */
 570     wxFont(const wxSize& pixelSize, wxFontFamily family,
 571            wxFontStyle style, wxFontWeight weight,
 572            bool underline = false,
 573            const wxString& faceName = wxEmptyString,
 574            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 575
 576     /**
 577         Constructor from font description string.
 578
 579         This constructor uses SetNativeFontInfo() to initialize the font.
 580         If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
 581         will return @false.
 582      */
 583     wxFont(const wxString& nativeInfoString);
 584
 585     /**
 586        Construct font from a native font info structure.
 587     */
 588     wxFont(const wxNativeFontInfo& nativeInfo);
 589
 590     /**
 591         Destructor.
 592
 593         See @ref overview_refcount_destruct "reference-counted object destruction"
 594         for more info.
 595
 596         @remarks Although all remaining fonts are deleted when the application
 597                  exits, the application should try to clean up all fonts
 598                  itself. This is because wxWidgets cannot know if a
 599                  pointer to the font object is stored in an application
 600                  data structure, and there is a risk of double deletion.
 601     */
 602     virtual ~wxFont();
 603
 604
 605     /**
 606         @name Getters
 607     */
 608     //@{
 609
 610     /**
 611         Returns the encoding of this font.
 612
 613         Note that under wxGTK the returned value is always @c wxFONTENCODING_UTF8.
 614
 615         @see SetEncoding()
 616     */
 617     virtual wxFontEncoding GetEncoding() const;
 618
 619     /**
 620         Returns the face name associated with the font, or the empty string if
 621         there is no face information.
 622
 623         @see SetFaceName()
 624     */
 625     virtual wxString GetFaceName() const;
 626
 627     /**
 628         Gets the font family if possible.
 629
 630         As described in ::wxFontFamily docs the returned value acts as a rough,
 631         basic classification of the main font properties (look, spacing).
 632
 633         If the current font face name is not recognized by wxFont or by the
 634         underlying system, @c wxFONTFAMILY_DEFAULT is returned.
 635
 636         Note that currently this function is not very precise and so not
 637         particularly useful. Font families mostly make sense only for font
 638         creation, see SetFamily().
 639
 640         @see SetFamily()
 641     */
 642     virtual wxFontFamily GetFamily() const;
 643
 644     /**
 645         Returns the platform-dependent string completely describing this font.
 646
 647         Returned string is always non-empty unless the font is invalid (in
 648         which case an assert is triggered).
 649
 650         Note that the returned string is not meant to be shown or edited by the user: a
 651         typical use of this function is for serializing in string-form a wxFont object.
 652
 653         @see SetNativeFontInfo(), GetNativeFontInfoUserDesc()
 654     */
 655     wxString GetNativeFontInfoDesc() const;
 656
 657     /**
 658         Returns a user-friendly string for this font object.
 659
 660         Returned string is always non-empty unless the font is invalid (in
 661         which case an assert is triggered).
 662
 663         The string does not encode all wxFont infos under all platforms;
 664         e.g. under wxMSW the font family is not present in the returned string.
 665
 666         Some examples of the formats of returned strings (which are platform-dependent)
 667         are in SetNativeFontInfoUserDesc().
 668
 669         @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()
 670     */
 671     wxString GetNativeFontInfoUserDesc() const;
 672
 673     const wxNativeFontInfo *GetNativeFontInfo() const;
 674
 675     /**
 676         Gets the point size.
 677
 678         @see SetPointSize()
 679     */
 680     virtual int GetPointSize() const;
 681
 682     /**
 683         Gets the pixel size.
 684
 685         Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
 686         a wxSize object with a null width value, you'll get a null width in
 687         the returned object.
 688
 689         @see SetPixelSize()
 690     */
 691     virtual wxSize GetPixelSize() const;
 692
 693     /**
 694         Gets the font style. See ::wxFontStyle for a list of valid styles.
 695
 696         @see SetStyle()
 697     */
 698     virtual wxFontStyle GetStyle() const;
 699
 700     /**
 701         Returns @true if the font is underlined, @false otherwise.
 702
 703         @see SetUnderlined()
 704     */
 705     virtual bool GetUnderlined() const;
 706
 707     /**
 708         Returns @true if the font is stricken-through, @false otherwise.
 709
 710         @see SetStrikethrough()
 711
 712         @since 2.9.4
 713      */
 714     virtual bool GetStrikethrough() const;
 715
 716     /**
 717         Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
 718
 719         @see SetWeight()
 720     */
 721     virtual wxFontWeight GetWeight() const;
 722
 723     /**
 724         Returns @true if the font is a fixed width (or monospaced) font,
 725         @false if it is a proportional one or font is invalid.
 726
 727         Note that this function under some platforms is different than just testing
 728         for the font family being equal to @c wxFONTFAMILY_TELETYPE because native
 729         platform-specific functions are used for the check (resulting in a more
 730         accurate return value).
 731     */
 732     virtual bool IsFixedWidth() const;
 733
 734     /**
 735         Returns @true if this object is a valid font, @false otherwise.
 736     */
 737     virtual bool IsOk() const;
 738
 739     //@}
 740
 741
 742     /**
 743         @name Similar fonts creation
 744
 745         The functions in this section either modify the font in place or create
 746         a new font similar to the given one but with its weight, style or size
 747         changed.
 748      */
 749     //@{
 750
 751     /**
 752         Returns a bold version of this font.
 753
 754         @see MakeBold()
 755
 756         @since 2.9.1
 757      */
 758     wxFont Bold() const;
 759
 760     /**
 761         Returns an italic version of this font.
 762
 763         @see MakeItalic()
 764
 765         @since 2.9.1
 766      */
 767     wxFont Italic() const;
 768
 769     /**
 770         Returns a larger version of this font.
 771
 772         The font size is multiplied by @c 1.2, the factor of @c 1.2 being
 773         inspired by the W3C CSS specification.
 774
 775         @see MakeLarger(), Smaller(), Scaled()
 776
 777         @since 2.9.1
 778      */
 779     wxFont Larger() const;
 780
 781     /**
 782         Returns a smaller version of this font.
 783
 784         The font size is divided by @c 1.2, the factor of @c 1.2 being
 785         inspired by the W3C CSS specification.
 786
 787         @see MakeSmaller(), Larger(), Scaled()
 788
 789         @since 2.9.1
 790      */
 791     wxFont Smaller() const;
 792
 793     /**
 794         Returns underlined version of this font.
 795
 796         @see MakeUnderlined()
 797
 798         @since 2.9.2
 799      */
 800     wxFont Underlined() const;
 801
 802     /**
 803         Returns stricken-through version of this font.
 804
 805         Currently stricken-through fonts are only supported in wxMSW and wxGTK.
 806
 807         @see MakeStrikethrough()
 808
 809         @since 2.9.4
 810      */
 811     wxFont Strikethrough() const;
 812
 813     /**
 814         Changes this font to be bold.
 815
 816         @see Bold()
 817
 818         @since 2.9.1
 819      */
 820     wxFont& MakeBold();
 821
 822     /**
 823         Changes this font to be italic.
 824
 825         @see Italic()
 826
 827         @since 2.9.1
 828      */
 829     wxFont& MakeItalic();
 830
 831     /**
 832         Changes this font to be larger.
 833
 834         The font size is multiplied by @c 1.2, the factor of @c 1.2 being
 835         inspired by the W3C CSS specification.
 836
 837         @see Larger(), MakeSmaller(), Scale()
 838
 839         @since 2.9.1
 840      */
 841     wxFont& MakeLarger();
 842
 843     /**
 844         Changes this font to be smaller.
 845
 846         The font size is divided by @c 1.2, the factor of @c 1.2 being
 847         inspired by the W3C CSS specification.
 848
 849         @see Smaller(), MakeLarger(), Scale()
 850
 851         @since 2.9.1
 852      */
 853     wxFont& MakeSmaller();
 854
 855     /**
 856         Changes this font to be underlined.
 857
 858         @see Underlined()
 859
 860         @since 2.9.2
 861      */
 862     wxFont& MakeUnderlined();
 863
 864     /**
 865         Changes this font to be stricken-through.
 866
 867         Currently stricken-through fonts are only supported in wxMSW and wxGTK.
 868
 869         @see Strikethrough()
 870
 871         @since 2.9.4
 872     */
 873     wxFont& MakeStrikethrough();
 874
 875     /**
 876         Changes the size of this font.
 877
 878         The font size is multiplied by the given factor (which may be less than
 879         1 to create a smaller version of the font).
 880
 881         @see Scaled(), MakeLarger(), MakeSmaller()
 882
 883         @since 2.9.1
 884      */
 885     wxFont& Scale(float x);
 886
 887     /**
 888         Returns a scaled version of this font.
 889
 890         The font size is multiplied by the given factor (which may be less than
 891         1 to create a smaller version of the font).
 892
 893         @see Scale(), Larger(), Smaller()
 894
 895         @since 2.9.1
 896      */
 897     wxFont Scaled(float x) const;
 898
 899     //@}
 900
 901     /**
 902         @name Setters
 903
 904         These functions internally recreate the native font object with the new
 905         specified property.
 906     */
 907     //@{
 908
 909     /**
 910         Sets the encoding for this font.
 911
 912         Note that under wxGTK this function has no effect (because the underlying
 913         Pango library always uses @c wxFONTENCODING_UTF8).
 914
 915         @see GetEncoding()
 916     */
 917     virtual void SetEncoding(wxFontEncoding encoding);
 918
 919     /**
 920         Sets the facename for the font.
 921
 922         @param faceName
 923             A valid facename, which should be on the end-user's system.
 924
 925         @remarks To avoid portability problems, don't rely on a specific face,
 926                  but specify the font family instead (see ::wxFontFamily and SetFamily()).
 927
 928         @return @true if the given face name exists; if the face name doesn't exist
 929                 in the user's system then the font is invalidated (so that IsOk() will
 930                 return @false) and @false is returned.
 931
 932         @see GetFaceName(), SetFamily()
 933     */
 934     virtual bool SetFaceName(const wxString& faceName);
 935
 936     /**
 937         Sets the font family.
 938
 939         As described in ::wxFontFamily docs the given @a family value acts as a rough,
 940         basic indication of the main font properties (look, spacing).
 941
 942         Note that changing the font family results in changing the font face name.
 943
 944         @param family
 945             One of the ::wxFontFamily values.
 946
 947         @see GetFamily(), SetFaceName()
 948     */
 949     virtual void SetFamily(wxFontFamily family);
 950
 951     /**
 952         Creates the font corresponding to the given native font description string
 953         which must have been previously returned by GetNativeFontInfoDesc().
 954
 955         If the string is invalid, font is unchanged.
 956         This function is typically used for de-serializing a wxFont object
 957         previously saved in a string-form.
 958
 959         @return @true if the creation was successful.
 960
 961         @see SetNativeFontInfoUserDesc()
 962     */
 963     bool SetNativeFontInfo(const wxString& info);
 964
 965     /**
 966         Creates the font corresponding to the given native font description string and
 967         returns @true if the creation was successful.
 968
 969         Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly.
 970         Examples of accepted string formats are:
 971
 972         @beginTable
 973         @hdr3col{platform, generic syntax, example}
 974         @row3col{wxGTK2, <tt>[underlined] [strikethrough] [FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
 975         @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
 976         @endTable
 977
 978         @todo add an example for wxMac
 979
 980         For more detailed information about the allowed syntaxes you can look at the
 981         documentation of the native API used for font-rendering
 982         (e.g. @c pango_font_description_from_string under GTK, although notice
 983         that it doesn't support the "underlined" and "strikethrough" attributes
 984         and so those are handled by wxWidgets itself).
 985
 986         Note that unlike SetNativeFontInfo(), this function doesn't always restore all
 987         attributes of the wxFont object under all platforms; e.g. on wxMSW the font family
 988         is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW).
 989         If you want to serialize/deserialize a font in string form, you should use
 990         GetNativeFontInfoDesc() and SetNativeFontInfo() instead.
 991
 992         @see SetNativeFontInfo()
 993     */
 994     bool SetNativeFontInfoUserDesc(const wxString& info);
 995
 996     void SetNativeFontInfo(const wxNativeFontInfo& info);
 997
 998     /**
 999         Sets the point size.
1000
1001         The <em>point size</em> is defined as 1/72 of the Anglo-Saxon inch
1002         (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
1003
1004         @param pointSize
1005             Size in points.
1006
1007         @see GetPointSize()
1008     */
1009     virtual void SetPointSize(int pointSize);
1010
1011     /**
1012         Sets the pixel size.
1013
1014         The height parameter of @a pixelSize must be positive while the width
1015         parameter may also be zero (to indicate that you're not interested in the
1016         width of the characters: a suitable width will be chosen for best rendering).
1017
1018         This feature (specifying the font pixel size) is directly supported only
1019         under wxMSW and wxGTK currently; under other platforms a font with the
1020         closest size to the given one is found using binary search (this maybe slower).
1021
1022         @see GetPixelSize()
1023     */
1024     virtual void SetPixelSize(const wxSize& pixelSize);
1025
1026     /**
1027         Sets the font style.
1028
1029         @param style
1030             One of the ::wxFontStyle enumeration values.
1031
1032         @see GetStyle()
1033     */
1034     virtual void SetStyle(wxFontStyle style);
1035
1036     /**
1037         Sets the font size using a predefined symbolic size name.
1038
1039         This function allows to change font size to be (very) large or small
1040         compared to the standard font size.
1041
1042         @see SetSymbolicSizeRelativeTo().
1043
1044         @since 2.9.2
1045      */
1046     void SetSymbolicSize(wxFontSymbolicSize size);
1047
1048     /**
1049         Sets the font size compared to the base font size.
1050
1051         This is the same as SetSymbolicSize() except that it uses the given
1052         font size as the normal font size instead of the standard font size.
1053
1054         @since 2.9.2
1055      */
1056     void SetSymbolicSizeRelativeTo(wxFontSymbolicSize size, int base);
1057
1058     /**
1059         Sets underlining.
1060
1061         @param underlined
1062             @true to underline, @false otherwise.
1063
1064         @see GetUnderlined()
1065     */
1066     virtual void SetUnderlined(bool underlined);
1067
1068     /**
1069         Sets strike-through attribute of the font.
1070
1071         Currently stricken-through fonts are only supported in wxMSW and wxGTK.
1072
1073         @param strikethrough
1074             @true to add strike-through style, @false to remove it.
1075
1076         @see GetStrikethrough()
1077
1078         @since 2.9.4
1079     */
1080     virtual void SetStrikethrough(bool strikethrough);
1081
1082     /**
1083         Sets the font weight.
1084
1085         @param weight
1086             One of the ::wxFontWeight values.
1087
1088         @see GetWeight()
1089     */
1090     virtual void SetWeight(wxFontWeight weight);
1091
1092     //@}
1093
1094
1095     /**
1096         Inequality operator.
1097
1098         See @ref overview_refcount_equality "reference-counted object comparison" for
1099         more info.
1100     */
1101     bool operator!=(const wxFont& font) const;
1102
1103     /**
1104         Equality operator.
1105
1106         See @ref overview_refcount_equality "reference-counted object comparison" for
1107         more info.
1108     */
1109     bool operator==(const wxFont& font) const;
1110
1111     /**
1112         Assignment operator, using @ref overview_refcount "reference counting".
1113     */
1114     wxFont& operator =(const wxFont& font);
1115
1116
1117     // statics
1118
1119     /**
1120         Returns the current application's default encoding.
1121
1122         @see @ref overview_fontencoding, SetDefaultEncoding()
1123     */
1124     static wxFontEncoding GetDefaultEncoding();
1125
1126     /**
1127         Sets the default font encoding.
1128
1129         @see @ref overview_fontencoding, GetDefaultEncoding()
1130     */
1131     static void SetDefaultEncoding(wxFontEncoding encoding);
1132
1133     //@{
1134     /**
1135         This function takes the same parameters as the relative
1136         @ref wxFont::wxFont "wxFont constructor" and returns a new font
1137         object allocated on the heap.
1138
1139         Their use is discouraged, use wxFont constructor from wxFontInfo
1140         instead.
1141     */
1142     static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
1143                        wxFontWeight weight,
1144                        bool underline = false,
1145                        const wxString& faceName = wxEmptyString,
1146                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
1147     static wxFont* New(int pointSize, wxFontFamily family,
1148                        int flags = wxFONTFLAG_DEFAULT,
1149                        const wxString& faceName = wxEmptyString,
1150                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
1151     static wxFont* New(const wxSize& pixelSize,
1152                        wxFontFamily family,
1153                        wxFontStyle style,
1154                        wxFontWeight weight,
1155                        bool underline = false,
1156                        const wxString& faceName = wxEmptyString,
1157                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
1158     static wxFont* New(const wxSize& pixelSize,
1159                        wxFontFamily family,
1160                        int flags = wxFONTFLAG_DEFAULT,
1161                        const wxString& faceName = wxEmptyString,
1162                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
1163
1164
1165     static wxFont *New(const wxNativeFontInfo& nativeInfo);
1166     static wxFont *New(const wxString& nativeInfoString);
1167
1168     //@}
1169 };
1170
1171
1172 /**
1173     An empty wxFont.
1174 */
1175 wxFont wxNullFont;
1176
1177 /**
1178     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
1179
1180     @see wxSystemSettings
1181 */
1182 wxFont* wxNORMAL_FONT;
1183
1184 /**
1185     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
1186     ::wxNORMAL_FONT.
1187 */
1188 wxFont* wxSMALL_FONT;
1189
1190 /**
1191     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
1192     of the same size of ::wxNORMAL_FONT.
1193 */
1194 wxFont* wxITALIC_FONT;
1195
1196 /**
1197     A font identic to ::wxNORMAL_FONT except for the family used which is
1198     @c wxFONTFAMILY_SWISS.
1199 */
1200 wxFont* wxSWISS_FONT;
1201
1202
1203 /**
1204     @class wxFontList
1205
1206     A font list is a list containing all fonts which have been created.
1207     There is only one instance of this class: ::wxTheFontList.
1208
1209     Use this object to search for a previously created font of the desired type
1210     and create it if not already found.
1211
1212     In some windowing systems, the font may be a scarce resource, so it is best to
1213     reuse old resources if possible.  When an application finishes, all fonts will
1214     be deleted and their resources freed, eliminating the possibility of 'memory
1215     leaks'.
1216
1217     @library{wxcore}
1218     @category{gdi}
1219
1220     @see wxFont
1221 */
1222 class wxFontList
1223 {
1224 public:
1225     /**
1226         Constructor. The application should not construct its own font list:
1227         use the object pointer ::wxTheFontList.
1228     */
1229     wxFontList();
1230
1231     /**
1232         Finds a font of the given specification, or creates one and adds it to the
1233         list. See the @ref wxFont "wxFont constructor" for details of the arguments.
1234     */
1235     wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
1236                              wxFontWeight weight, bool underline = false,
1237                              const wxString& facename = wxEmptyString,
1238                              wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
1239 };
1240
1241
1242 /**
1243     The global wxFontList instance.
1244 */
1245 wxFontList* wxTheFontList;
1246
1247
1248 // ============================================================================
1249 // Global functions/macros
1250 // ============================================================================
1251
1252 /** @addtogroup group_funcmacro_misc */
1253 //@{
1254
1255 /**
1256     Converts string to a wxFont best represented by the given string. Returns
1257     @true on success.
1258
1259     @see wxToString(const wxFont&)
1260
1261     @header{wx/font.h}
1262 */
1263 bool wxFromString(const wxString& string, wxFont* font);
1264
1265 /**
1266     Converts the given wxFont into a string.
1267
1268     @see wxFromString(const wxString&, wxFont*)
1269
1270     @header{wx/font.h}
1271 */
1272 wxString wxToString(const wxFont& font);
1273
1274 //@}
1275