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