wxFontEnumerator docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4349 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/classes.tex

@@ -80,7 +80,9 @@
 \input focusevt.tex
 \input font.tex
 \input fontdlg.tex
+\input fontenum.tex
 \input fontlist.tex
+\input fontmap.tex
 \input frame.tex
 \input fsfile.tex
 \input ftp.tex

docs/latex/wx/font.tex

@@ -44,7 +44,8 @@ Default constructor.
  \param{const bool}{ underline = FALSE}, \param{const wxString\& }{faceName = ""},
  \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}
 
-Creates a font object.
+Creates a font object (see \helpref{font encoding
+overview}{wxfontencodingoverview} for the meaning of the last parameter).
 
 \wxheading{Parameters}
 
@@ -106,13 +107,24 @@ Destructor.
 \wxheading{Remarks}
 
 The destructor may not delete the underlying font object of the native windowing
-system, since wxBrush uses a reference counting system for efficiency.
+system, since wxFont uses a reference counting system for efficiency.
 
 Although all remaining fonts are deleted when the application exits,
 the application should try to clean up all fonts itself. This is because
 wxWindows cannot know if a pointer to the font object is stored in an
 application data structure, and there is a risk of double deletion.
 
+\membersection{wxFont::GetDefaultEncoding}\label{wxfontgetdefaultencoding}
+
+\func{static wxFontEncoding}{GetDefaultEncoding}{\void}
+
+Returns the current applications default encoding.
+
+\wxheading{See also}
+
+\helpref{Font encoding overview}{wxfontencodingoverview}, 
+\helpref{SetDefaultEncoding}{wxfontsetdefaultencoding}
+
 \membersection{wxFont::GetFaceName}\label{wxfontgetfacename}
 
 \constfunc{wxString}{GetFaceName}{\void}
@@ -190,6 +202,11 @@ weight identifiers.
 
 Sets the default font encoding.
 
+\wxheading{See also}
+
+\helpref{Font encoding overview}{wxfontencodingoverview}, 
+\helpref{GetDefaultEncoding}{wxfontgetdefaultencoding}
+
 \membersection{wxFont::SetFaceName}\label{wxfontsetfacename}
 
 \func{void}{SetFaceName}{\param{const wxString\& }{faceName}}

docs/latex/wx/fontenum.tex

@@ -0,0 +1,92 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        fontenum.tex
+%% Purpose:     wxFontEnumerator documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     03.11.99
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Vadim Zeitlin
+%% Licence:     wxWindows licence
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxFontEnumerator}}\label{wxfontenumerator}
+
+wxFontEnumerator enumerates either all available fonts on the system or only
+the ones with given attributes - either only fixed-width (suited for use in
+programs such as terminal emulators and the like) or the fonts available in
+the given \helpref{encoding}{wxfontencodingoverview}.
+
+To do this, you just have to call one of EnumerateXXX() functions - either 
+\helpref{EnumerateFamilies}{wxfontenumeratorenumeratefamilies} or 
+\helpref{EnumerateEncodings}{wxfontenumeratorenumerateencodings} and the
+corresponding callback ( 
+\helpref{OnFontFamily}{wxFontEnumeratoronfontfamily} or
+\helpref{OnFontEncoding}{wxfontenumeratoronfontencoding}) will be called
+repeatedly until either all fonts (satisfying the specified criteria) are
+exhausted or the callback returns FALSE.
+
+\wxheading{Virtual functions to override}
+
+Either \helpref{OnFontFamily}{wxfontenumeratoronfontfamily} or 
+\helpref{OnFontEncoding}{wxfontenumeratoronfontencoding} should be overridden
+depending on whether you plan to call 
+\helpref{EnumerateFamilies}{wxfontenumeratorenumeratefamilies} or 
+\helpref{EnumerateEncodings}{wxfontenumeratorenumerateencodings}. Of course,
+if you call both of them, you should override both functions.
+
+\wxheading{Derived from}
+
+None
+
+\wxheading{Include files}
+
+<wx/fontenum.h>
+
+\wxheading{See also}
+
+\helpref{Font encoding overview}{wxfontencodingoverview}, 
+\helpref{Font sample}{samplefont}, 
+\helpref{wxFont}{wxfont}, 
+\helpref{wxFontMapper}{wxfontmapper}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxFontEnumerator::EnumerateFamilies}\label{wxfontenumeratorenumeratefamilies}
+
+\func{virtual bool}{EnumerateFamilies}{
+    \param{wxFontEncoding }{encoding = wxFONTENCODING\_SYSTEM},
+    \param{bool }{fixedWidthOnly = FALSE}}
+
+Call \helpref{OnFontFamily}{wxfontenumeratoronfontfamily} for each font which
+supports given encoding (only if it is not wxFONTENCODING\_SYSTEM) and is of
+fixed width (if {\it fixedWidthOnly} is TRUE).
+
+Calling this function with default arguments will result in enumerating all
+fonts available on the system.
+
+\membersection{wxFontEnumerator::EnumerateEncodings}\label{wxfontenumeratorenumerateencodings}
+
+\func{virtual bool}{EnumerateEncodings}{\param{const wxString\& }{font = ""}}
+
+Call \helpref{OnFontEncoding}{wxfontenumeratoronfontencoding} for each
+encoding supported by the given font - or for each encoding supported by at
+least some font if {\it font} is not specified.
+
+\membersection{wxFontEnumerator::OnFontFamily}\label{wxfontenumeratoronfontfamily}
+
+\func{virtual bool}{OnFontFamily}{\param{const wxString\& }{font}}
+
+Called by \helpref{EnumerateFamilies}{wxfontenumeratorenumeratefamilies} for
+each match. Return TRUE to continue enumeration or FALSE to stop it.
+
+\membersection{wxFontEnumerator::OnFontEncoding}\label{wxfontenumeratoronfontencoding}
+
+\func{virtual bool}{OnFontEncoding}{
+    \param{const wxString\& }{font},
+    \param{const wxString\& }{encoding}
+}
+
+Called by \helpref{EnumerateEncodings}{wxfontenumeratorenumerateencodings} for
+each match. Return TRUE to continue enumeration or FALSE to stop it.
+
+

docs/latex/wx/fontmap.tex

@@ -0,0 +1,14 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        fontmap.tex
+%% Purpose:     wxFontMapper documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     03.11.99
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Vadim Zeitlin
+%% Licence:     wxWindows licence
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxFontMapper}}\label{wxfontmapper}
+
+TODO.

docs/latex/wx/tfont.tex

@@ -4,7 +4,7 @@ Class: \helpref{wxFont}{wxfont}
 
 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
-up to six parameters:
+the following parameters (not all of them have to be specified, of course):
 
 \begin{twocollist}\itemsep=0pt
 \twocolitem{Point size}{This is the standard way of referring to text size.}
@@ -16,21 +16,26 @@ up to six parameters:
 \twocolitem{Underlining}{The value can be TRUE or FALSE.}
 \twocolitem{Face name}{An optional string specifying the actual typeface to be used. If NULL,
 a default typeface will chosen based on the family.}
+\twocolitem{Encoding}{The font encoding (see {\bf wxFONTENCODING\_XXX}
+constants and the \helpref{font overview}{wxfontencodingoverview} for more
+details)}
 \end{twocollist}
 
-Specifying a family, rather than a specific typeface name, ensures a degree of portability
+Specifying a family, rather than a specific typeface name, ensures a degree of
-across platforms because a suitable font will be chosen for the given font family.
+portability across platforms because a suitable font will be chosen for the
+given font family.
 
-Under Windows, the face name can be one of the installed fonts on the user's system. Since
+Under Windows, the face name can be one of the installed fonts on the user's
-the choice of fonts differs from system to system, either choose standard Windows fonts,
+system. Since the choice of fonts differs from system to system, either choose
-or if allowing the user to specify a face name, store the family id with any file that
+standard Windows fonts, or if allowing the user to specify a face name, store
-might be transported to a different Windows machine or other platform.
+the family id with any file that might be transported to a different Windows
+machine or other platform.
 
-\normalbox{{\bf Note:} There is currently a difference between the appearance of fonts on the
+\normalbox{{\bf Note:} There is currently a difference between the appearance
-two platforms, if the mapping mode is anything other than wxMM\_TEXT.
+of fonts on the two platforms, if the mapping mode is anything other than
-Under X, font size is always specified in points. Under MS Windows, the
+wxMM\_TEXT. Under X, font size is always specified in points. Under MS
-unit for text is points but the text is scaled according to the
+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
+current mapping mode. However, user scaling on a device context will also
-also scale fonts under both environments.}
+scale fonts under both environments.}
 
 

docs/latex/wx/tfontenc.tex

@@ -0,0 +1,85 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        tfontenc.tex
+%% Purpose:     font encoding overview
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     03.11.99
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Vadim Zeitlin
+%% Licence:     wxWindows licence
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Font encoding overview}\label{wxfontencodingoverview}
+
+wxWindows has support for multiple font encodings starting from release 2.2.
+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 alphabetes and here other encodings come into play. Please
+note that we will only discuss 8-bit fonts here and not 
+\helpref{Unicode}{unicode}.
+
+Font encoding support is assured by several classes: 
+\helpref{wxFont}{wxfont} itself, but also 
+\helpref{wxFontEnumerator}{wxfontenumerator} and 
+\helpref{wxFontMapper}{wxfontmapper}. wxFont encoding support is reflected by
+a (new) constructor parameter {\it encoding} which takes one of the following
+values (elements of enumeration type {\tt wxFontEncoding}):
+
+\begin{twocollist}
+\twocolitem{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).}
+\twocolitem{wxFONTENCODING\_DEFAULT}{The applications default encoding as
+returned by \helpref{wxFont::GetDefaultEncoding}{wxfontgetdefaultencoding}. 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).}
+\twocolitem{wxFONTENCODING\_ISO8859\_1..15}{ISO8859 family encodings which are
+usually used by all non-Microsoft operating systems}
+\twocolitem{wxFONTENCODING\_KOI8}{Standard cyrillic encoding for the Internet
+(but see also wxFONTENCODING\_ISO8859\_5 and wxFONTENCODING\_CP1251)}
+\twocolitem{wxFONTENCODING\_CP1250}{Microsoft analogue of ISO8859-2}
+\twocolitem{wxFONTENCODING\_CP1251}{Microsoft analogue of ISO8859-5}
+\twocolitem{wxFONTENCODING\_CP1252}{Microsoft analogue of ISO8859-1}
+\end{twocollist}
+
+As you may see, Microsofts 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) encodigns should make it clear that using
+encodings is less easy than it might seem. The problems arise both from the
+fact that the standard encodigns 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, not Win32, systems).
+
+To allow to see clearer in this, \helpref{wxFontEnumerator}{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 (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 
+\helpref{wxFontEnumerator}{wxfontenumerator} will never return one, even if
+the user has installed a KOI8 font on his system.
+
+To solve this problem, \helpref{wxFontMapper}{wxfontmapper} class is provided.
+This class stores the mapping between the encodings and the font face
+names<EFBFBD>which support them in a \helpref{wxConfig}{wxconfigoverview} object. Of
+course, it would be fairly useless if it tried to determine these mappings by
+itself, so, instead, it may (optionally) ask the user and remember his answers
+so that the next time the program will automatically choose the correct font.
+
+All these topics are illustrated by the \helpref{font sample}{samplefont},
+please refer to it and the documentation of the classes mentioned here for
+further explanations.
+

docs/latex/wx/topics.tex

@@ -42,6 +42,7 @@ This chapter contains a selection of topic overviews.
 \input tthreads.tex
 \input tfile.tex
 \input ti18n.tex
+\input tfontenc.tex
 \input tstream.tex
 \input tusage.tex
 \input ttips.tex

docs/latex/wx/tsamples.tex

@@ -19,6 +19,14 @@ make it easier to find the relevant one if a simple grep through all sources
 didn't help. They also provide some notes about using the samples and what
 features of wxWindows are they supposed to test.
 
+\subsection{Font sample}\label{samplefont}
+
+The font sample demonstrates \helpref{wxFont}{wxfont}, 
+\helpref{wxFontEnumerator}{wxfontenumerator} and 
+\helpref{wxFontMapper}{wxfontmapper} classes. It allows you to see the fonts
+available (to wxWindows) on the computer and shows all characters of the
+chosen font as well.
+
 \subsection{DnD sample}\label{samplednd}
 
 This sample shows both clipboard and drag and drop in action. It is quite non