docs/latex/wx/font.tex

   1 \section{\class{wxFont}}\label{wxfont}
   2
   3 A font is an object which determines the appearance of text. Fonts are
   4 used for drawing text to a device context, and setting the appearance of
   5 a window's text.
   6
   7 You can retrieve the current system font settings with \helpref{wxSystemSettings}{wxsystemsettings}.
   8
   9 \helpref{wxSystemSettings}{wxsystemsettings}
  10
  11 \wxheading{Derived from}
  12
  13 \helpref{wxGDIObject}{wxgdiobject}\\
  14 \helpref{wxObject}{wxobject}
  15
  16 \wxheading{Include files}
  17
  18 <wx/font.h>
  19
  20 \wxheading{Constants}
  21
  22 The possible values for the \arg{family} parameter of \helpref{wxFont
  23 constructor}{wxfontctor} are (the old names are for compatibility only):
  24
  25 \begin{verbatim}
  26 enum wxFontFamily
  27 {
  28     wxFONTFAMILY_DEFAULT = wxDEFAULT,
  29     wxFONTFAMILY_DECORATIVE = wxDECORATIVE,
  30     wxFONTFAMILY_ROMAN = wxROMAN,
  31     wxFONTFAMILY_SCRIPT = wxSCRIPT,
  32     wxFONTFAMILY_SWISS = wxSWISS,
  33     wxFONTFAMILY_MODERN = wxMODERN,
  34     wxFONTFAMILY_TELETYPE = wxTELETYPE,
  35     wxFONTFAMILY_MAX
  36 };
  37 \end{verbatim}
  38
  39 The font flags which can be used during the font creation are:
  40
  41 \begin{verbatim}
  42 enum
  43 {
  44     // no special flags: font with default weight/slant/anti-aliasing
  45     wxFONTFLAG_DEFAULT          = 0,
  46
  47     // slant flags (default: no slant)
  48     wxFONTFLAG_ITALIC           = 1 << 0,
  49     wxFONTFLAG_SLANT            = 1 << 1,
  50
  51     // weight flags (default: medium)
  52     wxFONTFLAG_LIGHT            = 1 << 2,
  53     wxFONTFLAG_BOLD             = 1 << 3,
  54
  55     // anti-aliasing flag: force on or off (default: the current system default)
  56     wxFONTFLAG_ANTIALIASED      = 1 << 4,
  57     wxFONTFLAG_NOT_ANTIALIASED  = 1 << 5,
  58
  59     // underlined/strikethrough flags (default: no lines)
  60     wxFONTFLAG_UNDERLINED       = 1 << 6,
  61     wxFONTFLAG_STRIKETHROUGH    = 1 << 7,
  62 };
  63 \end{verbatim}
  64
  65 The known font encodings are:
  66
  67 \begin{verbatim}
  68 enum wxFontEncoding
  69 {
  70     wxFONTENCODING_SYSTEM = -1,     // system default
  71     wxFONTENCODING_DEFAULT,         // current default encoding
  72
  73     // ISO8859 standard defines a number of single-byte charsets
  74     wxFONTENCODING_ISO8859_1,       // West European (Latin1)
  75     wxFONTENCODING_ISO8859_2,       // Central and East European (Latin2)
  76     wxFONTENCODING_ISO8859_3,       // Esperanto (Latin3)
  77     wxFONTENCODING_ISO8859_4,       // Baltic (old) (Latin4)
  78     wxFONTENCODING_ISO8859_5,       // Cyrillic
  79     wxFONTENCODING_ISO8859_6,       // Arabic
  80     wxFONTENCODING_ISO8859_7,       // Greek
  81     wxFONTENCODING_ISO8859_8,       // Hebrew
  82     wxFONTENCODING_ISO8859_9,       // Turkish (Latin5)
  83     wxFONTENCODING_ISO8859_10,      // Variation of Latin4 (Latin6)
  84     wxFONTENCODING_ISO8859_11,      // Thai
  85     wxFONTENCODING_ISO8859_12,      // doesn't exist currently, but put it
  86                                     // here anyhow to make all ISO8859
  87                                     // consecutive numbers
  88     wxFONTENCODING_ISO8859_13,      // Baltic (Latin7)
  89     wxFONTENCODING_ISO8859_14,      // Latin8
  90     wxFONTENCODING_ISO8859_15,      // Latin9 (a.k.a. Latin0, includes euro)
  91     wxFONTENCODING_ISO8859_MAX,
  92
  93     // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
  94     wxFONTENCODING_KOI8,            // we don't support any of KOI8 variants
  95     wxFONTENCODING_ALTERNATIVE,     // same as MS-DOS CP866
  96     wxFONTENCODING_BULGARIAN,       // used under Linux in Bulgaria
  97
  98     // what would we do without Microsoft? They have their own encodings
  99         // for DOS
 100     wxFONTENCODING_CP437,           // original MS-DOS codepage
 101     wxFONTENCODING_CP850,           // CP437 merged with Latin1
 102     wxFONTENCODING_CP852,           // CP437 merged with Latin2
 103     wxFONTENCODING_CP855,           // another cyrillic encoding
 104     wxFONTENCODING_CP866,           // and another one
 105         // and for Windows
 106     wxFONTENCODING_CP874,           // WinThai
 107     wxFONTENCODING_CP1250,          // WinLatin2
 108     wxFONTENCODING_CP1251,          // WinCyrillic
 109     wxFONTENCODING_CP1252,          // WinLatin1
 110     wxFONTENCODING_CP1253,          // WinGreek (8859-7)
 111     wxFONTENCODING_CP1254,          // WinTurkish
 112     wxFONTENCODING_CP1255,          // WinHebrew
 113     wxFONTENCODING_CP1256,          // WinArabic
 114     wxFONTENCODING_CP1257,          // WinBaltic (same as Latin 7)
 115     wxFONTENCODING_CP12_MAX,
 116
 117     wxFONTENCODING_UTF7,            // UTF-7 Unicode encoding
 118     wxFONTENCODING_UTF8,            // UTF-8 Unicode encoding
 119
 120     wxFONTENCODING_UNICODE,         // Unicode - currently used only by
 121                                     // wxEncodingConverter class
 122
 123     wxFONTENCODING_MAX
 124 };
 125 \end{verbatim}
 126
 127 \wxheading{Predefined objects}
 128
 129 Objects:
 130
 131 {\bf wxNullFont}
 132
 133 Pointers:
 134
 135 {\bf wxNORMAL\_FONT\\
 136 wxSMALL\_FONT\\
 137 wxITALIC\_FONT\\
 138 wxSWISS\_FONT}
 139
 140 \wxheading{See also}
 141
 142 \helpref{wxFont overview}{wxfontoverview}, \helpref{wxDC::SetFont}{wxdcsetfont},\rtfsp
 143 \helpref{wxDC::DrawText}{wxdcdrawtext}, \helpref{wxDC::GetTextExtent}{wxdcgettextextent},\rtfsp
 144 \helpref{wxFontDialog}{wxfontdialog}, \helpref{wxSystemSettings}{wxsystemsettings}
 145
 146 \latexignore{\rtfignore{\wxheading{Members}}}
 147
 148
 149 \membersection{wxFont::wxFont}\label{wxfontctor}
 150
 151 \func{}{wxFont}{\void}
 152
 153 Default constructor.
 154
 155 \func{}{wxFont}{\param{int}{ pointSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{int}{ weight},
 156  \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""},
 157  \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}
 158
 159 \func{}{wxFont}{\param{const wxSize\&}{ pixelSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{int}{ weight},
 160  \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""},
 161  \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}
 162
 163 Creates a font object with the specified attributes.
 164
 165 \wxheading{Parameters}
 166
 167 \docparam{pointSize}{Size in points.}
 168
 169 \docparam{pixelSize}{Size in pixels: this is directly supported only under MSW
 170 currently where this constructor can be used directly, under other platforms a
 171 font with the closest size to the given one is found using binary search and
 172 the static \helpref{New}{wxfontnew} method must be used.}
 173
 174 \docparam{family}{Font family, a generic way of referring to fonts without specifying actual facename. One of:
 175
 176 \twocolwidtha{5cm}
 177 \begin{twocollist}\itemsep=0pt
 178 \twocolitem{{\bf wxDEFAULT}}{Chooses a default font.}
 179 \twocolitem{{\bf wxDECORATIVE}}{A decorative font.}
 180 \twocolitem{{\bf wxROMAN}}{A formal, serif font.}
 181 \twocolitem{{\bf wxSCRIPT}}{A handwriting font.}
 182 \twocolitem{{\bf wxSWISS}}{A sans-serif font.}
 183 \twocolitem{{\bf wxMODERN}}{A fixed pitch font.}
 184 \end{twocollist}}
 185
 186 \docparam{style}{One of {\bf wxNORMAL}, {\bf wxSLANT} and {\bf wxITALIC}.}
 187
 188 \docparam{weight}{One of {\bf wxNORMAL}, {\bf wxLIGHT} and {\bf wxBOLD}.}
 189
 190 \docparam{underline}{The value can be true or false. At present this has an effect on Windows and Motif 2.x only.}
 191
 192 \docparam{faceName}{An optional string specifying the actual typeface to be used. If the empty string,
 193 a default typeface will chosen based on the family.}
 194
 195 \docparam{encoding}{An encoding which may be one of
 196 \twocolwidtha{5cm}
 197 \begin{twocollist}\itemsep=0pt
 198 \twocolitem{{\bf wxFONTENCODING\_SYSTEM}}{Default system encoding.}
 199 \twocolitem{{\bf wxFONTENCODING\_DEFAULT}}{Default application encoding: this
 200 is the encoding set by calls to
 201 \helpref{SetDefaultEncoding}{wxfontsetdefaultencoding} and which may be set to,
 202 say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the
 203 default application encoding is the same as default system encoding.}
 204 \twocolitem{{\bf wxFONTENCODING\_ISO8859\_1...15}}{ISO8859 encodings.}
 205 \twocolitem{{\bf wxFONTENCODING\_KOI8}}{The standard Russian encoding for Internet.}
 206 \twocolitem{{\bf wxFONTENCODING\_CP1250...1252}}{Windows encodings similar to ISO8859 (but not identical).}
 207 \end{twocollist}
 208 If the specified encoding isn't available, no font is created
 209 (see also \helpref{font encoding overview}{wxfontencodingoverview}).
 210 }
 211
 212 \wxheading{Remarks}
 213
 214 If the desired font does not exist, the closest match will be chosen.
 215 Under Windows, only scalable TrueType fonts are used.
 216
 217 See also \helpref{wxDC::SetFont}{wxdcsetfont}, \helpref{wxDC::DrawText}{wxdcdrawtext}
 218 and \helpref{wxDC::GetTextExtent}{wxdcgettextextent}.
 219
 220
 221 \membersection{wxFont::\destruct{wxFont}}\label{wxfontdtor}
 222
 223 \func{}{\destruct{wxFont}}{\void}
 224
 225 Destructor.
 226
 227 \wxheading{Remarks}
 228
 229 The destructor may not delete the underlying font object of the native windowing
 230 system, since wxFont uses a reference counting system for efficiency.
 231
 232 Although all remaining fonts are deleted when the application exits,
 233 the application should try to clean up all fonts itself. This is because
 234 wxWidgets cannot know if a pointer to the font object is stored in an
 235 application data structure, and there is a risk of double deletion.
 236
 237
 238 \membersection{wxFont::IsFixedWidth}\label{wxfontisfixedwidth}
 239
 240 \constfunc{bool}{IsFixedWidth}{\void}
 241
 242 Returns {\tt true} if the font is a fixed width (or monospaced) font,
 243 {\tt false} if it is a proportional one or font is invalid.
 244
 245
 246 \membersection{wxFont::GetDefaultEncoding}\label{wxfontgetdefaultencoding}
 247
 248 \func{static wxFontEncoding}{GetDefaultEncoding}{\void}
 249
 250 Returns the current application's default encoding.
 251
 252 \wxheading{See also}
 253
 254 \helpref{Font encoding overview}{wxfontencodingoverview},
 255 \helpref{SetDefaultEncoding}{wxfontsetdefaultencoding}
 256
 257
 258 \membersection{wxFont::GetFaceName}\label{wxfontgetfacename}
 259
 260 \constfunc{wxString}{GetFaceName}{\void}
 261
 262 Returns the typeface name associated with the font, or the empty string if there is no
 263 typeface information.
 264
 265 \wxheading{See also}
 266
 267 \helpref{wxFont::SetFaceName}{wxfontsetfacename}
 268
 269
 270 \membersection{wxFont::GetFamily}\label{wxfontgetfamily}
 271
 272 \constfunc{int}{GetFamily}{\void}
 273
 274 Gets the font family. See \helpref{wxFont::wxFont}{wxfontctor} for a list of valid
 275 family identifiers.
 276
 277 \wxheading{See also}
 278
 279 \helpref{wxFont::SetFamily}{wxfontsetfamily}
 280
 281
 282 \membersection{wxFont::GetNativeFontInfoDesc}\label{wxfontgetnativefontinfodesc}
 283
 284 \constfunc{wxString}{GetNativeFontInfoDesc}{\void}
 285
 286 Returns the platform-dependent string completely describing this font or an
 287 empty string if the font wasn't constructed using the native font description.
 288
 289 \wxheading{See also}
 290
 291 \helpref{wxFont::SetNativeFontInfo}{wxfontsetnativefontinfo}
 292
 293
 294 \membersection{wxFont::GetPointSize}\label{wxfontgetpointsize}
 295
 296 \constfunc{int}{GetPointSize}{\void}
 297
 298 Gets the point size.
 299
 300 \wxheading{See also}
 301
 302 \helpref{wxFont::SetPointSize}{wxfontsetpointsize}
 303
 304
 305 \membersection{wxFont::GetStyle}\label{wxfontgetstyle}
 306
 307 \constfunc{int}{GetStyle}{\void}
 308
 309 Gets the font style. See \helpref{wxFont::wxFont}{wxfontctor} for a list of valid
 310 styles.
 311
 312 \wxheading{See also}
 313
 314 \helpref{wxFont::SetStyle}{wxfontsetstyle}
 315
 316
 317 \membersection{wxFont::GetUnderlined}\label{wxfontgetunderlined}
 318
 319 \constfunc{bool}{GetUnderlined}{\void}
 320
 321 Returns true if the font is underlined, false otherwise.
 322
 323 \wxheading{See also}
 324
 325 \helpref{wxFont::SetUnderlined}{wxfontsetunderlined}
 326
 327
 328 \membersection{wxFont::GetWeight}\label{wxfontgetweight}
 329
 330 \constfunc{int}{GetWeight}{\void}
 331
 332 Gets the font weight. See \helpref{wxFont::wxFont}{wxfontctor} for a list of valid
 333 weight identifiers.
 334
 335 \wxheading{See also}
 336
 337 \helpref{wxFont::SetWeight}{wxfontsetweight}
 338
 339
 340 \membersection{wxFont::New}\label{wxfontnew}
 341
 342 \func{static wxFont *}{New}{\param{int}{ pointSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{int}{ weight},
 343  \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""},
 344  \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}
 345
 346 \func{static wxFont *}{New}{\param{int}{ pointSize}, \param{wxFontFamily}{ family},
 347  \param{int}{ flags = \texttt{wxFONTFLAG\_DEFAULT}}, \param{const wxString\& }{faceName = ""},
 348  \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}
 349
 350 \func{static wxFont *}{New}{\param{const wxSize\&}{ pixelSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{int}{ weight},
 351  \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""},
 352  \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}
 353
 354 \func{static wxFont *}{New}{\param{const wxSize\&}{ pixelSize}, \param{wxFontFamily}{ family},
 355  \param{int}{ flags = \texttt{wxFONTFLAG\_DEFAULT}}, \param{const wxString\& }{faceName = ""},
 356  \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}
 357
 358 These functions take the same parameters as \helpref{wxFont
 359 constructor}{wxfontctor} and return a new font object allocated on the heap.
 360
 361 Using \texttt{New()} is currently the only way to directly create a font with
 362 the given size in pixels on platforms other than wxMSW.
 363
 364
 365 \membersection{wxFont::Ok}\label{wxfontok}
 366
 367 \constfunc{bool}{Ok}{\void}
 368
 369 Returns {\tt true} if this object is a valid font, {\tt false} otherwise.
 370
 371
 372 \membersection{wxFont::SetDefaultEncoding}\label{wxfontsetdefaultencoding}
 373
 374 \func{static void}{SetDefaultEncoding}{\param{wxFontEncoding }{encoding}}
 375
 376 Sets the default font encoding.
 377
 378 \wxheading{See also}
 379
 380 \helpref{Font encoding overview}{wxfontencodingoverview},
 381 \helpref{GetDefaultEncoding}{wxfontgetdefaultencoding}
 382
 383
 384 \membersection{wxFont::SetFaceName}\label{wxfontsetfacename}
 385
 386 \func{void}{SetFaceName}{\param{const wxString\& }{faceName}}
 387
 388 Sets the facename for the font.
 389
 390 \wxheading{Parameters}
 391
 392 \docparam{faceName}{A valid facename, which should be on the end-user's system.}
 393
 394 \wxheading{Remarks}
 395
 396 To avoid portability problems, don't rely on a specific face, but specify the font family
 397 instead or as well. A suitable font will be found on the end-user's system. If both the
 398 family and the facename are specified, wxWidgets will first search for the specific face,
 399 and then for a font belonging to the same family.
 400
 401 \wxheading{See also}
 402
 403 \helpref{wxFont::GetFaceName}{wxfontgetfacename}, \helpref{wxFont::SetFamily}{wxfontsetfamily}
 404
 405
 406 \membersection{wxFont::SetFamily}\label{wxfontsetfamily}
 407
 408 \func{void}{SetFamily}{\param{int}{ family}}
 409
 410 Sets the font family.
 411
 412 \wxheading{Parameters}
 413
 414 \docparam{family}{One of:
 415
 416 \twocolwidtha{5cm}
 417 \begin{twocollist}\itemsep=0pt
 418 \twocolitem{{\bf wxDEFAULT}}{Chooses a default font.}
 419 \twocolitem{{\bf wxDECORATIVE}}{A decorative font.}
 420 \twocolitem{{\bf wxROMAN}}{A formal, serif font.}
 421 \twocolitem{{\bf wxSCRIPT}}{A handwriting font.}
 422 \twocolitem{{\bf wxSWISS}}{A sans-serif font.}
 423 \twocolitem{{\bf wxMODERN}}{A fixed pitch font.}
 424 \end{twocollist}}
 425
 426 \wxheading{See also}
 427
 428 \helpref{wxFont::GetFamily}{wxfontgetfamily}, \helpref{wxFont::SetFaceName}{wxfontsetfacename}
 429
 430
 431 \membersection{wxFont::SetNativeFontInfo}\label{wxfontsetnativefontinfo}
 432
 433 \func{void}{SetNativeFontInfo}{\param{const wxString\& }{info}}
 434
 435 Creates the font corresponding to the given native font description string
 436 which must have been previously returned by
 437 \helpref{GetNativeFontInfoDesc}{wxfontgetnativefontinfodesc}. If the string is
 438 invalid, font is unchanged.
 439
 440
 441 \membersection{wxFont::SetPointSize}\label{wxfontsetpointsize}
 442
 443 \func{void}{SetPointSize}{\param{int}{ pointSize}}
 444
 445 Sets the point size.
 446
 447 \wxheading{Parameters}
 448
 449 \docparam{pointSize}{Size in points.}
 450
 451 \wxheading{See also}
 452
 453 \helpref{wxFont::GetPointSize}{wxfontgetpointsize}
 454
 455
 456 \membersection{wxFont::SetStyle}\label{wxfontsetstyle}
 457
 458 \func{void}{SetStyle}{\param{int}{ style}}
 459
 460 Sets the font style.
 461
 462 \wxheading{Parameters}
 463
 464 \docparam{style}{One of {\bf wxNORMAL}, {\bf wxSLANT} and {\bf wxITALIC}.}
 465
 466 \wxheading{See also}
 467
 468 \helpref{wxFont::GetStyle}{wxfontgetstyle}
 469
 470
 471 \membersection{wxFont::SetUnderlined}\label{wxfontsetunderlined}
 472
 473 \func{void}{SetUnderlined}{\param{const bool}{ underlined}}
 474
 475 Sets underlining.
 476
 477 \wxheading{Parameters}
 478
 479 \docparam{underlining}{true to underline, false otherwise.}
 480
 481 \wxheading{See also}
 482
 483 \helpref{wxFont::GetUnderlined}{wxfontgetunderlined}
 484
 485
 486 \membersection{wxFont::SetWeight}\label{wxfontsetweight}
 487
 488 \func{void}{SetWeight}{\param{int}{ weight}}
 489
 490 Sets the font weight.
 491
 492 \wxheading{Parameters}
 493
 494 \docparam{weight}{One of {\bf wxNORMAL}, {\bf wxLIGHT} and {\bf wxBOLD}.}
 495
 496 \wxheading{See also}
 497
 498 \helpref{wxFont::GetWeight}{wxfontgetweight}
 499
 500
 501 \membersection{wxFont::operator $=$}\label{wxfontassignment}
 502
 503 \func{wxFont\&}{operator $=$}{\param{const wxFont\& }{font}}
 504
 505 Assignment operator, using reference counting. Returns a reference
 506 to `this'.
 507
 508
 509 \membersection{wxFont::operator $==$}\label{wxfontequals}
 510
 511 \func{bool}{operator $==$}{\param{const wxFont\& }{font}}
 512
 513 Equality operator. Two fonts are equal if they contain pointers
 514 to the same underlying font data. It does not compare each attribute,
 515 so two independently-created fonts using the same parameters will
 516 fail the test.
 517
 518
 519 \membersection{wxFont::operator $!=$}\label{wxfontnotequals}
 520
 521 \func{bool}{operator $!=$}{\param{const wxFont\& }{font}}
 522
 523 Inequality operator. Two fonts are not equal if they contain pointers
 524 to different underlying font data. It does not compare each attribute.
 525