wxFontEnumerator docs

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

diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index 5493fed36bc55e8f786d936604c4bad7cbb0b13d..97a203e1b412f8b6d977ae360815fc4dd2175b1d 100644 (file)
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -80,7 +80,9 @@
 \input focusevt.tex
 \input font.tex
 \input fontdlg.tex
 \input focusevt.tex
 \input font.tex
 \input fontdlg.tex

+\input fontenum.tex

 \input fontlist.tex
 \input fontlist.tex

+\input fontmap.tex

 \input frame.tex
 \input fsfile.tex
 \input ftp.tex
 \input frame.tex
 \input fsfile.tex
 \input ftp.tex

diff --git a/docs/latex/wx/font.tex b/docs/latex/wx/font.tex
index 31190c225910c7da1eeececfe78f1c3efb76bfcd..8a4530faf7175a84d6915288f51f4dca2e6c6f53 100644 (file)
--- a/docs/latex/wx/font.tex
+++ b/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}}
 
  \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}
 
 
 \wxheading{Parameters}
 


@@ -106,13 +107,24 @@ Destructor.
 \wxheading{Remarks}
 
 The destructor may not delete the underlying font object of the native windowing
 \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.
 
 
 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}
 \membersection{wxFont::GetFaceName}\label{wxfontgetfacename}
 
 \constfunc{wxString}{GetFaceName}{\void}


@@ -190,6 +202,11 @@ weight identifiers.
 
 Sets the default font encoding.
 
 
 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}}
 \membersection{wxFont::SetFaceName}\label{wxfontsetfacename}
 
 \func{void}{SetFaceName}{\param{const wxString\& }{faceName}}

diff --git a/docs/latex/wx/fontenum.tex b/docs/latex/wx/fontenum.tex
new file mode 100644 (file)
index 0000000..396ff62
--- /dev/null
+++ b/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.
+
+

diff --git a/docs/latex/wx/fontmap.tex b/docs/latex/wx/fontmap.tex
new file mode 100644 (file)
index 0000000..0041694
--- /dev/null
+++ b/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.

diff --git a/docs/latex/wx/tfont.tex b/docs/latex/wx/tfont.tex
index f79794290ad58150ee6e7e0497c86d5c2acdf4e6..212cbdbb480fad03ee1bc814d4ec901b29d10960 100644 (file)
--- a/docs/latex/wx/tfont.tex
+++ b/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
 
 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.}
 
 \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{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}
 
 \end{twocollist}
 

-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.
-
-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 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
-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.}
+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.
+
+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 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 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.}

 
 
 
 

diff --git a/docs/latex/wx/tfontenc.tex b/docs/latex/wx/tfontenc.tex
new file mode 100644 (file)
index 0000000..441cce6
--- /dev/null
+++ b/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 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.
+

diff --git a/docs/latex/wx/topics.tex b/docs/latex/wx/topics.tex
index 7daf692886b14489b15d74007dc33f53d1e40fd5..cf34d12aef97609ddaf6f1a95754bd3470cfa2dc 100644 (file)
--- a/docs/latex/wx/topics.tex
+++ b/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 tthreads.tex
 \input tfile.tex
 \input ti18n.tex

+\input tfontenc.tex

 \input tstream.tex
 \input tusage.tex
 \input ttips.tex
 \input tstream.tex
 \input tusage.tex
 \input ttips.tex

diff --git a/docs/latex/wx/tsamples.tex b/docs/latex/wx/tsamples.tex
index 619ef54183ad41f94998d293768fba7fecddeb20..69e1b39f8477db3cb857e1cac089e837e6895144 100644 (file)
--- a/docs/latex/wx/tsamples.tex
+++ b/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.
 
 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
 \subsection{DnD sample}\label{samplednd}
 
 This sample shows both clipboard and drag and drop in action. It is quite non