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 and size in points.
 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 and size in pixels.
 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         Creates a font object using font flags.
 399
 400         This constructor is similar to the constructors above except it
 401         specifies the font styles such as underlined, italic, bold, ... in a
 402         single @a flags argument instead of using separate arguments for them.
 403         This parameter can be a combination of ::wxFontFlag enum elements.
 404         The meaning of the remaining arguments is the same as in the other
 405         constructors, please see their documentation for details.
 406
 407         @since 2.9.4
 408      */
 409     wxFont(int pointSize, wxFontFamily family, int flags,
 410            const wxString& faceName = wxEmptyString,
 411            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 412
 413     /**
 414         Constructor from font description string.
 415
 416         This constructor uses SetNativeFontInfo() to initialize the font.
 417         If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
 418         will return @false.
 419      */
 420     wxFont(const wxString& nativeInfoString);
 421
 422     /**
 423        Construct font from a native font info structure.
 424     */
 425     wxFont(const wxNativeFontInfo& nativeInfo);
 426
 427     /**
 428         Destructor.
 429
 430         See @ref overview_refcount_destruct "reference-counted object destruction"
 431         for more info.
 432
 433         @remarks Although all remaining fonts are deleted when the application
 434                  exits, the application should try to clean up all fonts
 435                  itself. This is because wxWidgets cannot know if a
 436                  pointer to the font object is stored in an application
 437                  data structure, and there is a risk of double deletion.
 438     */
 439     virtual ~wxFont();
 440
 441
 442     /**
 443         @name Getters
 444     */
 445     //@{
 446
 447     /**
 448         Returns the encoding of this font.
 449
 450         Note that under wxGTK the returned value is always @c wxFONTENCODING_UTF8.
 451
 452         @see SetEncoding()
 453     */
 454     virtual wxFontEncoding GetEncoding() const;
 455
 456     /**
 457         Returns the face name associated with the font, or the empty string if
 458         there is no face information.
 459
 460         @see SetFaceName()
 461     */
 462     virtual wxString GetFaceName() const;
 463
 464     /**
 465         Gets the font family if possible.
 466
 467         As described in ::wxFontFamily docs the returned value acts as a rough,
 468         basic classification of the main font properties (look, spacing).
 469
 470         If the current font face name is not recognized by wxFont or by the
 471         underlying system, @c wxFONTFAMILY_DEFAULT is returned.
 472
 473         Note that currently this function is not very precise and so not
 474         particularly useful. Font families mostly make sense only for font
 475         creation, see SetFamily().
 476
 477         @see SetFamily()
 478     */
 479     virtual wxFontFamily GetFamily() const;
 480
 481     /**
 482         Returns the platform-dependent string completely describing this font.
 483
 484         Returned string is always non-empty unless the font is invalid (in
 485         which case an assert is triggered).
 486
 487         Note that the returned string is not meant to be shown or edited by the user: a
 488         typical use of this function is for serializing in string-form a wxFont object.
 489
 490         @see SetNativeFontInfo(), GetNativeFontInfoUserDesc()
 491     */
 492     wxString GetNativeFontInfoDesc() const;
 493
 494     /**
 495         Returns a user-friendly string for this font object.
 496
 497         Returned string is always non-empty unless the font is invalid (in
 498         which case an assert is triggered).
 499
 500         The string does not encode all wxFont infos under all platforms;
 501         e.g. under wxMSW the font family is not present in the returned string.
 502
 503         Some examples of the formats of returned strings (which are platform-dependent)
 504         are in SetNativeFontInfoUserDesc().
 505
 506         @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()
 507     */
 508     wxString GetNativeFontInfoUserDesc() const;
 509
 510     const wxNativeFontInfo *GetNativeFontInfo() const;
 511
 512     /**
 513         Gets the point size.
 514
 515         @see SetPointSize()
 516     */
 517     virtual int GetPointSize() const;
 518
 519     /**
 520         Gets the pixel size.
 521
 522         Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
 523         a wxSize object with a null width value, you'll get a null width in
 524         the returned object.
 525
 526         @see SetPixelSize()
 527     */
 528     virtual wxSize GetPixelSize() const;
 529
 530     /**
 531         Gets the font style. See ::wxFontStyle for a list of valid styles.
 532
 533         @see SetStyle()
 534     */
 535     virtual wxFontStyle GetStyle() const;
 536
 537     /**
 538         Returns @true if the font is underlined, @false otherwise.
 539
 540         @see SetUnderlined()
 541     */
 542     virtual bool GetUnderlined() const;
 543
 544     /**
 545         Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
 546
 547         @see SetWeight()
 548     */
 549     virtual wxFontWeight GetWeight() const;
 550
 551     /**
 552         Returns @true if the font is a fixed width (or monospaced) font,
 553         @false if it is a proportional one or font is invalid.
 554
 555         Note that this function under some platforms is different than just testing
 556         for the font family being equal to @c wxFONTFAMILY_TELETYPE because native
 557         platform-specific functions are used for the check (resulting in a more
 558         accurate return value).
 559     */
 560     virtual bool IsFixedWidth() const;
 561
 562     /**
 563         Returns @true if this object is a valid font, @false otherwise.
 564     */
 565     virtual bool IsOk() const;
 566
 567     //@}
 568
 569
 570     /**
 571         @name Similar fonts creation
 572
 573         The functions in this section either modify the font in place or create
 574         a new font similar to the given one but with its weight, style or size
 575         changed.
 576      */
 577     //@{
 578
 579     /**
 580         Returns a bold version of this font.
 581
 582         @see MakeBold()
 583
 584         @since 2.9.1
 585      */
 586     wxFont Bold() const;
 587
 588     /**
 589         Returns an italic version of this font.
 590
 591         @see MakeItalic()
 592
 593         @since 2.9.1
 594      */
 595     wxFont Italic() const;
 596
 597     /**
 598         Returns a larger version of this font.
 599
 600         The font size is multiplied by @c 1.2, the factor of @c 1.2 being
 601         inspired by the W3C CSS specification.
 602
 603         @see MakeLarger(), Smaller(), Scaled()
 604
 605         @since 2.9.1
 606      */
 607     wxFont Larger() const;
 608
 609     /**
 610         Returns a smaller version of this font.
 611
 612         The font size is divided by @c 1.2, the factor of @c 1.2 being
 613         inspired by the W3C CSS specification.
 614
 615         @see MakeSmaller(), Larger(), Scaled()
 616
 617         @since 2.9.1
 618      */
 619     wxFont Smaller() const;
 620
 621     /**
 622         Returns underlined version of this font.
 623
 624         @see MakeUnderlined()
 625
 626         @since 2.9.2
 627      */
 628     wxFont Underlined() const;
 629
 630     /**
 631         Changes this font to be bold.
 632
 633         @see Bold()
 634
 635         @since 2.9.1
 636      */
 637     wxFont& MakeBold();
 638
 639     /**
 640         Changes this font to be italic.
 641
 642         @see Italic()
 643
 644         @since 2.9.1
 645      */
 646     wxFont& MakeItalic();
 647
 648     /**
 649         Changes this font to be larger.
 650
 651         The font size is multiplied by @c 1.2, the factor of @c 1.2 being
 652         inspired by the W3C CSS specification.
 653
 654         @see Larger(), MakeSmaller(), Scale()
 655
 656         @since 2.9.1
 657      */
 658     wxFont& MakeLarger();
 659
 660     /**
 661         Changes this font to be smaller.
 662
 663         The font size is divided by @c 1.2, the factor of @c 1.2 being
 664         inspired by the W3C CSS specification.
 665
 666         @see Smaller(), MakeLarger(), Scale()
 667
 668         @since 2.9.1
 669      */
 670     wxFont& MakeSmaller();
 671
 672     /**
 673         Changes this font to be underlined.
 674
 675         @see Underlined()
 676
 677         @since 2.9.2
 678      */
 679     wxFont& MakeUnderlined();
 680
 681     /**
 682         Changes the size of this font.
 683
 684         The font size is multiplied by the given factor (which may be less than
 685         1 to create a smaller version of the font).
 686
 687         @see Scaled(), MakeLarger(), MakeSmaller()
 688
 689         @since 2.9.1
 690      */
 691     wxFont& Scale(float x);
 692
 693     /**
 694         Returns a scaled version of this font.
 695
 696         The font size is multiplied by the given factor (which may be less than
 697         1 to create a smaller version of the font).
 698
 699         @see Scale(), Larger(), Smaller()
 700
 701         @since 2.9.1
 702      */
 703     wxFont Scaled(float x) const;
 704
 705     //@}
 706
 707     /**
 708         @name Setters
 709
 710         These functions internally recreate the native font object with the new
 711         specified property.
 712     */
 713     //@{
 714
 715     /**
 716         Sets the encoding for this font.
 717
 718         Note that under wxGTK this function has no effect (because the underlying
 719         Pango library always uses @c wxFONTENCODING_UTF8).
 720
 721         @see GetEncoding()
 722     */
 723     virtual void SetEncoding(wxFontEncoding encoding);
 724
 725     /**
 726         Sets the facename for the font.
 727
 728         @param faceName
 729             A valid facename, which should be on the end-user's system.
 730
 731         @remarks To avoid portability problems, don't rely on a specific face,
 732                  but specify the font family instead (see ::wxFontFamily and SetFamily()).
 733
 734         @return @true if the given face name exists; if the face name doesn't exist
 735                 in the user's system then the font is invalidated (so that IsOk() will
 736                 return @false) and @false is returned.
 737
 738         @see GetFaceName(), SetFamily()
 739     */
 740     virtual bool SetFaceName(const wxString& faceName);
 741
 742     /**
 743         Sets the font family.
 744
 745         As described in ::wxFontFamily docs the given @a family value acts as a rough,
 746         basic indication of the main font properties (look, spacing).
 747
 748         Note that changing the font family results in changing the font face name.
 749
 750         @param family
 751             One of the ::wxFontFamily values.
 752
 753         @see GetFamily(), SetFaceName()
 754     */
 755     virtual void SetFamily(wxFontFamily family);
 756
 757     /**
 758         Creates the font corresponding to the given native font description string
 759         which must have been previously returned by GetNativeFontInfoDesc().
 760
 761         If the string is invalid, font is unchanged.
 762         This function is typically used for de-serializing a wxFont object
 763         previously saved in a string-form.
 764
 765         @return @true if the creation was successful.
 766
 767         @see SetNativeFontInfoUserDesc()
 768     */
 769     bool SetNativeFontInfo(const wxString& info);
 770
 771     /**
 772         Creates the font corresponding to the given native font description string and
 773         returns @true if the creation was successful.
 774
 775         Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly.
 776         Examples of accepted string formats are:
 777
 778         @beginTable
 779         @hdr3col{platform, generic syntax, example}
 780         @row3col{wxGTK2, <tt>[FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
 781         @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
 782         @endTable
 783
 784         @todo add an example for wxMac
 785
 786         For more detailed information about the allowed syntaxes you can look at the
 787         documentation of the native API used for font-rendering
 788         (e.g. @c pango_font_description_from_string on GTK).
 789
 790         Note that unlike SetNativeFontInfo(), this function doesn't always restore all
 791         attributes of the wxFont object under all platforms; e.g. on wxMSW the font family
 792         is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW).
 793         If you want to serialize/deserialize a font in string form, you should use
 794         GetNativeFontInfoDesc() and SetNativeFontInfo() instead.
 795
 796         @see SetNativeFontInfo()
 797     */
 798     bool SetNativeFontInfoUserDesc(const wxString& info);
 799
 800     void SetNativeFontInfo(const wxNativeFontInfo& info);
 801
 802     /**
 803         Sets the point size.
 804
 805         The <em>point size</em> is defined as 1/72 of the anglo-Saxon inch
 806         (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
 807
 808         @param pointSize
 809             Size in points.
 810
 811         @see GetPointSize()
 812     */
 813     virtual void SetPointSize(int pointSize);
 814
 815     /**
 816         Sets the pixel size.
 817
 818         The height parameter of @a pixelSize must be positive while the width
 819         parameter may also be zero (to indicate that you're not interested in the
 820         width of the characters: a suitable width will be chosen for best rendering).
 821
 822         This feature (specifying the font pixel size) is directly supported only
 823         under wxMSW and wxGTK currently; under other platforms a font with the
 824         closest size to the given one is found using binary search (this maybe slower).
 825
 826         @see GetPixelSize()
 827     */
 828     virtual void SetPixelSize(const wxSize& pixelSize);
 829
 830     /**
 831         Sets the font style.
 832
 833         @param style
 834             One of the ::wxFontStyle enumeration values.
 835
 836         @see GetStyle()
 837     */
 838     virtual void SetStyle(wxFontStyle style);
 839
 840     /**
 841         Sets the font size using a predefined symbolic size name.
 842
 843         This function allows to change font size to be (very) large or small
 844         compared to the standard font size.
 845
 846         @see SetSymbolicSizeRelativeTo().
 847
 848         @since 2.9.2
 849      */
 850     void SetSymbolicSize(wxFontSymbolicSize size);
 851
 852     /**
 853         Sets the font size compared to the base font size.
 854
 855         This is the same as SetSymbolicSize() except that it uses the given
 856         font size as the normal font size instead of the standard font size.
 857
 858         @since 2.9.2
 859      */
 860     void SetSymbolicSizeRelativeTo(wxFontSymbolicSize size, int base);
 861
 862     /**
 863         Sets underlining.
 864
 865         @param underlined
 866             @true to underline, @false otherwise.
 867
 868         @see GetUnderlined()
 869     */
 870     virtual void SetUnderlined(bool underlined);
 871
 872     /**
 873         Sets the font weight.
 874
 875         @param weight
 876             One of the ::wxFontWeight values.
 877
 878         @see GetWeight()
 879     */
 880     virtual void SetWeight(wxFontWeight weight);
 881
 882     //@}
 883
 884
 885     /**
 886         Inequality operator.
 887
 888         See @ref overview_refcount_equality "reference-counted object comparison" for
 889         more info.
 890     */
 891     bool operator!=(const wxFont& font) const;
 892
 893     /**
 894         Equality operator.
 895
 896         See @ref overview_refcount_equality "reference-counted object comparison" for
 897         more info.
 898     */
 899     bool operator==(const wxFont& font) const;
 900
 901     /**
 902         Assignment operator, using @ref overview_refcount "reference counting".
 903     */
 904     wxFont& operator =(const wxFont& font);
 905
 906
 907     // statics
 908
 909     /**
 910         Returns the current application's default encoding.
 911
 912         @see @ref overview_fontencoding, SetDefaultEncoding()
 913     */
 914     static wxFontEncoding GetDefaultEncoding();
 915
 916     /**
 917         Sets the default font encoding.
 918
 919         @see @ref overview_fontencoding, GetDefaultEncoding()
 920     */
 921     static void SetDefaultEncoding(wxFontEncoding encoding);
 922
 923     //@{
 924     /**
 925         This function takes the same parameters as the relative
 926         @ref wxFont::wxFont "wxFont constructor" and returns a new font
 927         object allocated on the heap.
 928     */
 929     static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
 930                        wxFontWeight weight,
 931                        bool underline = false,
 932                        const wxString& faceName = wxEmptyString,
 933                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 934     static wxFont* New(int pointSize, wxFontFamily family,
 935                        int flags = wxFONTFLAG_DEFAULT,
 936                        const wxString& faceName = wxEmptyString,
 937                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 938     static wxFont* New(const wxSize& pixelSize,
 939                        wxFontFamily family,
 940                        wxFontStyle style,
 941                        wxFontWeight weight,
 942                        bool underline = false,
 943                        const wxString& faceName = wxEmptyString,
 944                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 945     static wxFont* New(const wxSize& pixelSize,
 946                        wxFontFamily family,
 947                        int flags = wxFONTFLAG_DEFAULT,
 948                        const wxString& faceName = wxEmptyString,
 949                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 950
 951
 952     static wxFont *New(const wxNativeFontInfo& nativeInfo);
 953     static wxFont *New(const wxString& nativeInfoString);
 954
 955     //@}
 956 };
 957
 958
 959 /**
 960     An empty wxFont.
 961 */
 962 wxFont wxNullFont;
 963
 964 /**
 965     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
 966
 967     @see wxSystemSettings
 968 */
 969 wxFont wxNORMAL_FONT;
 970
 971 /**
 972     A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
 973     ::wxNORMAL_FONT.
 974 */
 975 wxFont wxSMALL_FONT;
 976
 977 /**
 978     A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
 979     of the same size of ::wxNORMAL_FONT.
 980 */
 981 wxFont wxITALIC_FONT;
 982
 983 /**
 984     A font identic to ::wxNORMAL_FONT except for the family used which is
 985     @c wxFONTFAMILY_SWISS.
 986 */
 987 wxFont wxSWISS_FONT;
 988
 989
 990 /**
 991     @class wxFontList
 992
 993     A font list is a list containing all fonts which have been created.
 994     There is only one instance of this class: ::wxTheFontList.
 995
 996     Use this object to search for a previously created font of the desired type
 997     and create it if not already found.
 998
 999     In some windowing systems, the font may be a scarce resource, so it is best to
1000     reuse old resources if possible.  When an application finishes, all fonts will
1001     be deleted and their resources freed, eliminating the possibility of 'memory
1002     leaks'.
1003
1004     @library{wxcore}
1005     @category{gdi}
1006
1007     @see wxFont
1008 */
1009 class wxFontList : public wxList
1010 {
1011 public:
1012     /**
1013         Constructor. The application should not construct its own font list:
1014         use the object pointer ::wxTheFontList.
1015     */
1016     wxFontList();
1017
1018     /**
1019         Finds a font of the given specification, or creates one and adds it to the
1020         list. See the @ref wxFont "wxFont constructor" for details of the arguments.
1021     */
1022     wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
1023                              wxFontWeight weight, bool underline = false,
1024                              const wxString& facename = wxEmptyString,
1025                              wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
1026 };
1027
1028
1029 /**
1030     The global wxFontList instance.
1031 */
1032 wxFontList* wxTheFontList;
1033
1034
1035 // ============================================================================
1036 // Global functions/macros
1037 // ============================================================================
1038
1039 /** @addtogroup group_funcmacro_misc */
1040 //@{
1041
1042 /**
1043     Converts string to a wxFont best represented by the given string. Returns
1044     @true on success.
1045
1046     @see wxToString(const wxFont&)
1047
1048     @header{wx/font.h}
1049 */
1050 bool wxFromString(const wxString& string, wxFont* font);
1051
1052 /**
1053     Converts the given wxFont into a string.
1054
1055     @see wxFromString(const wxString&, wxFont*)
1056
1057     @header{wx/font.h}
1058 */
1059 wxString wxToString(const wxFont& font);
1060
1061 //@}
1062