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