interface/font.h

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