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