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         The string does not encode all wxFont infos under all platforms;
 413         e.g. under wxMSW the font family is not present in the returned string.
 414
 415         Some examples of the formats of returned strings (which are platform-dependent)
 416         are in SetNativeFontInfoUserDesc().
 417
 418         @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()
 419     */
 420     wxString GetNativeFontInfoUserDesc() const;
 421
 422     /**
 423         Gets the point size.
 424
 425         @see SetPointSize()
 426     */
 427     virtual int GetPointSize() const;
 428
 429     /**
 430         Gets the pixel size.
 431
 432         Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
 433         a wxSize object with a null width value, you'll get a null width in
 434         the returned object.
 435
 436         @see SetPixelSize()
 437     */
 438     virtual wxSize GetPixelSize() const;
 439
 440     /**
 441         Gets the font style. See ::wxFontStyle for a list of valid styles.
 442
 443         @see SetStyle()
 444     */
 445     virtual wxFontStyle GetStyle() const;
 446
 447     /**
 448         Returns @true if the font is underlined, @false otherwise.
 449
 450         @see SetUnderlined()
 451     */
 452     virtual bool GetUnderlined() const;
 453
 454     /**
 455         Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
 456
 457         @see SetWeight()
 458     */
 459     virtual wxFontWeight GetWeight() const;
 460
 461     /**
 462         Returns @true if the font is a fixed width (or monospaced) font,
 463         @false if it is a proportional one or font is invalid.
 464     */
 465     virtual bool IsFixedWidth() const;
 466
 467     /**
 468         Returns @true if this object is a valid font, @false otherwise.
 469     */
 470     virtual bool IsOk() const;
 471
 472     //@{
 473     /**
 474         This function takes the same parameters as the relative
 475         @ref wxFont::wxFont "wxFont constructor" and returns a new font
 476         object allocated on the heap.
 477     */
 478     static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
 479                        wxFontWeight weight,
 480                        bool underline = false,
 481                        const wxString& faceName = wxEmptyString,
 482                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 483     static wxFont* New(int pointSize, wxFontFamily family,
 484                        int flags = wxFONTFLAG_DEFAULT,
 485                        const wxString& faceName = wxEmptyString,
 486                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 487     static wxFont* New(const wxSize& pixelSize,
 488                        wxFontFamily family,
 489                        wxFontStyle style,
 490                        wxFontWeight weight,
 491                        bool underline = false,
 492                        const wxString& faceName = wxEmptyString,
 493                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 494     static wxFont* New(const wxSize& pixelSize,
 495                        wxFontFamily family,
 496                        int flags = wxFONTFLAG_DEFAULT,
 497                        const wxString& faceName = wxEmptyString,
 498                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 499     //@}
 500
 501     /**
 502         Sets the default font encoding.
 503
 504         @see @ref overview_fontencoding, GetDefaultEncoding()
 505     */
 506     static void SetDefaultEncoding(wxFontEncoding encoding);
 507
 508     /**
 509         Sets the facename for the font.
 510         Returns @true if the given face name exists; @false otherwise.
 511
 512         @param faceName
 513             A valid facename, which should be on the end-user's system.
 514
 515         @remarks To avoid portability problems, don't rely on a specific face,
 516                  but specify the font family instead or as well.
 517                  A suitable font will be found on the end-user's system.
 518                  If both the family and the facename are specified,
 519                  wxWidgets will first search for the specific face, and
 520                  then for a font belonging to the same family.
 521
 522         @see GetFaceName(), SetFamily()
 523     */
 524     virtual bool SetFaceName(const wxString& faceName);
 525
 526     /**
 527         Sets the font family.
 528
 529         @param family
 530             One of the ::wxFontFamily values.
 531
 532         @see GetFamily(), SetFaceName()
 533     */
 534     virtual void SetFamily(wxFontFamily family);
 535
 536     /**
 537         Creates the font corresponding to the given native font description string
 538         which must have been previously returned by GetNativeFontInfoDesc().
 539
 540         If the string is invalid, font is unchanged.
 541         This function is typically used for de-serializing a wxFont object
 542         previously saved in a string-form.
 543
 544         @return @true if the creation was successful.
 545
 546         @see SetNativeFontInfoUserDesc()
 547     */
 548     bool SetNativeFontInfo(const wxString& info);
 549
 550     /**
 551         Creates the font corresponding to the given native font description string and
 552         returns @true if the creation was successful.
 553
 554         Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly.
 555         Examples of accepted string formats are:
 556
 557         @beginTable
 558         @hdr3col{platform, generic syntax, example}
 559         @row3col{wxGTK2, <tt>[FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
 560         @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
 561         @endTable
 562
 563         @todo add an example for wxMac
 564
 565         For more detailed information about the allowed syntaxes you can look at the
 566         documentation of the native API used for font-rendering
 567         (e.g. @c pango_font_description_from_string on GTK).
 568
 569         Note that unlike SetNativeFontInfo(), this function doesn't always restore all
 570         attributes of the wxFont object under all platforms; e.g. on wxMSW the font family
 571         is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW).
 572         If you want to serialize/deserialize a font in string form, you should use
 573         GetNativeFontInfoDesc() and SetNativeFontInfo() instead.
 574
 575         @see SetNativeFontInfo()
 576     */
 577     bool SetNativeFontInfoUserDesc(const wxString& info);
 578
 579     /**
 580         Sets the point size.
 581
 582         The <em>point size</em> is defined as 1/72 of the anglo-Saxon inch
 583         (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
 584
 585         @param pointSize
 586             Size in points.
 587
 588         @see GetPointSize()
 589     */
 590     virtual void SetPointSize(int pointSize);
 591
 592     /**
 593         Sets the pixel size.
 594
 595         The height parameter of @a pixelSize must be positive while the width
 596         parameter may also be zero (to indicate that you're not interested in the
 597         width of the characters: a suitable width will be chosen for best rendering).
 598
 599         This feature (specifying the font pixel size) is directly supported only
 600         under wxMSW and wxGTK currently; under other platforms a font with the
 601         closest size to the given one is found using binary search (this maybe slower).
 602
 603         @see GetPixelSize()
 604     */
 605     virtual void SetPixelSize(const wxSize& pixelSize);
 606
 607     /**
 608         Sets the font style.
 609
 610         @param style
 611             One of the ::wxFontStyle enumeration values.
 612
 613         @see GetStyle()
 614     */
 615     virtual void SetStyle(wxFontStyle style);
 616
 617     /**
 618         Sets underlining.
 619
 620         @param underlined
 621             @true to underline, @false otherwise.
 622
 623         @see GetUnderlined()
 624     */
 625     virtual void SetUnderlined(bool underlined);
 626
 627     /**
 628         Sets the font weight.
 629
 630         @param weight
 631             One of the ::wxFontWeight values.
 632
 633         @see GetWeight()
 634     */
 635     virtual void SetWeight(wxFontWeight weight);
 636
 637     /**
 638         Inequality operator.
 639
 640         See @ref overview_refcount_equality "reference-counted object comparison" for
 641         more info.
 642     */
 643     bool operator!=(const wxFont& font) const;
 644
 645     /**
 646         Equality operator.
 647
 648         See @ref overview_refcount_equality "reference-counted object comparison" for
 649         more info.
 650     */
 651     bool operator==(const wxFont& font) const;
 652
 653     /**
 654         Assignment operator, using @ref overview_refcount "reference counting".
 655     */
 656     wxFont& operator =(const wxFont& font);
 657 };
 658
 659
 660 /**
 661     An empty wxFont.
 662 */
 663 wxFont wxNullFont;
 664
 665 /**
 666     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
 667
 668     @see wxSystemSettings
 669 */
 670 wxFont wxNORMAL_FONT;
 671
 672 /**
 673     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
 674     ::wxNORMAL_FONT.
 675 */
 676 wxFont wxSMALL_FONT;
 677
 678 /**
 679     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
 680     of the same size of ::wxNORMAL_FONT.
 681 */
 682 wxFont wxITALIC_FONT;
 683
 684 /**
 685     A font identic to ::wxNORMAL_FONT except for the family used which is
 686     @c wxFONTFAMILY_SWISS.
 687 */
 688 wxFont wxSWISS_FONT;
 689
 690
 691 /**
 692     @class wxFontList
 693
 694     A font list is a list containing all fonts which have been created.
 695     There is only one instance of this class: ::wxTheFontList.
 696
 697     Use this object to search for a previously created font of the desired type
 698     and create it if not already found.
 699
 700     In some windowing systems, the font may be a scarce resource, so it is best to
 701     reuse old resources if possible.  When an application finishes, all fonts will
 702     be deleted and their resources freed, eliminating the possibility of 'memory
 703     leaks'.
 704
 705     @library{wxcore}
 706     @category{gdi}
 707
 708     @see wxFont
 709 */
 710 class wxFontList : public wxList
 711 {
 712 public:
 713     /**
 714         Constructor. The application should not construct its own font list:
 715         use the object pointer ::wxTheFontList.
 716     */
 717     wxFontList();
 718
 719     /**
 720         Finds a font of the given specification, or creates one and adds it to the
 721         list. See the @ref wxFont "wxFont constructor" for details of the arguments.
 722     */
 723     wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
 724                              wxFontWeight weight, bool underline = false,
 725                              const wxString& facename = wxEmptyString,
 726                              wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 727 };
 728
 729
 730 /**
 731     The global wxFontList instance.
 732 */
 733 wxFontList* wxTheFontList;
 734
 735
 736 // ============================================================================
 737 // Global functions/macros
 738 // ============================================================================
 739
 740 /** @addtogroup group_funcmacro_misc */
 741 //@{
 742
 743 /**
 744     Converts string to a wxFont best represented by the given string. Returns
 745     @true on success.
 746
 747     @see wxToString(const wxFont&)
 748
 749     @header{wx/font.h}
 750 */
 751 bool wxFromString(const wxString& string, wxFont* font);
 752
 753 /**
 754     Converts the given wxFont into a string.
 755
 756     @see wxFromString(const wxString&, wxFont*)
 757
 758     @header{wx/font.h}
 759 */
 760 wxString wxToString(const wxFont& font);
 761
 762 //@}
 763