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