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