X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..afbe906abdf9aa69a56571b8b20b095351dd8f34:/docs/latex/wx/tfont.tex

diff --git a/docs/latex/wx/tfont.tex b/docs/latex/wx/tfont.tex
index 9e6c6d83db..82b219b3eb 100644
--- a/docs/latex/wx/tfont.tex
+++ b/docs/latex/wx/tfont.tex
@@ -1,36 +1,64 @@
-\section{Font overview}\label{wxfontoverview}
+\section{wxFont overview}\label{wxfontoverview}
 
-Class: \helpref{wxFont}{wxfont}
+Class: \helpref{wxFont}{wxfont}, \helpref{wxFontDialog}{wxfontdialog}
 
 A font is an object which determines the appearance of text, primarily
-when drawing text to a canvas or device context. A font is determined by
-up to six parameters:
+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):
 
 \begin{twocollist}\itemsep=0pt
 \twocolitem{Point size}{This is the standard way of referring to text size.}
 \twocolitem{Family}{Supported families are:
-  {\bf wxDEFAULT, wxDECORATIVE, wxROMAN, wxSCRIPT, wxSWISS, wxMODERN}.
-  {\bf wxMODERN} is a fixed pitch font; the others are either fixed or variable pitch.}
+ {\bf wxDEFAULT, wxDECORATIVE, wxROMAN, wxSCRIPT, wxSWISS, wxMODERN}.
+ {\bf wxMODERN} is a fixed pitch font; the others are either fixed or variable pitch.}
 \twocolitem{Style}{The value can be {\bf wxNORMAL, wxSLANT} or {\bf wxITALIC}.}
 \twocolitem{Weight}{The value can be {\bf wxNORMAL, wxLIGHT} or {\bf wxBOLD}.}
 \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
-across platforms because a suitable font will be chosen for the given font family.
+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 id with any file that
-might be transported to a different Windows machine or other platform.
+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.
 
-\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 MM\_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 canvas will
-also scale fonts under both environments.}
+\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.}
 
+\subsection{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 \helpref{wxFontDialog}{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 
+\helpref{wxFont::GetNativeFontInfoDesc}{wxfontgetnativefontinfodesc} and pass
+it to \helpref{wxFont::SetNativeFontInfo}{wxfontsetnativefontinfo} 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.