docs/doxygen/overviews/font.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        font
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11  @page font_overview wxFont overview
  12
  13  Class: #wxFont, #wxFontDialog
  14  A font is an object which determines the appearance of text, primarily
  15  when drawing text to a window or device context. A font is determined by
  16  the following parameters (not all of them have to be specified, of course):
  17
  18
  19
  20
  21
  22
  23  Point size
  24
  25
  26
  27
  28  This is the standard way of referring to text size.
  29
  30
  31
  32
  33
  34  Family
  35
  36
  37
  38
  39  Supported families are:
  40   @b wxDEFAULT, wxDECORATIVE, wxROMAN, wxSCRIPT, wxSWISS, wxMODERN.
  41   @b wxMODERN is a fixed pitch font; the others are either fixed or variable pitch.
  42
  43
  44
  45
  46
  47  Style
  48
  49
  50
  51
  52  The value can be @b wxNORMAL, wxSLANT or @b wxITALIC.
  53
  54
  55
  56
  57
  58  Weight
  59
  60
  61
  62
  63  The value can be @b wxNORMAL, wxLIGHT or @b wxBOLD.
  64
  65
  66
  67
  68
  69  Underlining
  70
  71
  72
  73
  74  The value can be @true or @false.
  75
  76
  77
  78
  79
  80  Face name
  81
  82
  83
  84
  85  An optional string specifying the actual typeface to be used. If @NULL,
  86  a default typeface will chosen based on the family.
  87
  88
  89
  90
  91
  92  Encoding
  93
  94
  95
  96
  97  The font encoding (see @b wxFONTENCODING_XXX
  98  constants and the @ref fontencoding_overview for more
  99  details)
 100
 101
 102
 103
 104
 105  Specifying a family, rather than a specific typeface name, ensures a degree of
 106  portability across platforms because a suitable font will be chosen for the
 107  given font family, however it doesn't allow to choose a font precisely as the
 108  parameters above don't suffice, in general, to identify all the available fonts
 109  and this is where using the native font descriptions may be helpful - see
 110  below.
 111  Under Windows, the face name can be one of the installed fonts on the user's
 112  system. Since the choice of fonts differs from system to system, either choose
 113  standard Windows fonts, or if allowing the user to specify a face name, store
 114  the family name with any file that might be transported to a different Windows
 115  machine or other platform.
 116
 117  @b Note: There is currently a difference between the appearance
 118  of fonts on the two platforms, if the mapping mode is anything other than
 119  wxMM_TEXT. Under X, font size is always specified in points. Under MS
 120  Windows, the unit for text is points but the text is scaled according to the
 121  current mapping mode. However, user scaling on a device context will also
 122  scale fonts under both environments.
 123
 124  @ref nativefontinformation_overview
 125
 126
 127  @section nativefontinformation Native font information
 128
 129  An alternative way of choosing fonts is to use the native font description.
 130  This is the only acceptable solution if the user is allowed to choose the font
 131  using the #wxFontDialog because the selected font cannot
 132  be described using only the family name and so, if only family name is stored
 133  permanently, the user would almost surely see a different font in the program
 134  later.
 135  Instead, you should store the value returned by
 136  wxFont::GetNativeFontInfoDesc and pass
 137  it to wxFont::SetNativeFontInfo later to
 138  recreate exactly the same font.
 139  Note that the contents of this string depends on the platform and shouldn't be
 140  used for any other purpose (in particular, it is not meant to be shown to the
 141  user). Also please note that although the native font information is currently
 142  implemented for Windows and Unix (GTK+ and Motif) ports only, all the methods
 143  are available for all the ports and should be used to make your program work
 144  correctly when they are implemented later.
 145
 146  */
 147
 148