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