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