interface/font.h

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