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