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