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