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