interface/wx/font.h

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