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>[underlined] [strikethrough] [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 under GTK, although notice
 829         that it doesn't support the "underlined" and "strikethrough" attributes
 830         and so those are handled by wxWidgets itself).
 831
 832         Note that unlike SetNativeFontInfo(), this function doesn't always restore all
 833         attributes of the wxFont object under all platforms; e.g. on wxMSW the font family
 834         is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW).
 835         If you want to serialize/deserialize a font in string form, you should use
 836         GetNativeFontInfoDesc() and SetNativeFontInfo() instead.
 837
 838         @see SetNativeFontInfo()
 839     */
 840     bool SetNativeFontInfoUserDesc(const wxString& info);
 841
 842     void SetNativeFontInfo(const wxNativeFontInfo& info);
 843
 844     /**
 845         Sets the point size.
 846
 847         The <em>point size</em> is defined as 1/72 of the anglo-Saxon inch
 848         (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
 849
 850         @param pointSize
 851             Size in points.
 852
 853         @see GetPointSize()
 854     */
 855     virtual void SetPointSize(int pointSize);
 856
 857     /**
 858         Sets the pixel size.
 859
 860         The height parameter of @a pixelSize must be positive while the width
 861         parameter may also be zero (to indicate that you're not interested in the
 862         width of the characters: a suitable width will be chosen for best rendering).
 863
 864         This feature (specifying the font pixel size) is directly supported only
 865         under wxMSW and wxGTK currently; under other platforms a font with the
 866         closest size to the given one is found using binary search (this maybe slower).
 867
 868         @see GetPixelSize()
 869     */
 870     virtual void SetPixelSize(const wxSize& pixelSize);
 871
 872     /**
 873         Sets the font style.
 874
 875         @param style
 876             One of the ::wxFontStyle enumeration values.
 877
 878         @see GetStyle()
 879     */
 880     virtual void SetStyle(wxFontStyle style);
 881
 882     /**
 883         Sets the font size using a predefined symbolic size name.
 884
 885         This function allows to change font size to be (very) large or small
 886         compared to the standard font size.
 887
 888         @see SetSymbolicSizeRelativeTo().
 889
 890         @since 2.9.2
 891      */
 892     void SetSymbolicSize(wxFontSymbolicSize size);
 893
 894     /**
 895         Sets the font size compared to the base font size.
 896
 897         This is the same as SetSymbolicSize() except that it uses the given
 898         font size as the normal font size instead of the standard font size.
 899
 900         @since 2.9.2
 901      */
 902     void SetSymbolicSizeRelativeTo(wxFontSymbolicSize size, int base);
 903
 904     /**
 905         Sets underlining.
 906
 907         @param underlined
 908             @true to underline, @false otherwise.
 909
 910         @see GetUnderlined()
 911     */
 912     virtual void SetUnderlined(bool underlined);
 913
 914     /**
 915         Sets strike-through attribute of the font.
 916
 917         Currently stricken-through fonts are only supported in wxMSW and wxGTK.
 918
 919         @param strikethrough
 920             @true to add strike-through style, @false to remove it.
 921
 922         @see GetStrikethrough()
 923
 924         @since 2.9.4
 925     */
 926     virtual void SetStrikethrough(bool strikethrough);
 927
 928     /**
 929         Sets the font weight.
 930
 931         @param weight
 932             One of the ::wxFontWeight values.
 933
 934         @see GetWeight()
 935     */
 936     virtual void SetWeight(wxFontWeight weight);
 937
 938     //@}
 939
 940
 941     /**
 942         Inequality operator.
 943
 944         See @ref overview_refcount_equality "reference-counted object comparison" for
 945         more info.
 946     */
 947     bool operator!=(const wxFont& font) const;
 948
 949     /**
 950         Equality operator.
 951
 952         See @ref overview_refcount_equality "reference-counted object comparison" for
 953         more info.
 954     */
 955     bool operator==(const wxFont& font) const;
 956
 957     /**
 958         Assignment operator, using @ref overview_refcount "reference counting".
 959     */
 960     wxFont& operator =(const wxFont& font);
 961
 962
 963     // statics
 964
 965     /**
 966         Returns the current application's default encoding.
 967
 968         @see @ref overview_fontencoding, SetDefaultEncoding()
 969     */
 970     static wxFontEncoding GetDefaultEncoding();
 971
 972     /**
 973         Sets the default font encoding.
 974
 975         @see @ref overview_fontencoding, GetDefaultEncoding()
 976     */
 977     static void SetDefaultEncoding(wxFontEncoding encoding);
 978
 979     //@{
 980     /**
 981         This function takes the same parameters as the relative
 982         @ref wxFont::wxFont "wxFont constructor" and returns a new font
 983         object allocated on the heap.
 984     */
 985     static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
 986                        wxFontWeight weight,
 987                        bool underline = false,
 988                        const wxString& faceName = wxEmptyString,
 989                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 990     static wxFont* New(int pointSize, wxFontFamily family,
 991                        int flags = wxFONTFLAG_DEFAULT,
 992                        const wxString& faceName = wxEmptyString,
 993                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 994     static wxFont* New(const wxSize& pixelSize,
 995                        wxFontFamily family,
 996                        wxFontStyle style,
 997                        wxFontWeight weight,
 998                        bool underline = false,
 999                        const wxString& faceName = wxEmptyString,
1000                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
1001     static wxFont* New(const wxSize& pixelSize,
1002                        wxFontFamily family,
1003                        int flags = wxFONTFLAG_DEFAULT,
1004                        const wxString& faceName = wxEmptyString,
1005                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
1006
1007
1008     static wxFont *New(const wxNativeFontInfo& nativeInfo);
1009     static wxFont *New(const wxString& nativeInfoString);
1010
1011     //@}
1012 };
1013
1014
1015 /**
1016     An empty wxFont.
1017 */
1018 wxFont wxNullFont;
1019
1020 /**
1021     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
1022
1023     @see wxSystemSettings
1024 */
1025 wxFont* wxNORMAL_FONT;
1026
1027 /**
1028     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
1029     ::wxNORMAL_FONT.
1030 */
1031 wxFont* wxSMALL_FONT;
1032
1033 /**
1034     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
1035     of the same size of ::wxNORMAL_FONT.
1036 */
1037 wxFont* wxITALIC_FONT;
1038
1039 /**
1040     A font identic to ::wxNORMAL_FONT except for the family used which is
1041     @c wxFONTFAMILY_SWISS.
1042 */
1043 wxFont* wxSWISS_FONT;
1044
1045
1046 /**
1047     @class wxFontList
1048
1049     A font list is a list containing all fonts which have been created.
1050     There is only one instance of this class: ::wxTheFontList.
1051
1052     Use this object to search for a previously created font of the desired type
1053     and create it if not already found.
1054
1055     In some windowing systems, the font may be a scarce resource, so it is best to
1056     reuse old resources if possible.  When an application finishes, all fonts will
1057     be deleted and their resources freed, eliminating the possibility of 'memory
1058     leaks'.
1059
1060     @library{wxcore}
1061     @category{gdi}
1062
1063     @see wxFont
1064 */
1065 class wxFontList
1066 {
1067 public:
1068     /**
1069         Constructor. The application should not construct its own font list:
1070         use the object pointer ::wxTheFontList.
1071     */
1072     wxFontList();
1073
1074     /**
1075         Finds a font of the given specification, or creates one and adds it to the
1076         list. See the @ref wxFont "wxFont constructor" for details of the arguments.
1077     */
1078     wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
1079                              wxFontWeight weight, bool underline = false,
1080                              const wxString& facename = wxEmptyString,
1081                              wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
1082 };
1083
1084
1085 /**
1086     The global wxFontList instance.
1087 */
1088 wxFontList* wxTheFontList;
1089
1090
1091 // ============================================================================
1092 // Global functions/macros
1093 // ============================================================================
1094
1095 /** @addtogroup group_funcmacro_misc */
1096 //@{
1097
1098 /**
1099     Converts string to a wxFont best represented by the given string. Returns
1100     @true on success.
1101
1102     @see wxToString(const wxFont&)
1103
1104     @header{wx/font.h}
1105 */
1106 bool wxFromString(const wxString& string, wxFont* font);
1107
1108 /**
1109     Converts the given wxFont into a string.
1110
1111     @see wxFromString(const wxString&, wxFont*)
1112
1113     @header{wx/font.h}
1114 */
1115 wxString wxToString(const wxFont& font);
1116
1117 //@}
1118