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