docs/doxygen/overviews/fontencoding.h

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