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
 289                     is the encoding set by calls to
 290                     SetDefaultEncoding and which may be set to,
 291                     say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the
 292                     default application encoding is the same as default system encoding.</TD></TR>
 293                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 294                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 295                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 296             </TABLE>
 297             If the specified encoding isn't available, no font is created
 298             (see also font encoding overview).
 299
 300         @remarks If the desired font does not exist, the closest match will be
 301                  chosen. Under Windows, only scalable TrueType fonts are used.
 302     */
 303     wxFont(int pointSize, wxFontFamily family, wxFontStyle style,
 304            wxFontWeight weight,
 305            bool underline = false,
 306            const wxString& faceName = wxEmptyString,
 307            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 308
 309     /**
 310         Creates a font object with the specified attributes.
 311
 312         @param pixelSize
 313             Size in pixels. See SetPixelSize() for more info.
 314         @param family
 315             Font family, a generic way of referring to fonts without specifying actual
 316             facename. One of ::wxFontFamily enumeration values.
 317         @param style
 318             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
 319         @param weight
 320             Font weight, sometimes also referred to as font boldness.
 321             One of the ::wxFontWeight enumeration values.
 322         @param underline
 323             The value can be @true or @false.
 324             At present this has an effect on Windows and Motif 2.x only.
 325         @param faceName
 326             An optional string specifying the actual typeface to be used.
 327             If it is an empty string, a default typeface will be chosen based on the family.
 328         @param encoding
 329             An encoding which may be one of the enumeration values of ::wxFontEncoding.
 330             Briefly these can be summed up as:
 331             <TABLE>
 332                 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
 333                 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
 334                     Default application encoding: this
 335                     is the encoding set by calls to
 336                     SetDefaultEncoding and which may be set to,
 337                     say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the
 338                     default application encoding is the same as default system encoding.</TD></TR>
 339                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 340                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 341                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 342             </TABLE>
 343             If the specified encoding isn't available, no font is created
 344             (see also font encoding overview).
 345
 346         @remarks If the desired font does not exist, the closest match will be
 347                  chosen. Under Windows, only scalable TrueType fonts are used.
 348     */
 349     wxFont(const wxSize& pixelSize, wxFontFamily family,
 350            wxFontStyle style, wxFontWeight weight,
 351            bool underline = false,
 352            const wxString& faceName = wxEmptyString,
 353            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 354
 355     /**
 356         Destructor.
 357
 358         See @ref overview_refcount_destruct "reference-counted object destruction"
 359         for more info.
 360
 361         @remarks Although all remaining fonts are deleted when the application
 362                  exits, the application should try to clean up all fonts
 363                  itself. This is because wxWidgets cannot know if a
 364                  pointer to the font object is stored in an application
 365                  data structure, and there is a risk of double deletion.
 366     */
 367     virtual ~wxFont();
 368
 369     /**
 370         Returns the current application's default encoding.
 371
 372         @see @ref overview_fontencoding, SetDefaultEncoding()
 373     */
 374     static wxFontEncoding GetDefaultEncoding();
 375
 376     /**
 377         Returns the typeface name associated with the font, or the empty string if
 378         there is no typeface information.
 379
 380         @see SetFaceName()
 381     */
 382     virtual wxString GetFaceName() const;
 383
 384     /**
 385         Gets the font family. See SetFamily() for a list of valid
 386         family identifiers.
 387
 388         @see SetFamily()
 389     */
 390     virtual wxFontFamily GetFamily() const;
 391
 392     /**
 393         Returns the platform-dependent string completely describing this font.
 394         Returned string is always non-empty.
 395
 396         Note that the returned string is not meant to be shown or edited by the user: a
 397         typical use of this function is for serializing in string-form a wxFont object.
 398
 399         @see SetNativeFontInfo(),GetNativeFontInfoUserDesc()
 400     */
 401     wxString GetNativeFontInfoDesc() const;
 402
 403     /**
 404         Returns a user-friendly string for this font object.
 405         Returned string is always non-empty.
 406
 407         Some examples of the formats of returned strings (which are platform-dependent)
 408         are in SetNativeFontInfoUserDesc().
 409
 410         @see GetNativeFontInfoDesc()
 411     */
 412     wxString GetNativeFontInfoUserDesc() const;
 413
 414     /**
 415         Gets the point size.
 416
 417         @see SetPointSize()
 418     */
 419     virtual int GetPointSize() const;
 420
 421     /**
 422         Gets the pixel size.
 423
 424         Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
 425         a wxSize object with a null width value, you'll get a null width in
 426         the returned object.
 427
 428         @see SetPixelSize()
 429     */
 430     virtual wxSize GetPixelSize() const;
 431
 432     /**
 433         Gets the font style. See ::wxFontStyle for a list of valid styles.
 434
 435         @see SetStyle()
 436     */
 437     virtual wxFontStyle GetStyle() const;
 438
 439     /**
 440         Returns @true if the font is underlined, @false otherwise.
 441
 442         @see SetUnderlined()
 443     */
 444     virtual bool GetUnderlined() const;
 445
 446     /**
 447         Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
 448
 449         @see SetWeight()
 450     */
 451     virtual wxFontWeight GetWeight() const;
 452
 453     /**
 454         Returns @true if the font is a fixed width (or monospaced) font,
 455         @false if it is a proportional one or font is invalid.
 456     */
 457     virtual bool IsFixedWidth() const;
 458
 459     /**
 460         Returns @true if this object is a valid font, @false otherwise.
 461     */
 462     virtual bool IsOk() const;
 463
 464     //@{
 465     /**
 466         This function takes the same parameters as the relative
 467         @ref wxFont::wxFont "wxFont constructor" and returns a new font
 468         object allocated on the heap.
 469     */
 470     static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
 471                        wxFontWeight weight,
 472                        bool underline = false,
 473                        const wxString& faceName = wxEmptyString,
 474                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 475     static wxFont* New(int pointSize, wxFontFamily family,
 476                        int flags = wxFONTFLAG_DEFAULT,
 477                        const wxString& faceName = wxEmptyString,
 478                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 479     static wxFont* New(const wxSize& pixelSize,
 480                        wxFontFamily family,
 481                        wxFontStyle style,
 482                        wxFontWeight weight,
 483                        bool underline = false,
 484                        const wxString& faceName = wxEmptyString,
 485                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 486     static wxFont* New(const wxSize& pixelSize,
 487                        wxFontFamily family,
 488                        int flags = wxFONTFLAG_DEFAULT,
 489                        const wxString& faceName = wxEmptyString,
 490                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 491     //@}
 492
 493     /**
 494         Sets the default font encoding.
 495
 496         @see @ref overview_fontencoding, GetDefaultEncoding()
 497     */
 498     static void SetDefaultEncoding(wxFontEncoding encoding);
 499
 500     /**
 501         Sets the facename for the font.
 502         Returns @true if the given face name exists; @false otherwise.
 503
 504         @param faceName
 505             A valid facename, which should be on the end-user's system.
 506
 507         @remarks To avoid portability problems, don't rely on a specific face,
 508                  but specify the font family instead or as well.
 509                  A suitable font will be found on the end-user's system.
 510                  If both the family and the facename are specified,
 511                  wxWidgets will first search for the specific face, and
 512                  then for a font belonging to the same family.
 513
 514         @see GetFaceName(), SetFamily()
 515     */
 516     virtual bool SetFaceName(const wxString& faceName);
 517
 518     /**
 519         Sets the font family.
 520
 521         @param family
 522             One of the ::wxFontFamily values.
 523
 524         @see GetFamily(), SetFaceName()
 525     */
 526     virtual void SetFamily(wxFontFamily family);
 527
 528     /**
 529         Creates the font corresponding to the given native font description string
 530         which must have been previously returned by GetNativeFontInfoDesc().
 531
 532         If the string is invalid, font is unchanged.
 533         This function is typically used for de-serializing a wxFont object
 534         previously saved in a string-form.
 535
 536         @return @true if the creation was successful.
 537
 538         @see SetNativeFontInfoUserDesc()
 539     */
 540     bool SetNativeFontInfo(const wxString& info);
 541
 542     /**
 543         Creates the font corresponding to the given native font description string and
 544         returns @true if the creation was successful.
 545
 546         Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly.
 547         Examples of accepted string formats are:
 548
 549         @beginTable
 550         @hdr3col{platform, generic syntax, example}
 551         @row3col{wxGTK2, <tt>[FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
 552         @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
 553         @endTable
 554
 555         @todo add an example for wxMac
 556
 557         For more detailed information about the allowed syntaxes you can look at the
 558         documentation of the native API used for font-rendering
 559         (e.g. @c pango_font_description_from_string on GTK).
 560
 561         @see SetNativeFontInfo()
 562     */
 563     bool SetNativeFontInfoUserDesc(const wxString& info);
 564
 565     /**
 566         Sets the point size.
 567
 568         The <em>point size</em> is defined as 1/72 of the anglo-Saxon inch
 569         (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
 570
 571         @param pointSize
 572             Size in points.
 573
 574         @see GetPointSize()
 575     */
 576     virtual void SetPointSize(int pointSize);
 577
 578     /**
 579         Sets the pixel size.
 580
 581         The height parameter of @a pixelSize must be positive while the width
 582         parameter may also be zero (to indicate that you're not interested in the
 583         width of the characters: a suitable width will be chosen for best rendering).
 584
 585         This feature (specifying the font pixel size) is directly supported only
 586         under wxMSW and wxGTK currently; under other platforms a font with the
 587         closest size to the given one is found using binary search (this maybe slower).
 588
 589         @see GetPixelSize()
 590     */
 591     virtual void SetPixelSize(const wxSize& pixelSize);
 592
 593     /**
 594         Sets the font style.
 595
 596         @param style
 597             One of the ::wxFontStyle enumeration values.
 598
 599         @see GetStyle()
 600     */
 601     virtual void SetStyle(wxFontStyle style);
 602
 603     /**
 604         Sets underlining.
 605
 606         @param underlined
 607             @true to underline, @false otherwise.
 608
 609         @see GetUnderlined()
 610     */
 611     virtual void SetUnderlined(bool underlined);
 612
 613     /**
 614         Sets the font weight.
 615
 616         @param weight
 617             One of the ::wxFontWeight values.
 618
 619         @see GetWeight()
 620     */
 621     virtual void SetWeight(wxFontWeight weight);
 622
 623     /**
 624         Inequality operator.
 625
 626         See @ref overview_refcount_equality "reference-counted object comparison" for
 627         more info.
 628     */
 629     bool operator!=(const wxFont& font) const;
 630
 631     /**
 632         Equality operator.
 633
 634         See @ref overview_refcount_equality "reference-counted object comparison" for
 635         more info.
 636     */
 637     bool operator==(const wxFont& font) const;
 638
 639     /**
 640         Assignment operator, using @ref overview_refcount "reference counting".
 641     */
 642     wxFont& operator =(const wxFont& font);
 643 };
 644
 645
 646 /**
 647     An empty wxFont.
 648 */
 649 wxFont wxNullFont;
 650
 651 /**
 652     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
 653
 654     @see wxSystemSettings
 655 */
 656 wxFont wxNORMAL_FONT;
 657
 658 /**
 659     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
 660     ::wxNORMAL_FONT.
 661 */
 662 wxFont wxSMALL_FONT;
 663
 664 /**
 665     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
 666     of the same size of ::wxNORMAL_FONT.
 667 */
 668 wxFont wxITALIC_FONT;
 669
 670 /**
 671     A font identic to ::wxNORMAL_FONT except for the family used which is
 672     @c wxFONTFAMILY_SWISS.
 673 */
 674 wxFont wxSWISS_FONT;
 675
 676
 677 /**
 678     @class wxFontList
 679
 680     A font list is a list containing all fonts which have been created.
 681     There is only one instance of this class: ::wxTheFontList.
 682
 683     Use this object to search for a previously created font of the desired type
 684     and create it if not already found.
 685
 686     In some windowing systems, the font may be a scarce resource, so it is best to
 687     reuse old resources if possible.  When an application finishes, all fonts will
 688     be deleted and their resources freed, eliminating the possibility of 'memory
 689     leaks'.
 690
 691     @library{wxcore}
 692     @category{gdi}
 693
 694     @see wxFont
 695 */
 696 class wxFontList : public wxList
 697 {
 698 public:
 699     /**
 700         Constructor. The application should not construct its own font list:
 701         use the object pointer ::wxTheFontList.
 702     */
 703     wxFontList();
 704
 705     /**
 706         Finds a font of the given specification, or creates one and adds it to the
 707         list. See the @ref wxFont "wxFont constructor" for details of the arguments.
 708     */
 709     wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
 710                              wxFontWeight weight, bool underline = false,
 711                              const wxString& facename = wxEmptyString,
 712                              wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 713 };
 714
 715
 716 /**
 717     The global wxFontList instance.
 718 */
 719 wxFontList* wxTheFontList;
 720
 721
 722 // ============================================================================
 723 // Global functions/macros
 724 // ============================================================================
 725
 726 /** @addtogroup group_funcmacro_misc */
 727 //@{
 728
 729 /**
 730     Converts string to a wxFont best represented by the given string. Returns
 731     @true on success.
 732
 733     @see wxToString(const wxFont&)
 734
 735     @header{wx/font.h}
 736 */
 737 bool wxFromString(const wxString& string, wxFont* font);
 738
 739 /**
 740     Converts the given wxFont into a string.
 741
 742     @see wxFromString(const wxString&, wxFont*)
 743
 744     @header{wx/font.h}
 745 */
 746 wxString wxToString(const wxFont& font);
 747
 748 //@}
 749