added wxFont::SetNativeFontInfo(string) and documented the native font info stuff

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

diff --git a/docs/latex/wx/font.tex b/docs/latex/wx/font.tex
index 1c3682a2f500dc7d560b211acab1b0e55c7fb586..7fa1453b5ae7e124de8f0a6a6f01cadf7b660c3a 100644 (file)
--- a/docs/latex/wx/font.tex
+++ b/docs/latex/wx/font.tex
@@ -207,12 +207,16 @@ family identifiers.
 
 \helpref{wxFont::SetFamily}{wxfontsetfamily}
 
-\membersection{wxFont::GetFontId}\label{wxfontgetfontid}
+\membersection{wxFont::GetNativeFontInfoDesc}\label{wxfontgetnativefontinfodesc}
 
-\constfunc{int}{GetFontId}{\void}
+\constfunc{wxString}{GetNativeFontInfoDesc}{\void}
 
-Returns the font id, if the portable font system is in operation. See \helpref{Font overview}{wxfontoverview} for
-further details.
+Returns the platform-dependent string completely describing this font or an
+empty string if the font wasn't constructed using the native font description.
+
+\wxheading{See also}
+
+\helpref{wxFont::SetNativeFontInfo}{wxfontsetnativefontinfo}
 
 \membersection{wxFont::GetPointSize}\label{wxfontgetpointsize}
 
@@ -312,6 +316,15 @@ Sets the font family.
 
 \helpref{wxFont::GetFamily}{wxfontgetfamily}, \helpref{wxFont::SetFaceName}{wxfontsetfacename}
 
+\membersection{wxFont::SetNativeFontInfo}\label{wxfontsetnativefontinfo}
+
+\func{void}{SetNativeFontInfo}{\param{const wxString\& }{info}}
+
+Creates the font corresponding to the given native font description string
+which must have been previously returned by 
+\helpref{GetNativeFontInfoDesc}{wxfontgetnativefontinfodesc}. If the string is
+invalid, font is unchanged.
+
 \membersection{wxFont::SetPointSize}\label{wxfontsetpointsize}
 
 \func{void}{SetPointSize}{\param{int}{ pointSize}}

diff --git a/docs/latex/wx/tfont.tex b/docs/latex/wx/tfont.tex
index 7b532f57facada2b6f9e10525f9af35f161e0ed0..82b219b3ebb3c37547ea429c833ec815d3ab856f 100644 (file)
--- a/docs/latex/wx/tfont.tex
+++ b/docs/latex/wx/tfont.tex
@@ -1,6 +1,6 @@
 \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 window or device context. A font is determined by
@@ -23,12 +23,15 @@ details)}
 
 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.
+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
+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
@@ -38,3 +41,24 @@ 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.
+

diff --git a/include/wx/font.h b/include/wx/font.h
index 12ce162da7dad87bdc1f4ab4577d36fbe9982a5c..262bce29f5fefa093a53e9a7a24965827a64049a 100644 (file)
--- a/include/wx/font.h
+++ b/include/wx/font.h
@@ -125,8 +125,7 @@ public:
     virtual void SetUnderlined( bool underlined ) = 0;
     virtual void SetEncoding(wxFontEncoding encoding) = 0;
     virtual void SetNativeFontInfo(const wxNativeFontInfo& info);
-
-    // VZ: there is no void SetNativeFontInfo(const wxString& info), needed?
+    void SetNativeFontInfo(const wxString& info);
 
     // translate the fonts into human-readable string (i.e. GetStyleString()
     // will return "wxITALIC" for an italic font, ...)