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     The font flag bits for the new font ctor accepting one combined flags word.
  75 */
  76 enum wxFontFlag
  77 {
  78     /// no special flags: font with default weight/slant/anti-aliasing
  79     wxFONTFLAG_DEFAULT          = 0,
  80
  81     /// slant flags (default: no slant)
  82     wxFONTFLAG_ITALIC           = 1 << 0,
  83     wxFONTFLAG_SLANT            = 1 << 1,
  84
  85     /// weight flags (default: medium)
  86     wxFONTFLAG_LIGHT            = 1 << 2,
  87     wxFONTFLAG_BOLD             = 1 << 3,
  88
  89     /// anti-aliasing flag: force on or off (default: the current system default)
  90     wxFONTFLAG_ANTIALIASED      = 1 << 4,
  91     wxFONTFLAG_NOT_ANTIALIASED  = 1 << 5,
  92
  93     /// underlined/strikethrough flags (default: no lines)
  94     wxFONTFLAG_UNDERLINED       = 1 << 6,
  95     wxFONTFLAG_STRIKETHROUGH    = 1 << 7,
  96
  97     /// the mask of all currently used flags
  98     wxFONTFLAG_MASK = wxFONTFLAG_ITALIC             |
  99                       wxFONTFLAG_SLANT              |
 100                       wxFONTFLAG_LIGHT              |
 101                       wxFONTFLAG_BOLD               |
 102                       wxFONTFLAG_ANTIALIASED        |
 103                       wxFONTFLAG_NOT_ANTIALIASED    |
 104                       wxFONTFLAG_UNDERLINED         |
 105                       wxFONTFLAG_STRIKETHROUGH
 106 };
 107
 108
 109
 110 /**
 111     Font encodings.
 112
 113     See wxFont::SetEncoding().
 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     wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese
 239     wxFONTENCODING_BIG5 = wxFONTENCODING_CP950,   //!< Traditional Chinese
 240     wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932, //!< Shift JIS
 241     wxFONTENCODING_EUC_KR = wxFONTENCODING_CP949 //!< Korean
 242 };
 243
 244
 245
 246 /**
 247     @class wxFont
 248
 249     A font is an object which determines the appearance of text.
 250     Fonts are used for drawing text to a device context, and setting the appearance
 251     of a window's text.
 252
 253     This class uses @ref overview_refcount "reference counting and copy-on-write"
 254     internally so that assignments between two instances of this class are very
 255     cheap. You can therefore use actual objects instead of pointers without
 256     efficiency problems. If an instance of this class is changed it will create
 257     its own data internally so that other instances, which previously shared the
 258     data using the reference counting, are not affected.
 259
 260     You can retrieve the current system font settings with wxSystemSettings.
 261
 262     @library{wxcore}
 263     @category{gdi}
 264
 265     @stdobjects
 266     ::wxNullFont, ::wxNORMAL_FONT, ::wxSMALL_FONT, ::wxITALIC_FONT, ::wxSWISS_FONT
 267
 268     @see @ref overview_font, wxDC::SetFont, wxDC::DrawText,
 269          wxDC::GetTextExtent, wxFontDialog, wxSystemSettings
 270 */
 271 class wxFont : public wxGDIObject
 272 {
 273 public:
 274     /**
 275         Default ctor.
 276     */
 277     wxFont();
 278
 279     /**
 280         Copy constructor, uses @ref overview_refcount "reference counting".
 281     */
 282     wxFont(const wxFont& font);
 283
 284     /**
 285         Creates a font object with the specified attributes.
 286
 287         @param pointSize
 288             Size in points. See SetPointSize() for more info.
 289         @param family
 290             The font family: a generic portable way of referring to fonts without specifying a
 291             facename. This parameter must be one of the ::wxFontFamily enumeration values.
 292             If the @a faceName argument is provided, then it overrides the font family.
 293         @param style
 294             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
 295         @param weight
 296             Font weight, sometimes also referred to as font boldness.
 297             One of the ::wxFontWeight enumeration values.
 298         @param underline
 299             The value can be @true or @false.
 300             At present this has an effect on Windows and Motif 2.x only.
 301         @param faceName
 302             An optional string specifying the face name to be used.
 303             If it is an empty string, a default face name will be chosen based on the family.
 304         @param encoding
 305             An encoding which may be one of the enumeration values of ::wxFontEncoding.
 306             Briefly these can be summed up as:
 307             <TABLE>
 308                 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
 309                 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
 310                     Default application encoding: this is the encoding set by calls to
 311                     SetDefaultEncoding() and which may be set to, say, KOI8 to create all
 312                     fonts by default with KOI8 encoding. Initially, the default application
 313                     encoding is the same as default system encoding.</TD></TR>
 314                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 315                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 316                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 317             </TABLE>
 318             If the specified encoding isn't available, no font is created
 319             (see also @ref overview_fontencoding).
 320
 321         @remarks If the desired font does not exist, the closest match will be
 322                  chosen. Under Windows, only scalable TrueType fonts are used.
 323     */
 324     wxFont(int pointSize, wxFontFamily family, wxFontStyle style,
 325            wxFontWeight weight,
 326            bool underline = false,
 327            const wxString& faceName = wxEmptyString,
 328            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 329
 330     /**
 331         Creates a font object with the specified attributes.
 332
 333         @param pixelSize
 334             Size in pixels. See SetPixelSize() for more info.
 335         @param family
 336             The font family: a generic portable way of referring to fonts without specifying a
 337             facename. This parameter must be one of the ::wxFontFamily enumeration values.
 338             If the @a faceName argument is provided, then it overrides the font family.
 339         @param style
 340             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
 341         @param weight
 342             Font weight, sometimes also referred to as font boldness.
 343             One of the ::wxFontWeight enumeration values.
 344         @param underline
 345             The value can be @true or @false.
 346             At present this has an effect on Windows and Motif 2.x only.
 347         @param faceName
 348             An optional string specifying the face name to be used.
 349             If it is an empty string, a default face name will be chosen based on the family.
 350         @param encoding
 351             An encoding which may be one of the enumeration values of ::wxFontEncoding.
 352             Briefly these can be summed up as:
 353             <TABLE>
 354                 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
 355                 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
 356                     Default application encoding: this is the encoding set by calls to
 357                     SetDefaultEncoding() and which may be set to, say, KOI8 to create all
 358                     fonts by default with KOI8 encoding. Initially, the default application
 359                     encoding is the same as default system encoding.</TD></TR>
 360                 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
 361                 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
 362                 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
 363             </TABLE>
 364             If the specified encoding isn't available, no font is created
 365             (see also @ref overview_fontencoding).
 366
 367         @remarks If the desired font does not exist, the closest match will be
 368                  chosen. Under Windows, only scalable TrueType fonts are used.
 369     */
 370     wxFont(const wxSize& pixelSize, wxFontFamily family,
 371            wxFontStyle style, wxFontWeight weight,
 372            bool underline = false,
 373            const wxString& faceName = wxEmptyString,
 374            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 375
 376     /**
 377         Constructor from font description string.
 378
 379         This constructor uses SetNativeFontInfo() to initialize the font.
 380         If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
 381         will return @false.
 382      */
 383     wxFont(const wxString& fontdesc);
 384
 385     /**
 386         Destructor.
 387
 388         See @ref overview_refcount_destruct "reference-counted object destruction"
 389         for more info.
 390
 391         @remarks Although all remaining fonts are deleted when the application
 392                  exits, the application should try to clean up all fonts
 393                  itself. This is because wxWidgets cannot know if a
 394                  pointer to the font object is stored in an application
 395                  data structure, and there is a risk of double deletion.
 396     */
 397     virtual ~wxFont();
 398
 399
 400     /**
 401         @name Getters
 402     */
 403     //@{
 404
 405     /**
 406         Returns the encoding of this font.
 407
 408         Note that under wxGTK the returned value is always @c wxFONTENCODING_UTF8.
 409
 410         @see SetEncoding()
 411     */
 412     virtual wxFontEncoding GetEncoding() const;
 413
 414     /**
 415         Returns the face name associated with the font, or the empty string if
 416         there is no face information.
 417
 418         @see SetFaceName()
 419     */
 420     virtual wxString GetFaceName() const;
 421
 422     /**
 423         Gets the font family if possible.
 424
 425         As described in ::wxFontFamily docs the returned value acts as a rough,
 426         basic classification of the main font properties (look, spacing).
 427
 428         If the current font face name is not recognized by wxFont or by the
 429         underlying system, @c wxFONTFAMILY_DEFAULT is returned.
 430
 431         Note that currently this function is not very precise and so not
 432         particularly useful. Font families mostly make sense only for font
 433         creation, see SetFamily().
 434
 435         @see SetFamily()
 436     */
 437     virtual wxFontFamily GetFamily() const;
 438
 439     /**
 440         Returns the platform-dependent string completely describing this font.
 441
 442         Returned string is always non-empty unless the font is invalid (in
 443         which case an assert is triggered).
 444
 445         Note that the returned string is not meant to be shown or edited by the user: a
 446         typical use of this function is for serializing in string-form a wxFont object.
 447
 448         @see SetNativeFontInfo(), GetNativeFontInfoUserDesc()
 449     */
 450     wxString GetNativeFontInfoDesc() const;
 451
 452     /**
 453         Returns a user-friendly string for this font object.
 454
 455         Returned string is always non-empty unless the font is invalid (in
 456         which case an assert is triggered).
 457
 458         The string does not encode all wxFont infos under all platforms;
 459         e.g. under wxMSW the font family is not present in the returned string.
 460
 461         Some examples of the formats of returned strings (which are platform-dependent)
 462         are in SetNativeFontInfoUserDesc().
 463
 464         @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()
 465     */
 466     wxString GetNativeFontInfoUserDesc() const;
 467
 468     /**
 469         Gets the point size.
 470
 471         @see SetPointSize()
 472     */
 473     virtual int GetPointSize() const;
 474
 475     /**
 476         Gets the pixel size.
 477
 478         Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
 479         a wxSize object with a null width value, you'll get a null width in
 480         the returned object.
 481
 482         @see SetPixelSize()
 483     */
 484     virtual wxSize GetPixelSize() const;
 485
 486     /**
 487         Gets the font style. See ::wxFontStyle for a list of valid styles.
 488
 489         @see SetStyle()
 490     */
 491     virtual wxFontStyle GetStyle() const;
 492
 493     /**
 494         Returns @true if the font is underlined, @false otherwise.
 495
 496         @see SetUnderlined()
 497     */
 498     virtual bool GetUnderlined() const;
 499
 500     /**
 501         Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
 502
 503         @see SetWeight()
 504     */
 505     virtual wxFontWeight GetWeight() const;
 506
 507     /**
 508         Returns @true if the font is a fixed width (or monospaced) font,
 509         @false if it is a proportional one or font is invalid.
 510
 511         Note that this function under some platforms is different than just testing
 512         for the font family being equal to @c wxFONTFAMILY_TELETYPE because native
 513         platform-specific functions are used for the check (resulting in a more
 514         accurate return value).
 515     */
 516     virtual bool IsFixedWidth() const;
 517
 518     /**
 519         Returns @true if this object is a valid font, @false otherwise.
 520     */
 521     virtual bool IsOk() const;
 522
 523     //@}
 524
 525
 526     /**
 527         @name Similar fonts creation
 528
 529         The functions in this section either modify the font in place or create
 530         a new font similar to the given one but with its weight, style or size
 531         changed.
 532      */
 533     //@{
 534
 535     /**
 536         Returns a bold version of this font.
 537
 538         @see MakeBold()
 539
 540         @since 2.9.1
 541      */
 542     wxFont Bold() const;
 543
 544     /**
 545         Returns an italic version of this font.
 546
 547         @see MakeItalic()
 548
 549         @since 2.9.1
 550      */
 551     wxFont Italic() const;
 552
 553     /**
 554         Returns a larger version of this font.
 555
 556         The font size is multiplied by @c 1.2, the factor of @c 1.2 being
 557         inspired by the W3C CSS specification.
 558
 559         @see MakeLarger(), Smaller(), Scaled()
 560
 561         @since 2.9.1
 562      */
 563     wxFont Larger() const;
 564
 565     /**
 566         Returns a smaller version of this font.
 567
 568         The font size is divided by @c 1.2, the factor of @c 1.2 being
 569         inspired by the W3C CSS specification.
 570
 571         @see MakeSmaller(), Larger(), Scaled()
 572
 573         @since 2.9.1
 574      */
 575     wxFont Smaller() const;
 576
 577     /**
 578         Returns underlined version of this font.
 579
 580         @see MakeUnderlined()
 581
 582         @since 2.9.2
 583      */
 584     wxFont Underlined() const;
 585
 586     /**
 587         Changes this font to be bold.
 588
 589         @see Bold()
 590
 591         @since 2.9.1
 592      */
 593     wxFont& MakeBold();
 594
 595     /**
 596         Changes this font to be italic.
 597
 598         @see Italic()
 599
 600         @since 2.9.1
 601      */
 602     wxFont& MakeItalic();
 603
 604     /**
 605         Changes this font to be larger.
 606
 607         The font size is multiplied by @c 1.2, the factor of @c 1.2 being
 608         inspired by the W3C CSS specification.
 609
 610         @see Larger(), MakeSmaller(), Scale()
 611
 612         @since 2.9.1
 613      */
 614     wxFont& MakeLarger();
 615
 616     /**
 617         Changes this font to be smaller.
 618
 619         The font size is divided by @c 1.2, the factor of @c 1.2 being
 620         inspired by the W3C CSS specification.
 621
 622         @see Smaller(), MakeLarger(), Scale()
 623
 624         @since 2.9.1
 625      */
 626     wxFont& MakeSmaller();
 627
 628     /**
 629         Changes this font to be underlined.
 630
 631         @see Underlined()
 632
 633         @since 2.9.2
 634      */
 635     wxFont& MakeUnderlined();
 636
 637     /**
 638         Changes the size of this font.
 639
 640         The font size is multiplied by the given factor (which may be less than
 641         1 to create a smaller version of the font).
 642
 643         @see Scaled(), MakeLarger(), MakeSmaller()
 644
 645         @since 2.9.1
 646      */
 647     wxFont& Scale(float x);
 648
 649     /**
 650         Returns a scaled version of this font.
 651
 652         The font size is multiplied by the given factor (which may be less than
 653         1 to create a smaller version of the font).
 654
 655         @see Scale(), Larger(), Smaller()
 656
 657         @since 2.9.1
 658      */
 659     wxFont Scaled(float x) const;
 660
 661     //@}
 662
 663     /**
 664         @name Setters
 665
 666         These functions internally recreate the native font object with the new
 667         specified property.
 668     */
 669     //@{
 670
 671     /**
 672         Sets the encoding for this font.
 673
 674         Note that under wxGTK this function has no effect (because the underlying
 675         Pango library always uses @c wxFONTENCODING_UTF8).
 676
 677         @see GetEncoding()
 678     */
 679     virtual void SetEncoding(wxFontEncoding encoding);
 680
 681     /**
 682         Sets the facename for the font.
 683
 684         @param faceName
 685             A valid facename, which should be on the end-user's system.
 686
 687         @remarks To avoid portability problems, don't rely on a specific face,
 688                  but specify the font family instead (see ::wxFontFamily and SetFamily()).
 689
 690         @return @true if the given face name exists; if the face name doesn't exist
 691                 in the user's system then the font is invalidated (so that IsOk() will
 692                 return @false) and @false is returned.
 693
 694         @see GetFaceName(), SetFamily()
 695     */
 696     virtual bool SetFaceName(const wxString& faceName);
 697
 698     /**
 699         Sets the font family.
 700
 701         As described in ::wxFontFamily docs the given @a family value acts as a rough,
 702         basic indication of the main font properties (look, spacing).
 703
 704         Note that changing the font family results in changing the font face name.
 705
 706         @param family
 707             One of the ::wxFontFamily values.
 708
 709         @see GetFamily(), SetFaceName()
 710     */
 711     virtual void SetFamily(wxFontFamily family);
 712
 713     /**
 714         Creates the font corresponding to the given native font description string
 715         which must have been previously returned by GetNativeFontInfoDesc().
 716
 717         If the string is invalid, font is unchanged.
 718         This function is typically used for de-serializing a wxFont object
 719         previously saved in a string-form.
 720
 721         @return @true if the creation was successful.
 722
 723         @see SetNativeFontInfoUserDesc()
 724     */
 725     bool SetNativeFontInfo(const wxString& info);
 726
 727     /**
 728         Creates the font corresponding to the given native font description string and
 729         returns @true if the creation was successful.
 730
 731         Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly.
 732         Examples of accepted string formats are:
 733
 734         @beginTable
 735         @hdr3col{platform, generic syntax, example}
 736         @row3col{wxGTK2, <tt>[FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
 737         @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
 738         @endTable
 739
 740         @todo add an example for wxMac
 741
 742         For more detailed information about the allowed syntaxes you can look at the
 743         documentation of the native API used for font-rendering
 744         (e.g. @c pango_font_description_from_string on GTK).
 745
 746         Note that unlike SetNativeFontInfo(), this function doesn't always restore all
 747         attributes of the wxFont object under all platforms; e.g. on wxMSW the font family
 748         is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW).
 749         If you want to serialize/deserialize a font in string form, you should use
 750         GetNativeFontInfoDesc() and SetNativeFontInfo() instead.
 751
 752         @see SetNativeFontInfo()
 753     */
 754     bool SetNativeFontInfoUserDesc(const wxString& info);
 755
 756     /**
 757         Sets the point size.
 758
 759         The <em>point size</em> is defined as 1/72 of the anglo-Saxon inch
 760         (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
 761
 762         @param pointSize
 763             Size in points.
 764
 765         @see GetPointSize()
 766     */
 767     virtual void SetPointSize(int pointSize);
 768
 769     /**
 770         Sets the pixel size.
 771
 772         The height parameter of @a pixelSize must be positive while the width
 773         parameter may also be zero (to indicate that you're not interested in the
 774         width of the characters: a suitable width will be chosen for best rendering).
 775
 776         This feature (specifying the font pixel size) is directly supported only
 777         under wxMSW and wxGTK currently; under other platforms a font with the
 778         closest size to the given one is found using binary search (this maybe slower).
 779
 780         @see GetPixelSize()
 781     */
 782     virtual void SetPixelSize(const wxSize& pixelSize);
 783
 784     /**
 785         Sets the font style.
 786
 787         @param style
 788             One of the ::wxFontStyle enumeration values.
 789
 790         @see GetStyle()
 791     */
 792     virtual void SetStyle(wxFontStyle style);
 793
 794     /**
 795         Sets underlining.
 796
 797         @param underlined
 798             @true to underline, @false otherwise.
 799
 800         @see GetUnderlined()
 801     */
 802     virtual void SetUnderlined(bool underlined);
 803
 804     /**
 805         Sets the font weight.
 806
 807         @param weight
 808             One of the ::wxFontWeight values.
 809
 810         @see GetWeight()
 811     */
 812     virtual void SetWeight(wxFontWeight weight);
 813
 814     //@}
 815
 816
 817     /**
 818         Inequality operator.
 819
 820         See @ref overview_refcount_equality "reference-counted object comparison" for
 821         more info.
 822     */
 823     bool operator!=(const wxFont& font) const;
 824
 825     /**
 826         Equality operator.
 827
 828         See @ref overview_refcount_equality "reference-counted object comparison" for
 829         more info.
 830     */
 831     bool operator==(const wxFont& font) const;
 832
 833     /**
 834         Assignment operator, using @ref overview_refcount "reference counting".
 835     */
 836     wxFont& operator =(const wxFont& font);
 837
 838
 839     // statics
 840
 841     /**
 842         Returns the current application's default encoding.
 843
 844         @see @ref overview_fontencoding, SetDefaultEncoding()
 845     */
 846     static wxFontEncoding GetDefaultEncoding();
 847
 848     /**
 849         Sets the default font encoding.
 850
 851         @see @ref overview_fontencoding, GetDefaultEncoding()
 852     */
 853     static void SetDefaultEncoding(wxFontEncoding encoding);
 854
 855     //@{
 856     /**
 857         This function takes the same parameters as the relative
 858         @ref wxFont::wxFont "wxFont constructor" and returns a new font
 859         object allocated on the heap.
 860     */
 861     static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
 862                        wxFontWeight weight,
 863                        bool underline = false,
 864                        const wxString& faceName = wxEmptyString,
 865                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 866     static wxFont* New(int pointSize, wxFontFamily family,
 867                        int flags = wxFONTFLAG_DEFAULT,
 868                        const wxString& faceName = wxEmptyString,
 869                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 870     static wxFont* New(const wxSize& pixelSize,
 871                        wxFontFamily family,
 872                        wxFontStyle style,
 873                        wxFontWeight weight,
 874                        bool underline = false,
 875                        const wxString& faceName = wxEmptyString,
 876                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 877     static wxFont* New(const wxSize& pixelSize,
 878                        wxFontFamily family,
 879                        int flags = wxFONTFLAG_DEFAULT,
 880                        const wxString& faceName = wxEmptyString,
 881                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 882     //@}
 883 };
 884
 885
 886 /**
 887     An empty wxFont.
 888 */
 889 wxFont wxNullFont;
 890
 891 /**
 892     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
 893
 894     @see wxSystemSettings
 895 */
 896 wxFont wxNORMAL_FONT;
 897
 898 /**
 899     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
 900     ::wxNORMAL_FONT.
 901 */
 902 wxFont wxSMALL_FONT;
 903
 904 /**
 905     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
 906     of the same size of ::wxNORMAL_FONT.
 907 */
 908 wxFont wxITALIC_FONT;
 909
 910 /**
 911     A font identic to ::wxNORMAL_FONT except for the family used which is
 912     @c wxFONTFAMILY_SWISS.
 913 */
 914 wxFont wxSWISS_FONT;
 915
 916
 917 /**
 918     @class wxFontList
 919
 920     A font list is a list containing all fonts which have been created.
 921     There is only one instance of this class: ::wxTheFontList.
 922
 923     Use this object to search for a previously created font of the desired type
 924     and create it if not already found.
 925
 926     In some windowing systems, the font may be a scarce resource, so it is best to
 927     reuse old resources if possible.  When an application finishes, all fonts will
 928     be deleted and their resources freed, eliminating the possibility of 'memory
 929     leaks'.
 930
 931     @library{wxcore}
 932     @category{gdi}
 933
 934     @see wxFont
 935 */
 936 class wxFontList : public wxList
 937 {
 938 public:
 939     /**
 940         Constructor. The application should not construct its own font list:
 941         use the object pointer ::wxTheFontList.
 942     */
 943     wxFontList();
 944
 945     /**
 946         Finds a font of the given specification, or creates one and adds it to the
 947         list. See the @ref wxFont "wxFont constructor" for details of the arguments.
 948     */
 949     wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
 950                              wxFontWeight weight, bool underline = false,
 951                              const wxString& facename = wxEmptyString,
 952                              wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 953 };
 954
 955
 956 /**
 957     The global wxFontList instance.
 958 */
 959 wxFontList* wxTheFontList;
 960
 961
 962 // ============================================================================
 963 // Global functions/macros
 964 // ============================================================================
 965
 966 /** @addtogroup group_funcmacro_misc */
 967 //@{
 968
 969 /**
 970     Converts string to a wxFont best represented by the given string. Returns
 971     @true on success.
 972
 973     @see wxToString(const wxFont&)
 974
 975     @header{wx/font.h}
 976 */
 977 bool wxFromString(const wxString& string, wxFont* font);
 978
 979 /**
 980     Converts the given wxFont into a string.
 981
 982     @see wxFromString(const wxString&, wxFont*)
 983
 984     @header{wx/font.h}
 985 */
 986 wxString wxToString(const wxFont& font);
 987
 988 //@}
 989