interface/wx/font.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        font.h
   3 // Purpose:     interface of wxFont
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     Standard font families: these may be used only for the font creation, it
  12     doesn't make sense to query an existing font for its font family as,
  13     especially if the font had been created from a native font description, it
  14     may be unknown.
  15 */
  16 enum wxFontFamily
  17 {
  18     wxFONTFAMILY_DEFAULT = wxDEFAULT,           //!< Chooses a default font.
  19     wxFONTFAMILY_DECORATIVE = wxDECORATIVE,     //!< A decorative font.
  20     wxFONTFAMILY_ROMAN = wxROMAN,               //!< A formal, serif font.
  21     wxFONTFAMILY_SCRIPT = wxSCRIPT,             //!< A handwriting font.
  22     wxFONTFAMILY_SWISS = wxSWISS,               //!< A sans-serif font.
  23     wxFONTFAMILY_MODERN = wxMODERN,             //!< A fixed pitch font.
  24     wxFONTFAMILY_TELETYPE = wxTELETYPE,         //!< A teletype font.
  25     wxFONTFAMILY_MAX,
  26     wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX
  27 };
  28
  29 /**
  30     Font styles.
  31 */
  32 enum wxFontStyle
  33 {
  34     /// The font is drawn without slant.
  35     wxFONTSTYLE_NORMAL = wxNORMAL,
  36
  37     /// The font is slanted in an italic style.
  38     wxFONTSTYLE_ITALIC = wxITALIC,
  39
  40     /// The font is slanted, but in a roman style.
  41     /// Note that under wxMSW this style is the same as @c wxFONTSTYLE_ITALIC.
  42     wxFONTSTYLE_SLANT = wxSLANT,
  43
  44     wxFONTSTYLE_MAX
  45 };
  46
  47 /**
  48     Font weights.
  49 */
  50 enum wxFontWeight
  51 {
  52     wxFONTWEIGHT_NORMAL = wxNORMAL,  //!< Normal font.
  53     wxFONTWEIGHT_LIGHT = wxLIGHT,    //!< Light font.
  54     wxFONTWEIGHT_BOLD = wxBOLD,      //!< Bold font.
  55     wxFONTWEIGHT_MAX
  56 };
  57
  58 /**
  59     The font flag bits for the new font ctor accepting one combined flags word.
  60 */
  61 enum wxFontFlag
  62 {
  63     /// no special flags: font with default weight/slant/anti-aliasing
  64     wxFONTFLAG_DEFAULT          = 0,
  65
  66     /// slant flags (default: no slant)
  67     wxFONTFLAG_ITALIC           = 1 << 0,
  68     wxFONTFLAG_SLANT            = 1 << 1,
  69
  70     /// weight flags (default: medium)
  71     wxFONTFLAG_LIGHT            = 1 << 2,
  72     wxFONTFLAG_BOLD             = 1 << 3,
  73
  74     /// anti-aliasing flag: force on or off (default: the current system default)
  75     wxFONTFLAG_ANTIALIASED      = 1 << 4,
  76     wxFONTFLAG_NOT_ANTIALIASED  = 1 << 5,
  77
  78     /// underlined/strikethrough flags (default: no lines)
  79     wxFONTFLAG_UNDERLINED       = 1 << 6,
  80     wxFONTFLAG_STRIKETHROUGH    = 1 << 7,
  81
  82     /// the mask of all currently used flags
  83     wxFONTFLAG_MASK = wxFONTFLAG_ITALIC             |
  84                       wxFONTFLAG_SLANT              |
  85                       wxFONTFLAG_LIGHT              |
  86                       wxFONTFLAG_BOLD               |
  87                       wxFONTFLAG_ANTIALIASED        |
  88                       wxFONTFLAG_NOT_ANTIALIASED    |
  89                       wxFONTFLAG_UNDERLINED         |
  90                       wxFONTFLAG_STRIKETHROUGH
  91 };
  92
  93
  94
  95 /**
  96     Font encodings.
  97 */
  98 enum wxFontEncoding
  99 {
 100     /// Default system encoding.
 101     wxFONTENCODING_SYSTEM = -1,     // system default
 102
 103     /// Default application encoding.
 104     wxFONTENCODING_DEFAULT,         // current default encoding
 105
 106     // ISO8859 standard defines a number of single-byte charsets
 107     wxFONTENCODING_ISO8859_1,       //!< West European (Latin1)
 108     wxFONTENCODING_ISO8859_2,       //!< Central and East European (Latin2)
 109     wxFONTENCODING_ISO8859_3,       //!< Esperanto (Latin3)
 110     wxFONTENCODING_ISO8859_4,       //!< Baltic (old) (Latin4)
 111     wxFONTENCODING_ISO8859_5,       //!< Cyrillic
 112     wxFONTENCODING_ISO8859_6,       //!< Arabic
 113     wxFONTENCODING_ISO8859_7,       //!< Greek
 114     wxFONTENCODING_ISO8859_8,       //!< Hebrew
 115     wxFONTENCODING_ISO8859_9,       //!< Turkish (Latin5)
 116     wxFONTENCODING_ISO8859_10,      //!< Variation of Latin4 (Latin6)
 117     wxFONTENCODING_ISO8859_11,      //!< Thai
 118     wxFONTENCODING_ISO8859_12,      //!< doesn't exist currently, but put it
 119                                     //!< here anyhow to make all ISO8859
 120                                     //!< consecutive numbers
 121     wxFONTENCODING_ISO8859_13,      //!< Baltic (Latin7)
 122     wxFONTENCODING_ISO8859_14,      //!< Latin8
 123     wxFONTENCODING_ISO8859_15,      //!< Latin9 (a.k.a. Latin0, includes euro)
 124     wxFONTENCODING_ISO8859_MAX,
 125
 126     // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
 127     wxFONTENCODING_KOI8,            //!< KOI8 Russian
 128     wxFONTENCODING_KOI8_U,          //!< KOI8 Ukrainian
 129     wxFONTENCODING_ALTERNATIVE,     //!< same as MS-DOS CP866
 130     wxFONTENCODING_BULGARIAN,       //!< used under Linux in Bulgaria
 131
 132     // what would we do without Microsoft? They have their own encodings
 133         // for DOS
 134     wxFONTENCODING_CP437,           //!< original MS-DOS codepage
 135     wxFONTENCODING_CP850,           //!< CP437 merged with Latin1
 136     wxFONTENCODING_CP852,           //!< CP437 merged with Latin2
 137     wxFONTENCODING_CP855,           //!< another cyrillic encoding
 138     wxFONTENCODING_CP866,           //!< and another one
 139         // and for Windows
 140     wxFONTENCODING_CP874,           //!< WinThai
 141     wxFONTENCODING_CP932,           //!< Japanese (shift-JIS)
 142     wxFONTENCODING_CP936,           //!< Chinese simplified (GB)
 143     wxFONTENCODING_CP949,           //!< Korean (Hangul charset)
 144     wxFONTENCODING_CP950,           //!< Chinese (traditional - Big5)
 145     wxFONTENCODING_CP1250,          //!< WinLatin2
 146     wxFONTENCODING_CP1251,          //!< WinCyrillic
 147     wxFONTENCODING_CP1252,          //!< WinLatin1
 148     wxFONTENCODING_CP1253,          //!< WinGreek (8859-7)
 149     wxFONTENCODING_CP1254,          //!< WinTurkish
 150     wxFONTENCODING_CP1255,          //!< WinHebrew
 151     wxFONTENCODING_CP1256,          //!< WinArabic
 152     wxFONTENCODING_CP1257,          //!< WinBaltic (same as Latin 7)
 153     wxFONTENCODING_CP12_MAX,
 154
 155     wxFONTENCODING_UTF7,            //!< UTF-7 Unicode encoding
 156     wxFONTENCODING_UTF8,            //!< UTF-8 Unicode encoding
 157     wxFONTENCODING_EUC_JP,          //!< Extended Unix Codepage for Japanese
 158     wxFONTENCODING_UTF16BE,         //!< UTF-16 Big Endian Unicode encoding
 159     wxFONTENCODING_UTF16LE,         //!< UTF-16 Little Endian Unicode encoding
 160     wxFONTENCODING_UTF32BE,         //!< UTF-32 Big Endian Unicode encoding
 161     wxFONTENCODING_UTF32LE,         // UTF-32 Little Endian Unicode encoding
 162
 163     wxFONTENCODING_MACROMAN,        //!< the standard mac encodings
 164     wxFONTENCODING_MACJAPANESE,
 165     wxFONTENCODING_MACCHINESETRAD,
 166     wxFONTENCODING_MACKOREAN,
 167     wxFONTENCODING_MACARABIC,
 168     wxFONTENCODING_MACHEBREW,
 169     wxFONTENCODING_MACGREEK,
 170     wxFONTENCODING_MACCYRILLIC,
 171     wxFONTENCODING_MACDEVANAGARI,
 172     wxFONTENCODING_MACGURMUKHI,
 173     wxFONTENCODING_MACGUJARATI,
 174     wxFONTENCODING_MACORIYA,
 175     wxFONTENCODING_MACBENGALI,
 176     wxFONTENCODING_MACTAMIL,
 177     wxFONTENCODING_MACTELUGU,
 178     wxFONTENCODING_MACKANNADA,
 179     wxFONTENCODING_MACMALAJALAM,
 180     wxFONTENCODING_MACSINHALESE,
 181     wxFONTENCODING_MACBURMESE,
 182     wxFONTENCODING_MACKHMER,
 183     wxFONTENCODING_MACTHAI,
 184     wxFONTENCODING_MACLAOTIAN,
 185     wxFONTENCODING_MACGEORGIAN,
 186     wxFONTENCODING_MACARMENIAN,
 187     wxFONTENCODING_MACCHINESESIMP,
 188     wxFONTENCODING_MACTIBETAN,
 189     wxFONTENCODING_MACMONGOLIAN,
 190     wxFONTENCODING_MACETHIOPIC,
 191     wxFONTENCODING_MACCENTRALEUR,
 192     wxFONTENCODING_MACVIATNAMESE,
 193     wxFONTENCODING_MACARABICEXT,
 194     wxFONTENCODING_MACSYMBOL,
 195     wxFONTENCODING_MACDINGBATS,
 196     wxFONTENCODING_MACTURKISH,
 197     wxFONTENCODING_MACCROATIAN,
 198     wxFONTENCODING_MACICELANDIC,
 199     wxFONTENCODING_MACROMANIAN,
 200     wxFONTENCODING_MACCELTIC,
 201     wxFONTENCODING_MACGAELIC,
 202     wxFONTENCODING_MACKEYBOARD,
 203
 204     // more CJK encodings (for historical reasons some are already declared
 205     // above)
 206     wxFONTENCODING_ISO2022_JP,      //!< ISO-2022-JP JIS encoding
 207
 208     wxFONTENCODING_MAX,             //!< highest enumerated encoding value
 209
 210     wxFONTENCODING_MACMIN = wxFONTENCODING_MACROMAN ,
 211     wxFONTENCODING_MACMAX = wxFONTENCODING_MACKEYBOARD ,
 212
 213     // aliases for endian-dependent UTF encodings
 214     wxFONTENCODING_UTF16,  //!< native UTF-16
 215     wxFONTENCODING_UTF32,  //!< native UTF-32
 216
 217     /// Alias for the native Unicode encoding on this platform
 218     /// (this is used by wxEncodingConverter and wxUTFFile only for now)
 219     wxFONTENCODING_UNICODE,
 220
 221     // alternative names for Far Eastern encodings
 222     // Chinese
 223     wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese
 224     wxFONTENCODING_BIG5 = wxFONTENCODING_CP950,   //!< Traditional Chinese
 225
 226         // Japanese (see http://zsigri.tripod.com/fontboard/cjk/jis.html)
 227     wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932 //!< Shift JIS
 228 };
 229
 230
 231
 232 /**
 233     @class wxFont
 234
 235     A font is an object which determines the appearance of text.
 236     Fonts are used for drawing text to a device context, and setting the appearance
 237     of a window's text.
 238
 239     This class uses @ref overview_refcount "reference counting and copy-on-write"
 240     internally so that assignments between two instances of this class are very
 241     cheap. You can therefore use actual objects instead of pointers without
 242     efficiency problems. If an instance of this class is changed it will create
 243     its own data internally so that other instances, which previously shared the
 244     data using the reference counting, are not affected.
 245
 246     You can retrieve the current system font settings with wxSystemSettings.
 247
 248     @library{wxcore}
 249     @category{gdi}
 250
 251     @stdobjects
 252     ::wxNullFont, ::wxNORMAL_FONT, ::wxSMALL_FONT, ::wxITALIC_FONT, ::wxSWISS_FONT
 253
 254     @see @ref overview_font, wxDC::SetFont, wxDC::DrawText,
 255          wxDC::GetTextExtent, wxFontDialog, wxSystemSettings
 256 */
 257 class wxFont : public wxGDIObject
 258 {
 259 public:
 260     /**
 261         Default ctor.
 262     */
 263     wxFont();
 264
 265     /**
 266         Copy constructor, uses @ref overview_refcount "reference counting".
 267     */
 268     wxFont(const wxFont& font);
 269
 270     /**
 271         Creates a font object with the specified attributes.
 272
 273         @param pointSize
 274             Size in points. See SetPointSize() for more info.
 275         @param family
 276             Font family, a generic way of referring to fonts without specifying actual
 277             facename. One of the ::wxFontFamily enumeration values.
 278         @param style
 279             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
 280         @param weight
 281             Font weight, sometimes also referred to as font boldness.
 282             One of the ::wxFontWeight enumeration values.
 283         @param underline
 284             The value can be @true or @false.
 285             At present this has an effect on Windows and Motif 2.x only.
 286         @param faceName
 287             An optional string specifying the actual typeface to be used.
 288             If it is an empty string, a default typeface will be chosen based on the family.
 289         @param encoding
 290             An encoding which may be one of the enumeration values of ::wxFontEncoding.
 291             Briefly these can be summed up as:
 292             <TABLE>
 293                 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
 294                 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
 295                     Default application encoding: this is the encoding set by calls to
 296                     SetDefaultEncoding() and which may be set to, say, KOI8 to create all
 297                     fonts by default with KOI8 encoding. Initially, the default application
 298                     encoding is the same as default system encoding.</TD></TR>
 299                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 300                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 301                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 302             </TABLE>
 303             If the specified encoding isn't available, no font is created
 304             (see also @ref overview_fontencoding).
 305
 306         @remarks If the desired font does not exist, the closest match will be
 307                  chosen. Under Windows, only scalable TrueType fonts are used.
 308     */
 309     wxFont(int pointSize, wxFontFamily family, wxFontStyle style,
 310            wxFontWeight weight,
 311            bool underline = false,
 312            const wxString& faceName = wxEmptyString,
 313            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 314
 315     /**
 316         Creates a font object with the specified attributes.
 317
 318         @param pixelSize
 319             Size in pixels. See SetPixelSize() for more info.
 320         @param family
 321             Font family, a generic way of referring to fonts without specifying actual
 322             facename. One of ::wxFontFamily enumeration values.
 323         @param style
 324             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
 325         @param weight
 326             Font weight, sometimes also referred to as font boldness.
 327             One of the ::wxFontWeight enumeration values.
 328         @param underline
 329             The value can be @true or @false.
 330             At present this has an effect on Windows and Motif 2.x only.
 331         @param faceName
 332             An optional string specifying the actual typeface to be used.
 333             If it is an empty string, a default typeface will be chosen based on the family.
 334         @param encoding
 335             An encoding which may be one of the enumeration values of ::wxFontEncoding.
 336             Briefly these can be summed up as:
 337             <TABLE>
 338                 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
 339                 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
 340                     Default application encoding: this is the encoding set by calls to
 341                     SetDefaultEncoding() and which may be set to, say, KOI8 to create all
 342                     fonts by default with KOI8 encoding. Initially, the default application
 343                     encoding is the same as default system encoding.</TD></TR>
 344                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 345                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 346                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 347             </TABLE>
 348             If the specified encoding isn't available, no font is created
 349             (see also @ref overview_fontencoding).
 350
 351         @remarks If the desired font does not exist, the closest match will be
 352                  chosen. Under Windows, only scalable TrueType fonts are used.
 353     */
 354     wxFont(const wxSize& pixelSize, wxFontFamily family,
 355            wxFontStyle style, wxFontWeight weight,
 356            bool underline = false,
 357            const wxString& faceName = wxEmptyString,
 358            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 359
 360     /**
 361         Destructor.
 362
 363         See @ref overview_refcount_destruct "reference-counted object destruction"
 364         for more info.
 365
 366         @remarks Although all remaining fonts are deleted when the application
 367                  exits, the application should try to clean up all fonts
 368                  itself. This is because wxWidgets cannot know if a
 369                  pointer to the font object is stored in an application
 370                  data structure, and there is a risk of double deletion.
 371     */
 372     virtual ~wxFont();
 373
 374     /**
 375         Returns the current application's default encoding.
 376
 377         @see @ref overview_fontencoding, SetDefaultEncoding()
 378     */
 379     static wxFontEncoding GetDefaultEncoding();
 380
 381     /**
 382         Returns the typeface name associated with the font, or the empty string if
 383         there is no typeface information.
 384
 385         @see SetFaceName()
 386     */
 387     virtual wxString GetFaceName() const;
 388
 389     /**
 390         Gets the font family. See SetFamily() for a list of valid
 391         family identifiers.
 392
 393         @see SetFamily()
 394     */
 395     virtual wxFontFamily GetFamily() const;
 396
 397     /**
 398         Returns the platform-dependent string completely describing this font.
 399         Returned string is always non-empty.
 400
 401         Note that the returned string is not meant to be shown or edited by the user: a
 402         typical use of this function is for serializing in string-form a wxFont object.
 403
 404         @see SetNativeFontInfo(),GetNativeFontInfoUserDesc()
 405     */
 406     wxString GetNativeFontInfoDesc() const;
 407
 408     /**
 409         Returns a user-friendly string for this font object.
 410         Returned string is always non-empty.
 411
 412         Some examples of the formats of returned strings (which are platform-dependent)
 413         are in SetNativeFontInfoUserDesc().
 414
 415         @see GetNativeFontInfoDesc()
 416     */
 417     wxString GetNativeFontInfoUserDesc() const;
 418
 419     /**
 420         Gets the point size.
 421
 422         @see SetPointSize()
 423     */
 424     virtual int GetPointSize() const;
 425
 426     /**
 427         Gets the pixel size.
 428
 429         Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
 430         a wxSize object with a null width value, you'll get a null width in
 431         the returned object.
 432
 433         @see SetPixelSize()
 434     */
 435     virtual wxSize GetPixelSize() const;
 436
 437     /**
 438         Gets the font style. See ::wxFontStyle for a list of valid styles.
 439
 440         @see SetStyle()
 441     */
 442     virtual wxFontStyle GetStyle() const;
 443
 444     /**
 445         Returns @true if the font is underlined, @false otherwise.
 446
 447         @see SetUnderlined()
 448     */
 449     virtual bool GetUnderlined() const;
 450
 451     /**
 452         Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
 453
 454         @see SetWeight()
 455     */
 456     virtual wxFontWeight GetWeight() const;
 457
 458     /**
 459         Returns @true if the font is a fixed width (or monospaced) font,
 460         @false if it is a proportional one or font is invalid.
 461     */
 462     virtual bool IsFixedWidth() const;
 463
 464     /**
 465         Returns @true if this object is a valid font, @false otherwise.
 466     */
 467     virtual bool IsOk() const;
 468
 469     //@{
 470     /**
 471         This function takes the same parameters as the relative
 472         @ref wxFont::wxFont "wxFont constructor" and returns a new font
 473         object allocated on the heap.
 474     */
 475     static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
 476                        wxFontWeight weight,
 477                        bool underline = false,
 478                        const wxString& faceName = wxEmptyString,
 479                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 480     static wxFont* New(int pointSize, wxFontFamily family,
 481                        int flags = wxFONTFLAG_DEFAULT,
 482                        const wxString& faceName = wxEmptyString,
 483                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 484     static wxFont* New(const wxSize& pixelSize,
 485                        wxFontFamily family,
 486                        wxFontStyle style,
 487                        wxFontWeight weight,
 488                        bool underline = false,
 489                        const wxString& faceName = wxEmptyString,
 490                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 491     static wxFont* New(const wxSize& pixelSize,
 492                        wxFontFamily family,
 493                        int flags = wxFONTFLAG_DEFAULT,
 494                        const wxString& faceName = wxEmptyString,
 495                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 496     //@}
 497
 498     /**
 499         Sets the default font encoding.
 500
 501         @see @ref overview_fontencoding, GetDefaultEncoding()
 502     */
 503     static void SetDefaultEncoding(wxFontEncoding encoding);
 504
 505     /**
 506         Sets the facename for the font.
 507         Returns @true if the given face name exists; @false otherwise.
 508
 509         @param faceName
 510             A valid facename, which should be on the end-user's system.
 511
 512         @remarks To avoid portability problems, don't rely on a specific face,
 513                  but specify the font family instead or as well.
 514                  A suitable font will be found on the end-user's system.
 515                  If both the family and the facename are specified,
 516                  wxWidgets will first search for the specific face, and
 517                  then for a font belonging to the same family.
 518
 519         @see GetFaceName(), SetFamily()
 520     */
 521     virtual bool SetFaceName(const wxString& faceName);
 522
 523     /**
 524         Sets the font family.
 525
 526         @param family
 527             One of the ::wxFontFamily values.
 528
 529         @see GetFamily(), SetFaceName()
 530     */
 531     virtual void SetFamily(wxFontFamily family);
 532
 533     /**
 534         Creates the font corresponding to the given native font description string
 535         which must have been previously returned by GetNativeFontInfoDesc().
 536
 537         If the string is invalid, font is unchanged.
 538         This function is typically used for de-serializing a wxFont object
 539         previously saved in a string-form.
 540
 541         @return @true if the creation was successful.
 542
 543         @see SetNativeFontInfoUserDesc()
 544     */
 545     bool SetNativeFontInfo(const wxString& info);
 546
 547     /**
 548         Creates the font corresponding to the given native font description string and
 549         returns @true if the creation was successful.
 550
 551         Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly.
 552         Examples of accepted string formats are:
 553
 554         @beginTable
 555         @hdr3col{platform, generic syntax, example}
 556         @row3col{wxGTK2, <tt>[FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
 557         @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
 558         @endTable
 559
 560         @todo add an example for wxMac
 561
 562         For more detailed information about the allowed syntaxes you can look at the
 563         documentation of the native API used for font-rendering
 564         (e.g. @c pango_font_description_from_string on GTK).
 565
 566         @see SetNativeFontInfo()
 567     */
 568     bool SetNativeFontInfoUserDesc(const wxString& info);
 569
 570     /**
 571         Sets the point size.
 572
 573         The <em>point size</em> is defined as 1/72 of the anglo-Saxon inch
 574         (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
 575
 576         @param pointSize
 577             Size in points.
 578
 579         @see GetPointSize()
 580     */
 581     virtual void SetPointSize(int pointSize);
 582
 583     /**
 584         Sets the pixel size.
 585
 586         The height parameter of @a pixelSize must be positive while the width
 587         parameter may also be zero (to indicate that you're not interested in the
 588         width of the characters: a suitable width will be chosen for best rendering).
 589
 590         This feature (specifying the font pixel size) is directly supported only
 591         under wxMSW and wxGTK currently; under other platforms a font with the
 592         closest size to the given one is found using binary search (this maybe slower).
 593
 594         @see GetPixelSize()
 595     */
 596     virtual void SetPixelSize(const wxSize& pixelSize);
 597
 598     /**
 599         Sets the font style.
 600
 601         @param style
 602             One of the ::wxFontStyle enumeration values.
 603
 604         @see GetStyle()
 605     */
 606     virtual void SetStyle(wxFontStyle style);
 607
 608     /**
 609         Sets underlining.
 610
 611         @param underlined
 612             @true to underline, @false otherwise.
 613
 614         @see GetUnderlined()
 615     */
 616     virtual void SetUnderlined(bool underlined);
 617
 618     /**
 619         Sets the font weight.
 620
 621         @param weight
 622             One of the ::wxFontWeight values.
 623
 624         @see GetWeight()
 625     */
 626     virtual void SetWeight(wxFontWeight weight);
 627
 628     /**
 629         Inequality operator.
 630
 631         See @ref overview_refcount_equality "reference-counted object comparison" for
 632         more info.
 633     */
 634     bool operator!=(const wxFont& font) const;
 635
 636     /**
 637         Equality operator.
 638
 639         See @ref overview_refcount_equality "reference-counted object comparison" for
 640         more info.
 641     */
 642     bool operator==(const wxFont& font) const;
 643
 644     /**
 645         Assignment operator, using @ref overview_refcount "reference counting".
 646     */
 647     wxFont& operator =(const wxFont& font);
 648 };
 649
 650
 651 /**
 652     An empty wxFont.
 653 */
 654 wxFont wxNullFont;
 655
 656 /**
 657     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
 658
 659     @see wxSystemSettings
 660 */
 661 wxFont wxNORMAL_FONT;
 662
 663 /**
 664     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
 665     ::wxNORMAL_FONT.
 666 */
 667 wxFont wxSMALL_FONT;
 668
 669 /**
 670     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
 671     of the same size of ::wxNORMAL_FONT.
 672 */
 673 wxFont wxITALIC_FONT;
 674
 675 /**
 676     A font identic to ::wxNORMAL_FONT except for the family used which is
 677     @c wxFONTFAMILY_SWISS.
 678 */
 679 wxFont wxSWISS_FONT;
 680
 681
 682 /**
 683     @class wxFontList
 684
 685     A font list is a list containing all fonts which have been created.
 686     There is only one instance of this class: ::wxTheFontList.
 687
 688     Use this object to search for a previously created font of the desired type
 689     and create it if not already found.
 690
 691     In some windowing systems, the font may be a scarce resource, so it is best to
 692     reuse old resources if possible.  When an application finishes, all fonts will
 693     be deleted and their resources freed, eliminating the possibility of 'memory
 694     leaks'.
 695
 696     @library{wxcore}
 697     @category{gdi}
 698
 699     @see wxFont
 700 */
 701 class wxFontList : public wxList
 702 {
 703 public:
 704     /**
 705         Constructor. The application should not construct its own font list:
 706         use the object pointer ::wxTheFontList.
 707     */
 708     wxFontList();
 709
 710     /**
 711         Finds a font of the given specification, or creates one and adds it to the
 712         list. See the @ref wxFont "wxFont constructor" for details of the arguments.
 713     */
 714     wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
 715                              wxFontWeight weight, bool underline = false,
 716                              const wxString& facename = wxEmptyString,
 717                              wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 718 };
 719
 720
 721 /**
 722     The global wxFontList instance.
 723 */
 724 wxFontList* wxTheFontList;
 725
 726
 727 // ============================================================================
 728 // Global functions/macros
 729 // ============================================================================
 730
 731 /** @addtogroup group_funcmacro_misc */
 732 //@{
 733
 734 /**
 735     Converts string to a wxFont best represented by the given string. Returns
 736     @true on success.
 737
 738     @see wxToString(const wxFont&)
 739
 740     @header{wx/font.h}
 741 */
 742 bool wxFromString(const wxString& string, wxFont* font);
 743
 744 /**
 745     Converts the given wxFont into a string.
 746
 747     @see wxFromString(const wxString&, wxFont*)
 748
 749     @header{wx/font.h}
 750 */
 751 wxString wxToString(const wxFont& font);
 752
 753 //@}
 754