docs/doxygen/overviews/font.h

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