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 licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     Standard font families: these are used mainly during wxFont creation to specify
  12     the generic properties of the font without hardcoding in the sources a specific
  13     face name.
  14
  15     wxFontFamily thus allows to group the font face names of fonts with similar
  16     properties. Most wxWidgets ports use lists of fonts for each font family
  17     inspired by the data taken from http://www.codestyle.org/css/font-family.
  18 */
  19 enum wxFontFamily
  20 {
  21     wxFONTFAMILY_DEFAULT = wxDEFAULT,           //!< Chooses a default font.
  22
  23     wxFONTFAMILY_DECORATIVE = wxDECORATIVE,     //!< A decorative font.
  24     wxFONTFAMILY_ROMAN = wxROMAN,               //!< A formal, serif font.
  25     wxFONTFAMILY_SCRIPT = wxSCRIPT,             //!< A handwriting font.
  26     wxFONTFAMILY_SWISS = wxSWISS,               //!< A sans-serif font.
  27
  28     /// A fixed pitch font. Note that wxFont currently does not make distinctions
  29     /// between @c wxFONTFAMILY_MODERN and @c wxFONTFAMILY_TELETYPE.
  30     wxFONTFAMILY_MODERN = wxMODERN,
  31
  32     /// A teletype (i.e. monospaced) font.
  33     /// Monospace fonts have a fixed width like typewriters and often have strong angular
  34     /// or block serifs. Monospace font faces are often used code samples and have a simple,
  35     /// functional font style.
  36     /// See also wxFont::IsFixedWidth() for an easy way to test for monospace property.
  37     wxFONTFAMILY_TELETYPE = wxTELETYPE,
  38
  39     /// Invalid font family value, returned by wxFont::GetFamily() when the
  40     /// font is invalid for example.
  41     wxFONTFAMILY_UNKNOWN
  42 };
  43
  44 /**
  45     Font styles.
  46 */
  47 enum wxFontStyle
  48 {
  49     /// The font is drawn without slant.
  50     wxFONTSTYLE_NORMAL = wxNORMAL,
  51
  52     /// The font is slanted in an italic style.
  53     wxFONTSTYLE_ITALIC = wxITALIC,
  54
  55     /// The font is slanted, but in a roman style.
  56     /// Note that under wxMSW this style is the same as @c wxFONTSTYLE_ITALIC.
  57     wxFONTSTYLE_SLANT = wxSLANT,
  58
  59     wxFONTSTYLE_MAX
  60 };
  61
  62 /**
  63     Font weights.
  64 */
  65 enum wxFontWeight
  66 {
  67     wxFONTWEIGHT_NORMAL = wxNORMAL,  //!< Normal font.
  68     wxFONTWEIGHT_LIGHT = wxLIGHT,    //!< Light font.
  69     wxFONTWEIGHT_BOLD = wxBOLD,      //!< Bold font.
  70     wxFONTWEIGHT_MAX
  71 };
  72
  73 /**
  74     Symbolic font sizes.
  75
  76     The elements of this enum correspond to CSS absolute size specifications,
  77     see http://www.w3.org/TR/CSS21/fonts.html#font-size-props
  78
  79     @see wxFont::SetSymbolicSize()
  80
  81     @since 2.9.2
  82  */
  83 enum wxFontSymbolicSize
  84 {
  85     wxFONTSIZE_XX_SMALL = -3,   //!< Extra small.
  86     wxFONTSIZE_X_SMALL,         //!< Very small.
  87     wxFONTSIZE_SMALL,           //!< Small.
  88     wxFONTSIZE_MEDIUM,          //!< Normal.
  89     wxFONTSIZE_LARGE,           //!< Large.
  90     wxFONTSIZE_X_LARGE,         //!< Very large.
  91     wxFONTSIZE_XX_LARGE         //!< Extra large.
  92 };
  93
  94 /**
  95     The font flag bits for the new font ctor accepting one combined flags word.
  96 */
  97 enum wxFontFlag
  98 {
  99     /// no special flags: font with default weight/slant/anti-aliasing
 100     wxFONTFLAG_DEFAULT          = 0,
 101
 102     /// slant flags (default: no slant)
 103     wxFONTFLAG_ITALIC           = 1 << 0,
 104     wxFONTFLAG_SLANT            = 1 << 1,
 105
 106     /// weight flags (default: medium)
 107     wxFONTFLAG_LIGHT            = 1 << 2,
 108     wxFONTFLAG_BOLD             = 1 << 3,
 109
 110     /// anti-aliasing flag: force on or off (default: the current system default)
 111     wxFONTFLAG_ANTIALIASED      = 1 << 4,
 112     wxFONTFLAG_NOT_ANTIALIASED  = 1 << 5,
 113
 114     /// underlined/strikethrough flags (default: no lines)
 115     wxFONTFLAG_UNDERLINED       = 1 << 6,
 116     wxFONTFLAG_STRIKETHROUGH    = 1 << 7,
 117
 118     /// the mask of all currently used flags
 119     wxFONTFLAG_MASK = wxFONTFLAG_ITALIC             |
 120                       wxFONTFLAG_SLANT              |
 121                       wxFONTFLAG_LIGHT              |
 122                       wxFONTFLAG_BOLD               |
 123                       wxFONTFLAG_ANTIALIASED        |
 124                       wxFONTFLAG_NOT_ANTIALIASED    |
 125                       wxFONTFLAG_UNDERLINED         |
 126                       wxFONTFLAG_STRIKETHROUGH
 127 };
 128
 129
 130
 131 /**
 132     Font encodings.
 133
 134     See wxFont::SetEncoding().
 135 */
 136 enum wxFontEncoding
 137 {
 138     /// Default system encoding.
 139     wxFONTENCODING_SYSTEM = -1,     // system default
 140
 141     /// Default application encoding.
 142     wxFONTENCODING_DEFAULT,         // current default encoding
 143
 144     // ISO8859 standard defines a number of single-byte charsets
 145     wxFONTENCODING_ISO8859_1,       //!< West European (Latin1)
 146     wxFONTENCODING_ISO8859_2,       //!< Central and East European (Latin2)
 147     wxFONTENCODING_ISO8859_3,       //!< Esperanto (Latin3)
 148     wxFONTENCODING_ISO8859_4,       //!< Baltic (old) (Latin4)
 149     wxFONTENCODING_ISO8859_5,       //!< Cyrillic
 150     wxFONTENCODING_ISO8859_6,       //!< Arabic
 151     wxFONTENCODING_ISO8859_7,       //!< Greek
 152     wxFONTENCODING_ISO8859_8,       //!< Hebrew
 153     wxFONTENCODING_ISO8859_9,       //!< Turkish (Latin5)
 154     wxFONTENCODING_ISO8859_10,      //!< Variation of Latin4 (Latin6)
 155     wxFONTENCODING_ISO8859_11,      //!< Thai
 156     wxFONTENCODING_ISO8859_12,      //!< doesn't exist currently, but put it
 157                                     //!< here anyhow to make all ISO8859
 158                                     //!< consecutive numbers
 159     wxFONTENCODING_ISO8859_13,      //!< Baltic (Latin7)
 160     wxFONTENCODING_ISO8859_14,      //!< Latin8
 161     wxFONTENCODING_ISO8859_15,      //!< Latin9 (a.k.a. Latin0, includes euro)
 162     wxFONTENCODING_ISO8859_MAX,
 163
 164     // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
 165     wxFONTENCODING_KOI8,            //!< KOI8 Russian
 166     wxFONTENCODING_KOI8_U,          //!< KOI8 Ukrainian
 167     wxFONTENCODING_ALTERNATIVE,     //!< same as MS-DOS CP866
 168     wxFONTENCODING_BULGARIAN,       //!< used under Linux in Bulgaria
 169
 170     // what would we do without Microsoft? They have their own encodings
 171         // for DOS
 172     wxFONTENCODING_CP437,           //!< original MS-DOS codepage
 173     wxFONTENCODING_CP850,           //!< CP437 merged with Latin1
 174     wxFONTENCODING_CP852,           //!< CP437 merged with Latin2
 175     wxFONTENCODING_CP855,           //!< another cyrillic encoding
 176     wxFONTENCODING_CP866,           //!< and another one
 177         // and for Windows
 178     wxFONTENCODING_CP874,           //!< WinThai
 179     wxFONTENCODING_CP932,           //!< Japanese (shift-JIS)
 180     wxFONTENCODING_CP936,           //!< Chinese simplified (GB)
 181     wxFONTENCODING_CP949,           //!< Korean (Hangul charset)
 182     wxFONTENCODING_CP950,           //!< Chinese (traditional - Big5)
 183     wxFONTENCODING_CP1250,          //!< WinLatin2
 184     wxFONTENCODING_CP1251,          //!< WinCyrillic
 185     wxFONTENCODING_CP1252,          //!< WinLatin1
 186     wxFONTENCODING_CP1253,          //!< WinGreek (8859-7)
 187     wxFONTENCODING_CP1254,          //!< WinTurkish
 188     wxFONTENCODING_CP1255,          //!< WinHebrew
 189     wxFONTENCODING_CP1256,          //!< WinArabic
 190     wxFONTENCODING_CP1257,          //!< WinBaltic (same as Latin 7)
 191     wxFONTENCODING_CP12_MAX,
 192
 193     wxFONTENCODING_UTF7,            //!< UTF-7 Unicode encoding
 194     wxFONTENCODING_UTF8,            //!< UTF-8 Unicode encoding
 195     wxFONTENCODING_EUC_JP,          //!< Extended Unix Codepage for Japanese
 196     wxFONTENCODING_UTF16BE,         //!< UTF-16 Big Endian Unicode encoding
 197     wxFONTENCODING_UTF16LE,         //!< UTF-16 Little Endian Unicode encoding
 198     wxFONTENCODING_UTF32BE,         //!< UTF-32 Big Endian Unicode encoding
 199     wxFONTENCODING_UTF32LE,         // UTF-32 Little Endian Unicode encoding
 200
 201     wxFONTENCODING_MACROMAN,        //!< the standard mac encodings
 202     wxFONTENCODING_MACJAPANESE,
 203     wxFONTENCODING_MACCHINESETRAD,
 204     wxFONTENCODING_MACKOREAN,
 205     wxFONTENCODING_MACARABIC,
 206     wxFONTENCODING_MACHEBREW,
 207     wxFONTENCODING_MACGREEK,
 208     wxFONTENCODING_MACCYRILLIC,
 209     wxFONTENCODING_MACDEVANAGARI,
 210     wxFONTENCODING_MACGURMUKHI,
 211     wxFONTENCODING_MACGUJARATI,
 212     wxFONTENCODING_MACORIYA,
 213     wxFONTENCODING_MACBENGALI,
 214     wxFONTENCODING_MACTAMIL,
 215     wxFONTENCODING_MACTELUGU,
 216     wxFONTENCODING_MACKANNADA,
 217     wxFONTENCODING_MACMALAJALAM,
 218     wxFONTENCODING_MACSINHALESE,
 219     wxFONTENCODING_MACBURMESE,
 220     wxFONTENCODING_MACKHMER,
 221     wxFONTENCODING_MACTHAI,
 222     wxFONTENCODING_MACLAOTIAN,
 223     wxFONTENCODING_MACGEORGIAN,
 224     wxFONTENCODING_MACARMENIAN,
 225     wxFONTENCODING_MACCHINESESIMP,
 226     wxFONTENCODING_MACTIBETAN,
 227     wxFONTENCODING_MACMONGOLIAN,
 228     wxFONTENCODING_MACETHIOPIC,
 229     wxFONTENCODING_MACCENTRALEUR,
 230     wxFONTENCODING_MACVIATNAMESE,
 231     wxFONTENCODING_MACARABICEXT,
 232     wxFONTENCODING_MACSYMBOL,
 233     wxFONTENCODING_MACDINGBATS,
 234     wxFONTENCODING_MACTURKISH,
 235     wxFONTENCODING_MACCROATIAN,
 236     wxFONTENCODING_MACICELANDIC,
 237     wxFONTENCODING_MACROMANIAN,
 238     wxFONTENCODING_MACCELTIC,
 239     wxFONTENCODING_MACGAELIC,
 240     wxFONTENCODING_MACKEYBOARD,
 241
 242     // more CJK encodings (for historical reasons some are already declared
 243     // above)
 244     wxFONTENCODING_ISO2022_JP,      //!< ISO-2022-JP JIS encoding
 245
 246     wxFONTENCODING_MAX,             //!< highest enumerated encoding value
 247
 248     wxFONTENCODING_MACMIN = wxFONTENCODING_MACROMAN ,
 249     wxFONTENCODING_MACMAX = wxFONTENCODING_MACKEYBOARD ,
 250
 251     // aliases for endian-dependent UTF encodings
 252     wxFONTENCODING_UTF16,  //!< native UTF-16
 253     wxFONTENCODING_UTF32,  //!< native UTF-32
 254
 255     /// Alias for the native Unicode encoding on this platform
 256     /// (this is used by wxEncodingConverter and wxUTFFile only for now)
 257     wxFONTENCODING_UNICODE,
 258
 259     wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese
 260     wxFONTENCODING_BIG5 = wxFONTENCODING_CP950,   //!< Traditional Chinese
 261     wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932, //!< Shift JIS
 262     wxFONTENCODING_EUC_KR = wxFONTENCODING_CP949 //!< Korean
 263 };
 264
 265
 266
 267 /**
 268     @class wxFont
 269
 270     A font is an object which determines the appearance of text.
 271     Fonts are used for drawing text to a device context, and setting the appearance
 272     of a window's text.
 273
 274     This class uses @ref overview_refcount "reference counting and copy-on-write"
 275     internally so that assignments between two instances of this class are very
 276     cheap. You can therefore use actual objects instead of pointers without
 277     efficiency problems. If an instance of this class is changed it will create
 278     its own data internally so that other instances, which previously shared the
 279     data using the reference counting, are not affected.
 280
 281     You can retrieve the current system font settings with wxSystemSettings.
 282
 283     @library{wxcore}
 284     @category{gdi}
 285
 286     @stdobjects
 287     ::wxNullFont, ::wxNORMAL_FONT, ::wxSMALL_FONT, ::wxITALIC_FONT, ::wxSWISS_FONT
 288
 289     @see @ref overview_font, wxDC::SetFont, wxDC::DrawText,
 290          wxDC::GetTextExtent, wxFontDialog, wxSystemSettings
 291 */
 292 class wxFont : public wxGDIObject
 293 {
 294 public:
 295     /**
 296         Default ctor.
 297     */
 298     wxFont();
 299
 300     /**
 301         Copy constructor, uses @ref overview_refcount "reference counting".
 302     */
 303     wxFont(const wxFont& font);
 304
 305     /**
 306         Creates a font object with the specified attributes.
 307
 308         @param pointSize
 309             Size in points. See SetPointSize() for more info.
 310         @param family
 311             The font family: a generic portable way of referring to fonts without specifying a
 312             facename. This parameter must be one of the ::wxFontFamily enumeration values.
 313             If the @a faceName argument is provided, then it overrides the font family.
 314         @param style
 315             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
 316         @param weight
 317             Font weight, sometimes also referred to as font boldness.
 318             One of the ::wxFontWeight enumeration values.
 319         @param underline
 320             The value can be @true or @false.
 321             At present this has an effect on Windows and Motif 2.x only.
 322         @param faceName
 323             An optional string specifying the face name to be used.
 324             If it is an empty string, a default face name will be chosen based on the family.
 325         @param encoding
 326             An encoding which may be one of the enumeration values of ::wxFontEncoding.
 327             Briefly these can be summed up as:
 328             <TABLE>
 329                 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
 330                 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
 331                     Default application encoding: this is the encoding set by calls to
 332                     SetDefaultEncoding() and which may be set to, say, KOI8 to create all
 333                     fonts by default with KOI8 encoding. Initially, the default application
 334                     encoding is the same as default system encoding.</TD></TR>
 335                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 336                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 337                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 338             </TABLE>
 339             If the specified encoding isn't available, no font is created
 340             (see also @ref overview_fontencoding).
 341
 342         @remarks If the desired font does not exist, the closest match will be
 343                  chosen. Under Windows, only scalable TrueType fonts are used.
 344     */
 345     wxFont(int pointSize, wxFontFamily family, wxFontStyle style,
 346            wxFontWeight weight,
 347            bool underline = false,
 348            const wxString& faceName = wxEmptyString,
 349            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 350
 351     /**
 352         Creates a font object with the specified attributes.
 353
 354         @param pixelSize
 355             Size in pixels. See SetPixelSize() for more info.
 356         @param family
 357             The font family: a generic portable way of referring to fonts without specifying a
 358             facename. This parameter must be one of the ::wxFontFamily enumeration values.
 359             If the @a faceName argument is provided, then it overrides the font family.
 360         @param style
 361             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
 362         @param weight
 363             Font weight, sometimes also referred to as font boldness.
 364             One of the ::wxFontWeight enumeration values.
 365         @param underline
 366             The value can be @true or @false.
 367             At present this has an effect on Windows and Motif 2.x only.
 368         @param faceName
 369             An optional string specifying the face name to be used.
 370             If it is an empty string, a default face name will be chosen based on the family.
 371         @param encoding
 372             An encoding which may be one of the enumeration values of ::wxFontEncoding.
 373             Briefly these can be summed up as:
 374             <TABLE>
 375                 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
 376                 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
 377                     Default application encoding: this is the encoding set by calls to
 378                     SetDefaultEncoding() and which may be set to, say, KOI8 to create all
 379                     fonts by default with KOI8 encoding. Initially, the default application
 380                     encoding is the same as default system encoding.</TD></TR>
 381                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 382                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 383                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 384             </TABLE>
 385             If the specified encoding isn't available, no font is created
 386             (see also @ref overview_fontencoding).
 387
 388         @remarks If the desired font does not exist, the closest match will be
 389                  chosen. Under Windows, only scalable TrueType fonts are used.
 390     */
 391     wxFont(const wxSize& pixelSize, wxFontFamily family,
 392            wxFontStyle style, wxFontWeight weight,
 393            bool underline = false,
 394            const wxString& faceName = wxEmptyString,
 395            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 396
 397     /**
 398         Constructor from font description string.
 399
 400         This constructor uses SetNativeFontInfo() to initialize the font.
 401         If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
 402         will return @false.
 403      */
 404     wxFont(const wxString& fontdesc);
 405
 406     /**
 407         Destructor.
 408
 409         See @ref overview_refcount_destruct "reference-counted object destruction"
 410         for more info.
 411
 412         @remarks Although all remaining fonts are deleted when the application
 413                  exits, the application should try to clean up all fonts
 414                  itself. This is because wxWidgets cannot know if a
 415                  pointer to the font object is stored in an application
 416                  data structure, and there is a risk of double deletion.
 417     */
 418     virtual ~wxFont();
 419
 420
 421     /**
 422         @name Getters
 423     */
 424     //@{
 425
 426     /**
 427         Returns the encoding of this font.
 428
 429         Note that under wxGTK the returned value is always @c wxFONTENCODING_UTF8.
 430
 431         @see SetEncoding()
 432     */
 433     virtual wxFontEncoding GetEncoding() const;
 434
 435     /**
 436         Returns the face name associated with the font, or the empty string if
 437         there is no face information.
 438
 439         @see SetFaceName()
 440     */
 441     virtual wxString GetFaceName() const;
 442
 443     /**
 444         Gets the font family if possible.
 445
 446         As described in ::wxFontFamily docs the returned value acts as a rough,
 447         basic classification of the main font properties (look, spacing).
 448
 449         If the current font face name is not recognized by wxFont or by the
 450         underlying system, @c wxFONTFAMILY_DEFAULT is returned.
 451
 452         Note that currently this function is not very precise and so not
 453         particularly useful. Font families mostly make sense only for font
 454         creation, see SetFamily().
 455
 456         @see SetFamily()
 457     */
 458     virtual wxFontFamily GetFamily() const;
 459
 460     /**
 461         Returns the platform-dependent string completely describing this font.
 462
 463         Returned string is always non-empty unless the font is invalid (in
 464         which case an assert is triggered).
 465
 466         Note that the returned string is not meant to be shown or edited by the user: a
 467         typical use of this function is for serializing in string-form a wxFont object.
 468
 469         @see SetNativeFontInfo(), GetNativeFontInfoUserDesc()
 470     */
 471     wxString GetNativeFontInfoDesc() const;
 472
 473     /**
 474         Returns a user-friendly string for this font object.
 475
 476         Returned string is always non-empty unless the font is invalid (in
 477         which case an assert is triggered).
 478
 479         The string does not encode all wxFont infos under all platforms;
 480         e.g. under wxMSW the font family is not present in the returned string.
 481
 482         Some examples of the formats of returned strings (which are platform-dependent)
 483         are in SetNativeFontInfoUserDesc().
 484
 485         @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()
 486     */
 487     wxString GetNativeFontInfoUserDesc() const;
 488
 489     /**
 490         Gets the point size.
 491
 492         @see SetPointSize()
 493     */
 494     virtual int GetPointSize() const;
 495
 496     /**
 497         Gets the pixel size.
 498
 499         Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
 500         a wxSize object with a null width value, you'll get a null width in
 501         the returned object.
 502
 503         @see SetPixelSize()
 504     */
 505     virtual wxSize GetPixelSize() const;
 506
 507     /**
 508         Gets the font style. See ::wxFontStyle for a list of valid styles.
 509
 510         @see SetStyle()
 511     */
 512     virtual wxFontStyle GetStyle() const;
 513
 514     /**
 515         Returns @true if the font is underlined, @false otherwise.
 516
 517         @see SetUnderlined()
 518     */
 519     virtual bool GetUnderlined() const;
 520
 521     /**
 522         Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
 523
 524         @see SetWeight()
 525     */
 526     virtual wxFontWeight GetWeight() const;
 527
 528     /**
 529         Returns @true if the font is a fixed width (or monospaced) font,
 530         @false if it is a proportional one or font is invalid.
 531
 532         Note that this function under some platforms is different than just testing
 533         for the font family being equal to @c wxFONTFAMILY_TELETYPE because native
 534         platform-specific functions are used for the check (resulting in a more
 535         accurate return value).
 536     */
 537     virtual bool IsFixedWidth() const;
 538
 539     /**
 540         Returns @true if this object is a valid font, @false otherwise.
 541     */
 542     virtual bool IsOk() const;
 543
 544     //@}
 545
 546
 547     /**
 548         @name Similar fonts creation
 549
 550         The functions in this section either modify the font in place or create
 551         a new font similar to the given one but with its weight, style or size
 552         changed.
 553      */
 554     //@{
 555
 556     /**
 557         Returns a bold version of this font.
 558
 559         @see MakeBold()
 560
 561         @since 2.9.1
 562      */
 563     wxFont Bold() const;
 564
 565     /**
 566         Returns an italic version of this font.
 567
 568         @see MakeItalic()
 569
 570         @since 2.9.1
 571      */
 572     wxFont Italic() const;
 573
 574     /**
 575         Returns a larger version of this font.
 576
 577         The font size is multiplied by @c 1.2, the factor of @c 1.2 being
 578         inspired by the W3C CSS specification.
 579
 580         @see MakeLarger(), Smaller(), Scaled()
 581
 582         @since 2.9.1
 583      */
 584     wxFont Larger() const;
 585
 586     /**
 587         Returns a smaller version of this font.
 588
 589         The font size is divided by @c 1.2, the factor of @c 1.2 being
 590         inspired by the W3C CSS specification.
 591
 592         @see MakeSmaller(), Larger(), Scaled()
 593
 594         @since 2.9.1
 595      */
 596     wxFont Smaller() const;
 597
 598     /**
 599         Returns underlined version of this font.
 600
 601         @see MakeUnderlined()
 602
 603         @since 2.9.2
 604      */
 605     wxFont Underlined() const;
 606
 607     /**
 608         Changes this font to be bold.
 609
 610         @see Bold()
 611
 612         @since 2.9.1
 613      */
 614     wxFont& MakeBold();
 615
 616     /**
 617         Changes this font to be italic.
 618
 619         @see Italic()
 620
 621         @since 2.9.1
 622      */
 623     wxFont& MakeItalic();
 624
 625     /**
 626         Changes this font to be larger.
 627
 628         The font size is multiplied by @c 1.2, the factor of @c 1.2 being
 629         inspired by the W3C CSS specification.
 630
 631         @see Larger(), MakeSmaller(), Scale()
 632
 633         @since 2.9.1
 634      */
 635     wxFont& MakeLarger();
 636
 637     /**
 638         Changes this font to be smaller.
 639
 640         The font size is divided by @c 1.2, the factor of @c 1.2 being
 641         inspired by the W3C CSS specification.
 642
 643         @see Smaller(), MakeLarger(), Scale()
 644
 645         @since 2.9.1
 646      */
 647     wxFont& MakeSmaller();
 648
 649     /**
 650         Changes this font to be underlined.
 651
 652         @see Underlined()
 653
 654         @since 2.9.2
 655      */
 656     wxFont& MakeUnderlined();
 657
 658     /**
 659         Changes the size of this font.
 660
 661         The font size is multiplied by the given factor (which may be less than
 662         1 to create a smaller version of the font).
 663
 664         @see Scaled(), MakeLarger(), MakeSmaller()
 665
 666         @since 2.9.1
 667      */
 668     wxFont& Scale(float x);
 669
 670     /**
 671         Returns a scaled version of this font.
 672
 673         The font size is multiplied by the given factor (which may be less than
 674         1 to create a smaller version of the font).
 675
 676         @see Scale(), Larger(), Smaller()
 677
 678         @since 2.9.1
 679      */
 680     wxFont Scaled(float x) const;
 681
 682     //@}
 683
 684     /**
 685         @name Setters
 686
 687         These functions internally recreate the native font object with the new
 688         specified property.
 689     */
 690     //@{
 691
 692     /**
 693         Sets the encoding for this font.
 694
 695         Note that under wxGTK this function has no effect (because the underlying
 696         Pango library always uses @c wxFONTENCODING_UTF8).
 697
 698         @see GetEncoding()
 699     */
 700     virtual void SetEncoding(wxFontEncoding encoding);
 701
 702     /**
 703         Sets the facename for the font.
 704
 705         @param faceName
 706             A valid facename, which should be on the end-user's system.
 707
 708         @remarks To avoid portability problems, don't rely on a specific face,
 709                  but specify the font family instead (see ::wxFontFamily and SetFamily()).
 710
 711         @return @true if the given face name exists; if the face name doesn't exist
 712                 in the user's system then the font is invalidated (so that IsOk() will
 713                 return @false) and @false is returned.
 714
 715         @see GetFaceName(), SetFamily()
 716     */
 717     virtual bool SetFaceName(const wxString& faceName);
 718
 719     /**
 720         Sets the font family.
 721
 722         As described in ::wxFontFamily docs the given @a family value acts as a rough,
 723         basic indication of the main font properties (look, spacing).
 724
 725         Note that changing the font family results in changing the font face name.
 726
 727         @param family
 728             One of the ::wxFontFamily values.
 729
 730         @see GetFamily(), SetFaceName()
 731     */
 732     virtual void SetFamily(wxFontFamily family);
 733
 734     /**
 735         Creates the font corresponding to the given native font description string
 736         which must have been previously returned by GetNativeFontInfoDesc().
 737
 738         If the string is invalid, font is unchanged.
 739         This function is typically used for de-serializing a wxFont object
 740         previously saved in a string-form.
 741
 742         @return @true if the creation was successful.
 743
 744         @see SetNativeFontInfoUserDesc()
 745     */
 746     bool SetNativeFontInfo(const wxString& info);
 747
 748     /**
 749         Creates the font corresponding to the given native font description string and
 750         returns @true if the creation was successful.
 751
 752         Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly.
 753         Examples of accepted string formats are:
 754
 755         @beginTable
 756         @hdr3col{platform, generic syntax, example}
 757         @row3col{wxGTK2, <tt>[FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
 758         @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
 759         @endTable
 760
 761         @todo add an example for wxMac
 762
 763         For more detailed information about the allowed syntaxes you can look at the
 764         documentation of the native API used for font-rendering
 765         (e.g. @c pango_font_description_from_string on GTK).
 766
 767         Note that unlike SetNativeFontInfo(), this function doesn't always restore all
 768         attributes of the wxFont object under all platforms; e.g. on wxMSW the font family
 769         is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW).
 770         If you want to serialize/deserialize a font in string form, you should use
 771         GetNativeFontInfoDesc() and SetNativeFontInfo() instead.
 772
 773         @see SetNativeFontInfo()
 774     */
 775     bool SetNativeFontInfoUserDesc(const wxString& info);
 776
 777     /**
 778         Sets the point size.
 779
 780         The <em>point size</em> is defined as 1/72 of the anglo-Saxon inch
 781         (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
 782
 783         @param pointSize
 784             Size in points.
 785
 786         @see GetPointSize()
 787     */
 788     virtual void SetPointSize(int pointSize);
 789
 790     /**
 791         Sets the pixel size.
 792
 793         The height parameter of @a pixelSize must be positive while the width
 794         parameter may also be zero (to indicate that you're not interested in the
 795         width of the characters: a suitable width will be chosen for best rendering).
 796
 797         This feature (specifying the font pixel size) is directly supported only
 798         under wxMSW and wxGTK currently; under other platforms a font with the
 799         closest size to the given one is found using binary search (this maybe slower).
 800
 801         @see GetPixelSize()
 802     */
 803     virtual void SetPixelSize(const wxSize& pixelSize);
 804
 805     /**
 806         Sets the font style.
 807
 808         @param style
 809             One of the ::wxFontStyle enumeration values.
 810
 811         @see GetStyle()
 812     */
 813     virtual void SetStyle(wxFontStyle style);
 814
 815     /**
 816         Sets the font size using a predefined symbolic size name.
 817
 818         This function allows to change font size to be (very) large or small
 819         compared to the standard font size.
 820
 821         @see SetSymbolicSizeRelativeTo().
 822
 823         @since 2.9.2
 824      */
 825     void SetSymbolicSize(wxFontSymbolicSize size);
 826
 827     /**
 828         Sets the font size compared to the base font size.
 829
 830         This is the same as SetSymbolicSize() except that it uses the given
 831         font size as the normal font size instead of the standard font size.
 832
 833         @since 2.9.2
 834      */
 835     void SetSymbolicSizeRelativeTo(wxFontSymbolicSize size, int base);
 836
 837     /**
 838         Sets underlining.
 839
 840         @param underlined
 841             @true to underline, @false otherwise.
 842
 843         @see GetUnderlined()
 844     */
 845     virtual void SetUnderlined(bool underlined);
 846
 847     /**
 848         Sets the font weight.
 849
 850         @param weight
 851             One of the ::wxFontWeight values.
 852
 853         @see GetWeight()
 854     */
 855     virtual void SetWeight(wxFontWeight weight);
 856
 857     //@}
 858
 859
 860     /**
 861         Inequality operator.
 862
 863         See @ref overview_refcount_equality "reference-counted object comparison" for
 864         more info.
 865     */
 866     bool operator!=(const wxFont& font) const;
 867
 868     /**
 869         Equality operator.
 870
 871         See @ref overview_refcount_equality "reference-counted object comparison" for
 872         more info.
 873     */
 874     bool operator==(const wxFont& font) const;
 875
 876     /**
 877         Assignment operator, using @ref overview_refcount "reference counting".
 878     */
 879     wxFont& operator =(const wxFont& font);
 880
 881
 882     // statics
 883
 884     /**
 885         Returns the current application's default encoding.
 886
 887         @see @ref overview_fontencoding, SetDefaultEncoding()
 888     */
 889     static wxFontEncoding GetDefaultEncoding();
 890
 891     /**
 892         Sets the default font encoding.
 893
 894         @see @ref overview_fontencoding, GetDefaultEncoding()
 895     */
 896     static void SetDefaultEncoding(wxFontEncoding encoding);
 897
 898     //@{
 899     /**
 900         This function takes the same parameters as the relative
 901         @ref wxFont::wxFont "wxFont constructor" and returns a new font
 902         object allocated on the heap.
 903     */
 904     static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
 905                        wxFontWeight weight,
 906                        bool underline = false,
 907                        const wxString& faceName = wxEmptyString,
 908                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 909     static wxFont* New(int pointSize, wxFontFamily family,
 910                        int flags = wxFONTFLAG_DEFAULT,
 911                        const wxString& faceName = wxEmptyString,
 912                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 913     static wxFont* New(const wxSize& pixelSize,
 914                        wxFontFamily family,
 915                        wxFontStyle style,
 916                        wxFontWeight weight,
 917                        bool underline = false,
 918                        const wxString& faceName = wxEmptyString,
 919                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 920     static wxFont* New(const wxSize& pixelSize,
 921                        wxFontFamily family,
 922                        int flags = wxFONTFLAG_DEFAULT,
 923                        const wxString& faceName = wxEmptyString,
 924                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 925     //@}
 926 };
 927
 928
 929 /**
 930     An empty wxFont.
 931 */
 932 wxFont wxNullFont;
 933
 934 /**
 935     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
 936
 937     @see wxSystemSettings
 938 */
 939 wxFont wxNORMAL_FONT;
 940
 941 /**
 942     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
 943     ::wxNORMAL_FONT.
 944 */
 945 wxFont wxSMALL_FONT;
 946
 947 /**
 948     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
 949     of the same size of ::wxNORMAL_FONT.
 950 */
 951 wxFont wxITALIC_FONT;
 952
 953 /**
 954     A font identic to ::wxNORMAL_FONT except for the family used which is
 955     @c wxFONTFAMILY_SWISS.
 956 */
 957 wxFont wxSWISS_FONT;
 958
 959
 960 /**
 961     @class wxFontList
 962
 963     A font list is a list containing all fonts which have been created.
 964     There is only one instance of this class: ::wxTheFontList.
 965
 966     Use this object to search for a previously created font of the desired type
 967     and create it if not already found.
 968
 969     In some windowing systems, the font may be a scarce resource, so it is best to
 970     reuse old resources if possible.  When an application finishes, all fonts will
 971     be deleted and their resources freed, eliminating the possibility of 'memory
 972     leaks'.
 973
 974     @library{wxcore}
 975     @category{gdi}
 976
 977     @see wxFont
 978 */
 979 class wxFontList : public wxList
 980 {
 981 public:
 982     /**
 983         Constructor. The application should not construct its own font list:
 984         use the object pointer ::wxTheFontList.
 985     */
 986     wxFontList();
 987
 988     /**
 989         Finds a font of the given specification, or creates one and adds it to the
 990         list. See the @ref wxFont "wxFont constructor" for details of the arguments.
 991     */
 992     wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
 993                              wxFontWeight weight, bool underline = false,
 994                              const wxString& facename = wxEmptyString,
 995                              wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 996 };
 997
 998
 999 /**
1000     The global wxFontList instance.
1001 */
1002 wxFontList* wxTheFontList;
1003
1004
1005 // ============================================================================
1006 // Global functions/macros
1007 // ============================================================================
1008
1009 /** @addtogroup group_funcmacro_misc */
1010 //@{
1011
1012 /**
1013     Converts string to a wxFont best represented by the given string. Returns
1014     @true on success.
1015
1016     @see wxToString(const wxFont&)
1017
1018     @header{wx/font.h}
1019 */
1020 bool wxFromString(const wxString& string, wxFont* font);
1021
1022 /**
1023     Converts the given wxFont into a string.
1024
1025     @see wxFromString(const wxString&, wxFont*)
1026
1027     @header{wx/font.h}
1028 */
1029 wxString wxToString(const wxFont& font);
1030
1031 //@}
1032