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