[wxWidgets.git] / docs / doxygen / overviews / font.h

/////////////////////////////////////////////////////////////////////////////
// Name:        font
// Purpose:     topic overview
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/*!

 @page font_overview wxFont overview

 Class: #wxFont, #wxFontDialog
 A font is an object which determines the appearance of text, primarily
 when drawing text to a window or device context. A font is determined by
 the following parameters (not all of them have to be specified, of course):


 Point size


 This is the standard way of referring to text size.


 Family


 Supported families are:
  @b wxDEFAULT, wxDECORATIVE, wxROMAN, wxSCRIPT, wxSWISS, wxMODERN.
  @b wxMODERN is a fixed pitch font; the others are either fixed or variable pitch.


 Style


 The value can be @b wxNORMAL, wxSLANT or @b wxITALIC.


 Weight


 The value can be @b wxNORMAL, wxLIGHT or @b wxBOLD.


 Underlining


 The value can be @true or @false.


 Face name


 An optional string specifying the actual typeface to be used. If @NULL,
 a default typeface will chosen based on the family.


 Encoding


 The font encoding (see @b wxFONTENCODING_XXX
 constants and the @ref fontencoding_overview for more
 details)


 Specifying a family, rather than a specific typeface name, ensures a degree of
 portability across platforms because a suitable font will be chosen for the
 given font family, however it doesn't allow to choose a font precisely as the
 parameters above don't suffice, in general, to identify all the available fonts
 and this is where using the native font descriptions may be helpful - see
 below.
 Under Windows, the face name can be one of the installed fonts on the user's
 system. Since the choice of fonts differs from system to system, either choose
 standard Windows fonts, or if allowing the user to specify a face name, store
 the family name with any file that might be transported to a different Windows
 machine or other platform.

 @b Note: There is currently a difference between the appearance
 of fonts on the two platforms, if the mapping mode is anything other than
 wxMM_TEXT. Under X, font size is always specified in points. Under MS
 Windows, the unit for text is points but the text is scaled according to the
 current mapping mode. However, user scaling on a device context will also
 scale fonts under both environments.

 @ref nativefontinformation_overview


 @section nativefontinformation Native font information

 An alternative way of choosing fonts is to use the native font description.
 This is the only acceptable solution if the user is allowed to choose the font
 using the #wxFontDialog because the selected font cannot
 be described using only the family name and so, if only family name is stored
 permanently, the user would almost surely see a different font in the program
 later.
 Instead, you should store the value returned by
 wxFont::GetNativeFontInfoDesc and pass
 it to wxFont::SetNativeFontInfo later to
 recreate exactly the same font.
 Note that the contents of this string depends on the platform and shouldn't be
 used for any other purpose (in particular, it is not meant to be shown to the
 user). Also please note that although the native font information is currently
 implemented for Windows and Unix (GTK+ and Motif) ports only, all the methods
 are available for all the ports and should be used to make your program work
 correctly when they are implemented later.

 */
Commit	Line	Data
15b6757b FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: font
	3	// Purpose: topic overview
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/*!
36c9828f	10
15b6757b	11	@page font_overview wxFont overview
36c9828f	12
15b6757b FM	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):
36c9828f FM	17
	18
	19
	20
	21
	22
15b6757b	23	Point size
36c9828f FM	24
	25
	26
	27
15b6757b	28	This is the standard way of referring to text size.
36c9828f FM	29
	30
	31
	32
	33
15b6757b	34	Family
36c9828f FM	35
	36
	37
	38
15b6757b FM	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.
36c9828f FM	42
	43
	44
	45
	46
15b6757b	47	Style
36c9828f FM	48
	49
	50
	51
15b6757b	52	The value can be @b wxNORMAL, wxSLANT or @b wxITALIC.
36c9828f FM	53
	54
	55
	56
	57
15b6757b	58	Weight
36c9828f FM	59
	60
	61
	62
15b6757b	63	The value can be @b wxNORMAL, wxLIGHT or @b wxBOLD.
36c9828f FM	64
	65
	66
	67
	68
15b6757b	69	Underlining
36c9828f FM	70
	71
	72
	73
15b6757b	74	The value can be @true or @false.
36c9828f FM	75
	76
	77
	78
	79
15b6757b	80	Face name
36c9828f FM	81
	82
	83
	84
15b6757b FM	85	An optional string specifying the actual typeface to be used. If @NULL,
15b6757b FM	86	a default typeface will chosen based on the family.
36c9828f FM	87
	88
	89
	90
	91
15b6757b	92	Encoding
36c9828f FM	93
	94
	95
	96
15b6757b FM	97	The font encoding (see @b wxFONTENCODING_XXX
	98	constants and the @ref fontencoding_overview for more
	99	details)
36c9828f FM	100
	101
	102
	103
	104
15b6757b FM	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.
36c9828f	116
15b6757b FM	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.
36c9828f	123
15b6757b	124	@ref nativefontinformation_overview
36c9828f FM	125
36c9828f FM	126
15b6757b	127	@section nativefontinformation Native font information
36c9828f	128
15b6757b FM	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.
36c9828f	135	Instead, you should store the value returned by
15b6757b FM	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.
36c9828f	145
15b6757b	146	*/
36c9828f FM	147
36c9828f FM	148