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