interface/wx/font.h

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