interface/wx/font.h

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