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

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

/*!

 @page fontencoding_overview Font encoding overview

 wxWidgets has support for multiple font encodings.
 By encoding we mean here the mapping between the character codes and the
 letters. Probably the most well-known encoding is (7 bit) ASCII one which is
 used almost universally now to represent the letters of the English alphabet
 and some other common characters. However, it is not enough to represent the
 letters of foreign alphabets and here other encodings come into play. Please
 note that we will only discuss 8-bit fonts here and not
 #Unicode.
 Font encoding support is ensured by several classes:
 #wxFont itself, but also
 #wxFontEnumerator and
 #wxFontMapper. wxFont encoding support is reflected by
 a (new) constructor parameter @e encoding which takes one of the following
 values (elements of enumeration type @c wxFontEncoding):


 wxFONTENCODING_SYSTEM


 The default encoding of the underlying
 operating system (notice that this might be a "foreign" encoding for foreign
 versions of Windows 9x/NT).


 wxFONTENCODING_DEFAULT


 The applications default encoding as
 returned by wxFont::GetDefaultEncoding. On
 program startup, the applications default encoding is the same as
 wxFONTENCODING_SYSTEM, but may be changed to make all the fonts created later
 to use it (by default).


 wxFONTENCODING_ISO8859_1..15


 ISO8859 family encodings which are
 usually used by all non-Microsoft operating systems


 wxFONTENCODING_KOI8


 Standard Cyrillic encoding for the Internet
 (but see also wxFONTENCODING_ISO8859_5 and wxFONTENCODING_CP1251)


 wxFONTENCODING_CP1250


 Microsoft analogue of ISO8859-2


 wxFONTENCODING_CP1251


 Microsoft analogue of ISO8859-5


 wxFONTENCODING_CP1252


 Microsoft analogue of ISO8859-1


 As you may see, Microsoft's encoding partly mirror the standard ISO8859 ones,
 but there are (minor) differences even between ISO8859-1 (Latin1, ISO encoding
 for Western Europe) and CP1251 (WinLatin1, standard code page for English
 versions of Windows) and there are more of them for other encodings.
 The situation is particularly complicated with Cyrillic encodings for which
 (more than) three incompatible encodings exist: KOI8 (the old standard, widely
 used on the Internet), ISO8859-5 (ISO standard for Cyrillic) and CP1251
 (WinCyrillic).
 This abundance of (incompatible) encodings should make it clear that using
 encodings is less easy than it might seem. The problems arise both from the
 fact that the standard encodings for the given language (say Russian, which is
 written in Cyrillic) are different on different platforms and because the
 fonts in the given encoding might just not be installed (this is especially a
 problem with Unix, or, in general, non-Win32 systems).
 To clarify, the #wxFontEnumerator
 class may be used to enumerate both all available encodings and to find the
 facename(s) in which the given encoding exists. If you can find the font in
 the correct encoding with wxFontEnumerator then your troubles are over, but,
 unfortunately, sometimes this is not enough. For example, there is no standard
 way (that I know of, please tell me if you do!) to find a font on a Windows system
 for KOI8 encoding (only for WinCyrillic one which is quite different), so
 #wxFontEnumerator will never return one, even if
 the user has installed a KOI8 font on his system.
 To solve this problem, a #wxFontMapper class is provided.
 This class stores the mapping between the encodings and the font face
 names which support them in #wxConfig object. Of
 course, it would be fairly useless if it tried to determine these mappings by
 itself, so, instead, it (optionally) asks the user and remembers his answers
 so that the next time the program will automatically choose the correct font.
 All these topics are illustrated by the @ref samplefont_overview;
 please refer to it and the documentation of the classes mentioned here for
 further explanations.

 */
Commit	Line	Data
15b6757b FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: fontencoding
	3	// Purpose: topic overview
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/*!
36c9828f	10
15b6757b	11	@page fontencoding_overview Font encoding overview
36c9828f	12
15b6757b FM	13	wxWidgets has support for multiple font encodings.
	14	By encoding we mean here the mapping between the character codes and the
	15	letters. Probably the most well-known encoding is (7 bit) ASCII one which is
	16	used almost universally now to represent the letters of the English alphabet
	17	and some other common characters. However, it is not enough to represent the
	18	letters of foreign alphabets and here other encodings come into play. Please
36c9828f	19	note that we will only discuss 8-bit fonts here and not
15b6757b	20	#Unicode.
36c9828f FM	21	Font encoding support is ensured by several classes:
	22	#wxFont itself, but also
	23	#wxFontEnumerator and
15b6757b FM	24	#wxFontMapper. wxFont encoding support is reflected by
	25	a (new) constructor parameter @e encoding which takes one of the following
	26	values (elements of enumeration type @c wxFontEncoding):
36c9828f FM	27
	28
	29
	30
	31
	32
15b6757b	33	wxFONTENCODING_SYSTEM
36c9828f FM	34
	35
	36
	37
15b6757b FM	38	The default encoding of the underlying
	39	operating system (notice that this might be a "foreign" encoding for foreign
	40	versions of Windows 9x/NT).
36c9828f FM	41
	42
	43
	44
	45
15b6757b	46	wxFONTENCODING_DEFAULT
36c9828f FM	47
	48
	49
	50
15b6757b FM	51	The applications default encoding as
	52	returned by wxFont::GetDefaultEncoding. On
	53	program startup, the applications default encoding is the same as
	54	wxFONTENCODING_SYSTEM, but may be changed to make all the fonts created later
	55	to use it (by default).
36c9828f FM	56
	57
	58
	59
	60
15b6757b	61	wxFONTENCODING_ISO8859_1..15
36c9828f FM	62
	63
	64
	65
15b6757b FM	66	ISO8859 family encodings which are
15b6757b FM	67	usually used by all non-Microsoft operating systems
36c9828f FM	68
	69
	70
	71
	72
15b6757b	73	wxFONTENCODING_KOI8
36c9828f FM	74
	75
	76
	77
15b6757b FM	78	Standard Cyrillic encoding for the Internet
15b6757b FM	79	(but see also wxFONTENCODING_ISO8859_5 and wxFONTENCODING_CP1251)
36c9828f FM	80
	81
	82
	83
	84
15b6757b	85	wxFONTENCODING_CP1250
36c9828f FM	86
	87
	88
	89
15b6757b	90	Microsoft analogue of ISO8859-2
36c9828f FM	91
	92
	93
	94
	95
15b6757b	96	wxFONTENCODING_CP1251
36c9828f FM	97
	98
	99
	100
15b6757b	101	Microsoft analogue of ISO8859-5
36c9828f FM	102
	103
	104
	105
	106
15b6757b	107	wxFONTENCODING_CP1252
36c9828f FM	108
	109
	110
	111
15b6757b	112	Microsoft analogue of ISO8859-1
36c9828f FM	113
	114
	115
	116
	117
15b6757b FM	118	As you may see, Microsoft's encoding partly mirror the standard ISO8859 ones,
	119	but there are (minor) differences even between ISO8859-1 (Latin1, ISO encoding
	120	for Western Europe) and CP1251 (WinLatin1, standard code page for English
	121	versions of Windows) and there are more of them for other encodings.
	122	The situation is particularly complicated with Cyrillic encodings for which
	123	(more than) three incompatible encodings exist: KOI8 (the old standard, widely
	124	used on the Internet), ISO8859-5 (ISO standard for Cyrillic) and CP1251
	125	(WinCyrillic).
	126	This abundance of (incompatible) encodings should make it clear that using
	127	encodings is less easy than it might seem. The problems arise both from the
	128	fact that the standard encodings for the given language (say Russian, which is
	129	written in Cyrillic) are different on different platforms and because the
	130	fonts in the given encoding might just not be installed (this is especially a
	131	problem with Unix, or, in general, non-Win32 systems).
36c9828f	132	To clarify, the #wxFontEnumerator
15b6757b FM	133	class may be used to enumerate both all available encodings and to find the
	134	facename(s) in which the given encoding exists. If you can find the font in
	135	the correct encoding with wxFontEnumerator then your troubles are over, but,
	136	unfortunately, sometimes this is not enough. For example, there is no standard
	137	way (that I know of, please tell me if you do!) to find a font on a Windows system
36c9828f	138	for KOI8 encoding (only for WinCyrillic one which is quite different), so
15b6757b FM	139	#wxFontEnumerator will never return one, even if
	140	the user has installed a KOI8 font on his system.
	141	To solve this problem, a #wxFontMapper class is provided.
	142	This class stores the mapping between the encodings and the font face
	143	names which support them in #wxConfig object. Of
	144	course, it would be fairly useless if it tried to determine these mappings by
	145	itself, so, instead, it (optionally) asks the user and remembers his answers
	146	so that the next time the program will automatically choose the correct font.
	147	All these topics are illustrated by the @ref samplefont_overview;
	148	please refer to it and the documentation of the classes mentioned here for
	149	further explanations.
36c9828f	150
15b6757b	151	*/
36c9828f FM	152
36c9828f FM	153