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