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