1%
2% automatically generated by HelpGen from
3% fontmap.h at 10/Mar/00 23:54:16
4%
5
6\section{\class{wxFontMapper}}\label{wxfontmapper}
7
8wxFontMapper manages user-definable correspondence between logical font
9names and the fonts present on the machine.
10
11The default implementations of all functions will ask the user if they are
12not capable of finding the answer themselves and store the answer in a
13config file (configurable via SetConfigXXX functions). This behaviour may
14be disabled by giving the value of false to "interactive" parameter.
15
16However, the functions will always consult the config file to allow the
17user-defined values override the default logic and there is no way to
18disable this - which shouldn't be ever needed because if "interactive" was
19never true, the config file is never created anyhow.
20
21In case everything else fails (i.e. there is no record in config file
22and "interactive" is false or user denied to choose any replacement), 
23the class queries \helpref{wxEncodingConverter}{wxencodingconverter} 
24for "equivalent" encodings (e.g. iso8859-2 and cp1250) and tries them.
25
26\wxheading{Using wxFontMapper in conjunction with wxMBConv classes}
27
28If you need to display text in encoding which is not available at
29host system (see \helpref{IsEncodingAvailable}{wxfontmapperisencodingavailable}),
30you may use these two classes to find font in some similar encoding
31(see \helpref{GetAltForEncoding}{wxfontmappergetaltforencoding})
32and convert the text to this encoding 
33(\helpref{wxMBConv classes}{mbconvclasses}).
34
35Following code snippet demonstrates it:
36
37\begin{verbatim}
38if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename))
39{
40   wxFontEncoding alternative;
41   if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative,
42                                              facename, false))
43   {
44       wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc));
45       wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative));
46       text = wxString(text.mb_str(convFrom), convTo);
47   }
48   else
49       ...failure (or we may try iso8859-1/7bit ASCII)...
50}
51...display text...
52\end{verbatim}
53
54
55\wxheading{Derived from}
56
57No base class
58
59\wxheading{Include files}
60
61<wx/fontmap.h>
62
63\wxheading{See also}
64
65\helpref{wxEncodingConverter}{wxencodingconverter}, 
66\helpref{Writing non-English applications}{nonenglishoverview}
67
68\latexignore{\rtfignore{\wxheading{Members}}}
69
70
71\membersection{wxFontMapper::wxFontMapper}\label{wxfontmapperwxfontmapper}
72
73\func{}{wxFontMapper}{\void}
74
75Default ctor.
76
77\wxheading{Note}
78
79The preferred way of creating a wxFontMapper instance is to call 
80\helpref{wxFontMapper::Get}{wxfontmapperget}.
81
82
83\membersection{wxFontMapper::\destruct{wxFontMapper}}\label{wxfontmapperdtor}
84
85\func{}{\destruct{wxFontMapper}}{\void}
86
87Virtual dtor for a base class.
88
89
90\membersection{wxFontMapper::CharsetToEncoding}\label{wxfontmappercharsettoencoding}
91
92\func{wxFontEncoding}{CharsetToEncoding}{\param{const wxString\& }{charset}, \param{bool }{interactive = true}}
93
94Returns the encoding for the given charset (in the form of RFC 2046) or
95\texttt{wxFONTENCODING\_SYSTEM} if couldn't decode it.
96
97Be careful when using this function with \arg{interactive} set to \true
98(default value) as the function then may show a dialog box to the user which
99may lead to unexpected reentrancies and may also take a significantly longer
100time than a simple function call. For these reasons, it is almost always a bad
101idea to call this function from the event handlers for repeatedly generated
102events such as \texttt{EVT\_PAINT}.
103
104
105\membersection{wxFontMapper::Get}\label{wxfontmapperget}
106
107\func{static wxFontMapper *}{Get}{\void}
108
109Get the current font mapper object. If there is no current object, creates
110one.
111
112\wxheading{See also}
113
114\helpref{wxFontMapper::Set}{wxfontmapperset}
115
116
117\membersection{wxFontMapper::GetAllEncodingNames}\label{wxfontmappergetallencodingnames}
118
119\func{static const wxChar**}{GetAllEncodingNames}{\param{wxFontEncoding }{encoding}}
120
121Returns the array of all possible names for the given encoding. The array is
122\NULL-terminated. IF it isn't empty, the first name in it is the canonical
123encoding name, i.e. the same string as returned by 
124\helpref{GetEncodingName()}{wxfontmappergetencodingname}.
125
126
127\membersection{wxFontMapper::GetAltForEncoding}\label{wxfontmappergetaltforencoding}
128
129\func{bool}{GetAltForEncoding}{\param{wxFontEncoding }{encoding}, \param{wxNativeEncodingInfo* }{info}, \param{const wxString\& }{facename = wxEmptyString}, \param{bool }{interactive = true}}
130
131\func{bool}{GetAltForEncoding}{\param{wxFontEncoding }{encoding}, \param{wxFontEncoding* }{alt\_encoding}, \param{const wxString\& }{facename = wxEmptyString}, \param{bool }{interactive = true}}
132
133Find an alternative for the given encoding (which is supposed to not be
134available on this system). If successful, return true and fill info
135structure with the parameters required to create the font, otherwise
136return false.
137
138The first form is for wxWidgets' internal use while the second one
139is better suitable for general use -- it returns wxFontEncoding which
140can consequently be passed to wxFont constructor.
141
142
143\membersection{wxFontMapper::GetEncoding}\label{wxfontmappergetencoding}
144
145\func{static wxFontEncoding}{GetEncoding}{\param{size\_t }{n}}
146
147Returns the {\it n}-th supported encoding. Together with 
148\helpref{GetSupportedEncodingsCount()}{wxfontmappergetsupportedencodingscount} 
149this method may be used to get all supported encodings.
150
151
152\membersection{wxFontMapper::GetEncodingDescription}\label{wxfontmappergetencodingdescription}
153
154\func{static wxString}{GetEncodingDescription}{\param{wxFontEncoding }{encoding}}
155
156Return user-readable string describing the given encoding.
157
158
159\membersection{wxFontMapper::GetEncodingFromName}\label{wxfontmappergetencodingfromname}
160
161\func{static wxFontEncoding}{GetEncodingFromName}{\param{const wxString\& }{encoding}}
162
163Return the encoding corresponding to the given internal name. This function is
164the inverse of \helpref{GetEncodingName}{wxfontmappergetencodingname} and is
165intentionally less general than 
166\helpref{CharsetToEncoding}{wxfontmappercharsettoencoding}, i.e. it doesn't
167try to make any guesses nor ever asks the user. It is meant just as a way of
168restoring objects previously serialized using 
169\helpref{GetEncodingName}{wxfontmappergetencodingname}.
170
171
172\membersection{wxFontMapper::GetEncodingName}\label{wxfontmappergetencodingname}
173
174\func{static wxString}{GetEncodingName}{\param{wxFontEncoding }{encoding}}
175
176Return internal string identifier for the encoding (see also 
177\helpref{GetEncodingDescription()}{wxfontmappergetencodingdescription})
178
179\wxheading{See also}
180
181\helpref{GetEncodingFromName}{wxfontmappergetencodingfromname}
182
183
184\membersection{wxFontMapper::GetSupportedEncodingsCount}\label{wxfontmappergetsupportedencodingscount}
185
186\func{static size\_t}{GetSupportedEncodingsCount}{\void}
187
188Returns the number of the font encodings supported by this class. Together with 
189\helpref{GetEncoding}{wxfontmappergetencoding} this method may be used to get
190all supported encodings.
191
192
193\membersection{wxFontMapper::IsEncodingAvailable}\label{wxfontmapperisencodingavailable}
194
195\func{bool}{IsEncodingAvailable}{\param{wxFontEncoding }{encoding}, \param{const wxString\& }{facename = wxEmptyString}}
196
197Check whether given encoding is available in given face or not.
198If no facename is given, find {\it any} font in this encoding.
199
200
201\membersection{wxFontMapper::SetDialogParent}\label{wxfontmappersetdialogparent}
202
203\func{void}{SetDialogParent}{\param{wxWindow* }{parent}}
204
205The parent window for modal dialogs.
206
207
208\membersection{wxFontMapper::SetDialogTitle}\label{wxfontmappersetdialogtitle}
209
210\func{void}{SetDialogTitle}{\param{const wxString\& }{title}}
211
212The title for the dialogs (note that default is quite reasonable).
213
214
215\membersection{wxFontMapper::Set}\label{wxfontmapperset}
216
217\func{static wxFontMapper *}{Set}{\param{wxFontMapper *}{mapper}}
218
219Set the current font mapper object and return previous one (may be NULL).
220This method is only useful if you want to plug-in an alternative font mapper
221into wxWidgets.
222
223\wxheading{See also}
224
225\helpref{wxFontMapper::Get}{wxfontmapperget}
226
227
228\membersection{wxFontMapper::SetConfig}\label{wxfontmappersetconfig}
229
230\func{void}{SetConfig}{\param{wxConfigBase* }{config}}
231
232Set the config object to use (may be NULL to use default).
233
234By default, the global one (from wxConfigBase::Get() will be used) 
235and the default root path for the config settings is the string returned by
236GetDefaultConfigPath().
237
238
239\membersection{wxFontMapper::SetConfigPath}\label{wxfontmappersetconfigpath}
240
241\func{void}{SetConfigPath}{\param{const wxString\& }{prefix}}
242
243Set the root config path to use (should be an absolute path).
244
245