interface/font.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        font.h
   3 // Purpose:     documentation for wxFont class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxFont
  11     @wxheader{font.h}
  12
  13     A font is an object which determines the appearance of text. Fonts are
  14     used for drawing text to a device context, and setting the appearance of
  15     a window's text.
  16
  17     This class uses @ref overview_trefcount "reference counting and copy-on-write"
  18     internally so that assignments between two instances of this class are very
  19     cheap. You can therefore use actual objects instead of pointers without
  20     efficiency problems. If an instance of this class is changed it will create
  21     its own data internally so that other instances, which previously shared the
  22     data using the reference counting, are not affected.
  23
  24     You can retrieve the current system font settings with wxSystemSettings.
  25
  26     wxSystemSettings
  27
  28     @library{wxcore}
  29     @category{gdi}
  30
  31     @stdobjects
  32     Objects:
  33     wxNullFont
  34     Pointers:
  35     wxNORMAL_FONT
  36
  37     wxSMALL_FONT
  38
  39     wxITALIC_FONT
  40
  41     wxSWISS_FONT
  42
  43     @seealso
  44     @ref overview_wxfontoverview, wxDC::SetFont, wxDC::DrawText,
  45     wxDC::GetTextExtent, wxFontDialog, wxSystemSettings
  46 */
  47 class wxFont : public wxGDIObject
  48 {
  49 public:
  50     //@{
  51     /**
  52         Creates a font object with the specified attributes.
  53
  54         @param pointSize
  55             Size in points.
  56         @param pixelSize
  57             Size in pixels: this is directly supported only under MSW
  58             currently where this constructor can be used directly, under other
  59         platforms a
  60             font with the closest size to the given one is found using binary search and
  61             the static New method must be used.
  62         @param family
  63             Font family, a generic way of referring to fonts without specifying actual
  64         facename. One of:
  65
  66
  67
  68
  69
  70
  71
  72             wxFONTFAMILY_DEFAULT
  73
  74
  75
  76
  77             Chooses a default font.
  78
  79
  80
  81
  82
  83             wxFONTFAMILY_DECORATIVE
  84
  85
  86
  87
  88             A decorative font.
  89
  90
  91
  92
  93
  94             wxFONTFAMILY_ROMAN
  95
  96
  97
  98
  99             A formal, serif font.
 100
 101
 102
 103
 104
 105             wxFONTFAMILY_SCRIPT
 106
 107
 108
 109
 110             A handwriting font.
 111
 112
 113
 114
 115
 116             wxFONTFAMILY_SWISS
 117
 118
 119
 120
 121             A sans-serif font.
 122
 123
 124
 125
 126
 127             wxFONTFAMILY_MODERN
 128
 129
 130
 131
 132             A fixed pitch font.
 133
 134
 135
 136
 137
 138             wxFONTFAMILY_TELETYPE
 139
 140
 141
 142
 143             A teletype font.
 144         @param style
 145             One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC.
 146         @param weight
 147             Font weight, sometimes also referred to as font boldness. One of:
 148
 149
 150
 151
 152
 153
 154
 155             wxFONTWEIGHT_NORMAL
 156
 157
 158
 159
 160             Normal font.
 161
 162
 163
 164
 165
 166             wxFONTWEIGHT_LIGHT
 167
 168
 169
 170
 171             Light font.
 172
 173
 174
 175
 176
 177             wxFONTWEIGHT_BOLD
 178
 179
 180
 181
 182             Bold font.
 183         @param underline
 184             The value can be @true or @false. At present this has an effect on Windows
 185         and Motif 2.x only.
 186         @param faceName
 187             An optional string specifying the actual typeface to be used. If it is an
 188         empty string,
 189             a default typeface will be chosen based on the family.
 190         @param encoding
 191             An encoding which may be one of
 192
 193
 194
 195
 196
 197
 198
 199             wxFONTENCODING_SYSTEM
 200
 201
 202
 203
 204             Default system encoding.
 205
 206
 207
 208
 209
 210             wxFONTENCODING_DEFAULT
 211
 212
 213
 214
 215             Default application encoding: this
 216             is the encoding set by calls to
 217             SetDefaultEncoding and which may be set to,
 218             say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the
 219             default application encoding is the same as default system encoding.
 220
 221
 222
 223
 224
 225             wxFONTENCODING_ISO8859_1...15
 226
 227
 228
 229
 230             ISO8859 encodings.
 231
 232
 233
 234
 235
 236             wxFONTENCODING_KOI8
 237
 238
 239
 240
 241             The standard Russian encoding for Internet.
 242
 243
 244
 245
 246
 247             wxFONTENCODING_CP1250...1252
 248
 249
 250
 251
 252             Windows encodings similar to ISO8859 (but not identical).
 253
 254
 255
 256
 257
 258             If the specified encoding isn't available, no font is created
 259             (see also font encoding overview).
 260
 261         @remarks If the desired font does not exist, the closest match will be
 262                  chosen. Under Windows, only scalable TrueType fonts are
 263                  used.
 264     */
 265     wxFont();
 266     wxFont(const wxFont& font);
 267     wxFont(int pointSize, wxFontFamily family, int style,
 268            wxFontWeight weight,
 269            const bool underline = false,
 270            const wxString& faceName = "",
 271            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 272     wxFont(const wxSize& pixelSize, wxFontFamily family,
 273            int style, wxFontWeight weight,
 274            const bool underline = false,
 275            const wxString& faceName = "",
 276            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 277     //@}
 278
 279     /**
 280         Destructor.
 281         See @ref overview_refcountdestruct "reference-counted object destruction" for
 282         more info.
 283
 284         @remarks Although all remaining fonts are deleted when the application
 285                  exits, the application should try to clean up all fonts
 286                  itself. This is because wxWidgets cannot know if a
 287                  pointer to the font object is stored in an application
 288                  data structure, and there is a risk of double deletion.
 289     */
 290     ~wxFont();
 291
 292     /**
 293         Returns the current application's default encoding.
 294
 295         @see @ref overview_wxfontencodingoverview, SetDefaultEncoding()
 296     */
 297     static wxFontEncoding GetDefaultEncoding();
 298
 299     /**
 300         Returns the typeface name associated with the font, or the empty string if
 301         there is no
 302         typeface information.
 303
 304         @see SetFaceName()
 305     */
 306     wxString GetFaceName();
 307
 308     /**
 309         Gets the font family. See SetFamily() for a list of valid
 310         family identifiers.
 311
 312         @see SetFamily()
 313     */
 314     wxFontFamily GetFamily();
 315
 316     /**
 317         Returns the platform-dependent string completely describing this font.
 318         Returned string is always non-empty.
 319         Note that the returned string is not meant to be shown or edited by the user: a
 320         typical
 321         use of this function is for serializing in string-form a wxFont object.
 322
 323         @see SetNativeFontInfo(),GetNativeFontInfoUserDesc()
 324     */
 325     wxString GetNativeFontInfoDesc();
 326
 327     /**
 328         Returns a user-friendly string for this font object. Returned string is always
 329         non-empty.
 330         Some examples of the formats of returned strings (which are platform-dependent)
 331         are in SetNativeFontInfoUserDesc().
 332
 333         @see GetNativeFontInfoDesc()
 334     */
 335     wxString GetNativeFontInfoUserDesc();
 336
 337     /**
 338         Gets the point size.
 339
 340         @see SetPointSize()
 341     */
 342     int GetPointSize();
 343
 344     /**
 345         Gets the font style. See wxFont() for a list of valid
 346         styles.
 347
 348         @see SetStyle()
 349     */
 350     int GetStyle();
 351
 352     /**
 353         Returns @true if the font is underlined, @false otherwise.
 354
 355         @see SetUnderlined()
 356     */
 357     bool GetUnderlined();
 358
 359     /**
 360         Gets the font weight. See wxFont() for a list of valid
 361         weight identifiers.
 362
 363         @see SetWeight()
 364     */
 365     wxFontWeight GetWeight();
 366
 367     /**
 368         Returns @true if the font is a fixed width (or monospaced) font,
 369         @false if it is a proportional one or font is invalid.
 370     */
 371     bool IsFixedWidth();
 372
 373     /**
 374         Returns @true if this object is a valid font, @false otherwise.
 375     */
 376     bool IsOk();
 377
 378     //@{
 379     /**
 380         These functions take the same parameters as @ref ctor() wxFont
 381         constructor and return a new font object allocated on the heap.
 382         Using @c New() is currently the only way to directly create a font with
 383         the given size in pixels on platforms other than wxMSW.
 384     */
 385     static wxFont* New(int pointSize, wxFontFamily family, int style,
 386                        wxFontWeight weight,
 387                        const bool underline = false,
 388                        const wxString& faceName = "",
 389                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 390     static wxFont* New(int pointSize, wxFontFamily family,
 391                        int flags = wxFONTFLAG_DEFAULT,
 392                        const wxString& faceName = "",
 393                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 394     static wxFont* New(const wxSize& pixelSize,
 395                        wxFontFamily family,
 396                        int style,
 397                        wxFontWeight weight,
 398                        const bool underline = false,
 399                        const wxString& faceName = "",
 400                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 401     static wxFont* New(const wxSize& pixelSize,
 402                        wxFontFamily family,
 403                        int flags = wxFONTFLAG_DEFAULT,
 404                        const wxString& faceName = "",
 405                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 406     //@}
 407
 408     /**
 409         Sets the default font encoding.
 410
 411         @see @ref overview_wxfontencodingoverview, GetDefaultEncoding()
 412     */
 413     static void SetDefaultEncoding(wxFontEncoding encoding);
 414
 415     /**
 416         Sets the facename for the font.
 417         Returns @true if the given face name exists; @false otherwise.
 418
 419         @param faceName
 420             A valid facename, which should be on the end-user's system.
 421
 422         @remarks To avoid portability problems, don't rely on a specific face,
 423                  but specify the font family instead or as well. A
 424                  suitable font will be found on the end-user's system.
 425                  If both the family and the facename are specified,
 426                  wxWidgets will first search for the specific face, and
 427                  then for a font belonging to the same family.
 428
 429         @see GetFaceName(), SetFamily()
 430     */
 431     bool SetFaceName(const wxString& faceName);
 432
 433     /**
 434         Sets the font family.
 435
 436         @param family
 437             One of:
 438
 439
 440
 441
 442
 443
 444
 445             wxFONTFAMILY_DEFAULT
 446
 447
 448
 449
 450             Chooses a default font.
 451
 452
 453
 454
 455
 456             wxFONTFAMILY_DECORATIVE
 457
 458
 459
 460
 461             A decorative font.
 462
 463
 464
 465
 466
 467             wxFONTFAMILY_ROMAN
 468
 469
 470
 471
 472             A formal, serif font.
 473
 474
 475
 476
 477
 478             wxFONTFAMILY_SCRIPT
 479
 480
 481
 482
 483             A handwriting font.
 484
 485
 486
 487
 488
 489             wxFONTFAMILY_SWISS
 490
 491
 492
 493
 494             A sans-serif font.
 495
 496
 497
 498
 499
 500             wxFONTFAMILY_MODERN
 501
 502
 503
 504
 505             A fixed pitch font.
 506
 507
 508
 509
 510
 511             wxFONTFAMILY_TELETYPE
 512
 513
 514
 515
 516             A teletype font.
 517
 518         @see GetFamily(), SetFaceName()
 519     */
 520     void SetFamily(wxFontFamily family);
 521
 522     /**
 523         Creates the font corresponding to the given native font description string and
 524         returns @true if
 525         the creation was successful.
 526         which must have been previously returned by
 527         GetNativeFontInfoDesc(). If the string is
 528         invalid, font is unchanged. This function is typically used for de-serializing
 529         a wxFont
 530         object previously saved in a string-form.
 531
 532         @see SetNativeFontInfoUserDesc()
 533     */
 534     bool SetNativeFontInfo(const wxString& info);
 535
 536     /**
 537         Creates the font corresponding to the given native font description string and
 538         returns @true if
 539         the creation was successful.
 540         Unlike SetNativeFontInfo(), this function accepts
 541         strings which are user-friendly.
 542         Examples of accepted string formats are:
 543
 544         Generic syntax
 545
 546         Example
 547
 548         on @b wxGTK2: @c [FACE-NAME] [bold] [oblique|italic] [POINTSIZE]
 549
 550         Monospace bold 10
 551
 552         on @b wxMSW: @c [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]
 553
 554         Tahoma 10 WINDOWS-1252
 555
 556         on @b wxMac: FIXME
 557
 558         FIXME
 559
 560         For more detailed information about the allowed syntaxes you can look at the
 561         documentation of the native API used for font-rendering (e.g. pango_font_description_from_string).
 562
 563         @see SetNativeFontInfo()
 564     */
 565     bool SetNativeFontInfoUserDesc(const wxString& info);
 566
 567     /**
 568         Sets the point size.
 569
 570         @param pointSize
 571             Size in points.
 572
 573         @see GetPointSize()
 574     */
 575     void SetPointSize(int pointSize);
 576
 577     /**
 578         Sets the font style.
 579
 580         @param style
 581             One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC.
 582
 583         @see GetStyle()
 584     */
 585     void SetStyle(int style);
 586
 587     /**
 588         Sets underlining.
 589
 590         @param underlining
 591             @true to underline, @false otherwise.
 592
 593         @see GetUnderlined()
 594     */
 595     void SetUnderlined(const bool underlined);
 596
 597     /**
 598         Sets the font weight.
 599
 600         @param weight
 601             One of:
 602
 603
 604
 605
 606
 607
 608
 609             wxFONTWEIGHT_NORMAL
 610
 611
 612
 613
 614             Normal font.
 615
 616
 617
 618
 619
 620             wxFONTWEIGHT_LIGHT
 621
 622
 623
 624
 625             Light font.
 626
 627
 628
 629
 630
 631             wxFONTWEIGHT_BOLD
 632
 633
 634
 635
 636             Bold font.
 637
 638         @see GetWeight()
 639     */
 640     void SetWeight(wxFontWeight weight);
 641
 642     /**
 643         Inequality operator.
 644         See @ref overview_refcountequality "reference-counted object comparison" for
 645         more info.
 646     */
 647     bool operator !=(const wxFont& font);
 648
 649     /**
 650         Assignment operator, using @ref overview_trefcount "reference counting".
 651     */
 652     wxFont operator =(const wxFont& font);
 653
 654     /**
 655         Equality operator.
 656         See @ref overview_refcountequality "reference-counted object comparison" for
 657         more info.
 658     */
 659     bool operator ==(const wxFont& font);
 660 };