]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/font.h
undo the last change as it results in buildbot configuration error
[wxWidgets.git] / interface / wx / font.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: font.h
3 // Purpose: interface of wxFont
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9
10 /**
11 Standard font families: these are used mainly during wxFont creation to specify
12 the generic properties of the font without hardcoding in the sources a specific
13 face name.
14
15 wxFontFamily thus allows to group the font face names of fonts with similar
16 properties. Most wxWidgets ports use lists of fonts for each font family
17 inspired by the data taken from http://www.codestyle.org/css/font-family.
18 */
19 enum wxFontFamily
20 {
21 wxFONTFAMILY_DEFAULT = wxDEFAULT, //!< Chooses a default font.
22
23 wxFONTFAMILY_DECORATIVE = wxDECORATIVE, //!< A decorative font.
24 wxFONTFAMILY_ROMAN = wxROMAN, //!< A formal, serif font.
25 wxFONTFAMILY_SCRIPT = wxSCRIPT, //!< A handwriting font.
26 wxFONTFAMILY_SWISS = wxSWISS, //!< A sans-serif font.
27
28 /// A fixed pitch font. Note that wxFont currently does not make distinctions
29 /// between @c wxFONTFAMILY_MODERN and @c wxFONTFAMILY_TELETYPE.
30 wxFONTFAMILY_MODERN = wxMODERN,
31
32 /// A teletype (i.e. monospaced) font.
33 /// Monospace fonts have a fixed width like typewriters and often have strong angular
34 /// or block serifs. Monospace font faces are often used code samples and have a simple,
35 /// functional font style.
36 /// See also wxFont::IsFixedWidth() for an easy way to test for monospace property.
37 wxFONTFAMILY_TELETYPE = wxTELETYPE,
38
39 /// Returned by wxFont::GetFamily() when the face name of the font cannot
40 /// be classified into one of the previous wxFontFamily values.
41 wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX,
42
43 wxFONTFAMILY_MAX
44 };
45
46 /**
47 Font styles.
48 */
49 enum wxFontStyle
50 {
51 /// The font is drawn without slant.
52 wxFONTSTYLE_NORMAL = wxNORMAL,
53
54 /// The font is slanted in an italic style.
55 wxFONTSTYLE_ITALIC = wxITALIC,
56
57 /// The font is slanted, but in a roman style.
58 /// Note that under wxMSW this style is the same as @c wxFONTSTYLE_ITALIC.
59 wxFONTSTYLE_SLANT = wxSLANT,
60
61 wxFONTSTYLE_MAX
62 };
63
64 /**
65 Font weights.
66 */
67 enum wxFontWeight
68 {
69 wxFONTWEIGHT_NORMAL = wxNORMAL, //!< Normal font.
70 wxFONTWEIGHT_LIGHT = wxLIGHT, //!< Light font.
71 wxFONTWEIGHT_BOLD = wxBOLD, //!< Bold font.
72 wxFONTWEIGHT_MAX
73 };
74
75 /**
76 The font flag bits for the new font ctor accepting one combined flags word.
77 */
78 enum wxFontFlag
79 {
80 /// no special flags: font with default weight/slant/anti-aliasing
81 wxFONTFLAG_DEFAULT = 0,
82
83 /// slant flags (default: no slant)
84 wxFONTFLAG_ITALIC = 1 << 0,
85 wxFONTFLAG_SLANT = 1 << 1,
86
87 /// weight flags (default: medium)
88 wxFONTFLAG_LIGHT = 1 << 2,
89 wxFONTFLAG_BOLD = 1 << 3,
90
91 /// anti-aliasing flag: force on or off (default: the current system default)
92 wxFONTFLAG_ANTIALIASED = 1 << 4,
93 wxFONTFLAG_NOT_ANTIALIASED = 1 << 5,
94
95 /// underlined/strikethrough flags (default: no lines)
96 wxFONTFLAG_UNDERLINED = 1 << 6,
97 wxFONTFLAG_STRIKETHROUGH = 1 << 7,
98
99 /// the mask of all currently used flags
100 wxFONTFLAG_MASK = wxFONTFLAG_ITALIC |
101 wxFONTFLAG_SLANT |
102 wxFONTFLAG_LIGHT |
103 wxFONTFLAG_BOLD |
104 wxFONTFLAG_ANTIALIASED |
105 wxFONTFLAG_NOT_ANTIALIASED |
106 wxFONTFLAG_UNDERLINED |
107 wxFONTFLAG_STRIKETHROUGH
108 };
109
110
111
112 /**
113 Font encodings.
114
115 See wxFont::SetEncoding().
116 */
117 enum wxFontEncoding
118 {
119 /// Default system encoding.
120 wxFONTENCODING_SYSTEM = -1, // system default
121
122 /// Default application encoding.
123 wxFONTENCODING_DEFAULT, // current default encoding
124
125 // ISO8859 standard defines a number of single-byte charsets
126 wxFONTENCODING_ISO8859_1, //!< West European (Latin1)
127 wxFONTENCODING_ISO8859_2, //!< Central and East European (Latin2)
128 wxFONTENCODING_ISO8859_3, //!< Esperanto (Latin3)
129 wxFONTENCODING_ISO8859_4, //!< Baltic (old) (Latin4)
130 wxFONTENCODING_ISO8859_5, //!< Cyrillic
131 wxFONTENCODING_ISO8859_6, //!< Arabic
132 wxFONTENCODING_ISO8859_7, //!< Greek
133 wxFONTENCODING_ISO8859_8, //!< Hebrew
134 wxFONTENCODING_ISO8859_9, //!< Turkish (Latin5)
135 wxFONTENCODING_ISO8859_10, //!< Variation of Latin4 (Latin6)
136 wxFONTENCODING_ISO8859_11, //!< Thai
137 wxFONTENCODING_ISO8859_12, //!< doesn't exist currently, but put it
138 //!< here anyhow to make all ISO8859
139 //!< consecutive numbers
140 wxFONTENCODING_ISO8859_13, //!< Baltic (Latin7)
141 wxFONTENCODING_ISO8859_14, //!< Latin8
142 wxFONTENCODING_ISO8859_15, //!< Latin9 (a.k.a. Latin0, includes euro)
143 wxFONTENCODING_ISO8859_MAX,
144
145 // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
146 wxFONTENCODING_KOI8, //!< KOI8 Russian
147 wxFONTENCODING_KOI8_U, //!< KOI8 Ukrainian
148 wxFONTENCODING_ALTERNATIVE, //!< same as MS-DOS CP866
149 wxFONTENCODING_BULGARIAN, //!< used under Linux in Bulgaria
150
151 // what would we do without Microsoft? They have their own encodings
152 // for DOS
153 wxFONTENCODING_CP437, //!< original MS-DOS codepage
154 wxFONTENCODING_CP850, //!< CP437 merged with Latin1
155 wxFONTENCODING_CP852, //!< CP437 merged with Latin2
156 wxFONTENCODING_CP855, //!< another cyrillic encoding
157 wxFONTENCODING_CP866, //!< and another one
158 // and for Windows
159 wxFONTENCODING_CP874, //!< WinThai
160 wxFONTENCODING_CP932, //!< Japanese (shift-JIS)
161 wxFONTENCODING_CP936, //!< Chinese simplified (GB)
162 wxFONTENCODING_CP949, //!< Korean (Hangul charset)
163 wxFONTENCODING_CP950, //!< Chinese (traditional - Big5)
164 wxFONTENCODING_CP1250, //!< WinLatin2
165 wxFONTENCODING_CP1251, //!< WinCyrillic
166 wxFONTENCODING_CP1252, //!< WinLatin1
167 wxFONTENCODING_CP1253, //!< WinGreek (8859-7)
168 wxFONTENCODING_CP1254, //!< WinTurkish
169 wxFONTENCODING_CP1255, //!< WinHebrew
170 wxFONTENCODING_CP1256, //!< WinArabic
171 wxFONTENCODING_CP1257, //!< WinBaltic (same as Latin 7)
172 wxFONTENCODING_CP12_MAX,
173
174 wxFONTENCODING_UTF7, //!< UTF-7 Unicode encoding
175 wxFONTENCODING_UTF8, //!< UTF-8 Unicode encoding
176 wxFONTENCODING_EUC_JP, //!< Extended Unix Codepage for Japanese
177 wxFONTENCODING_UTF16BE, //!< UTF-16 Big Endian Unicode encoding
178 wxFONTENCODING_UTF16LE, //!< UTF-16 Little Endian Unicode encoding
179 wxFONTENCODING_UTF32BE, //!< UTF-32 Big Endian Unicode encoding
180 wxFONTENCODING_UTF32LE, // UTF-32 Little Endian Unicode encoding
181
182 wxFONTENCODING_MACROMAN, //!< the standard mac encodings
183 wxFONTENCODING_MACJAPANESE,
184 wxFONTENCODING_MACCHINESETRAD,
185 wxFONTENCODING_MACKOREAN,
186 wxFONTENCODING_MACARABIC,
187 wxFONTENCODING_MACHEBREW,
188 wxFONTENCODING_MACGREEK,
189 wxFONTENCODING_MACCYRILLIC,
190 wxFONTENCODING_MACDEVANAGARI,
191 wxFONTENCODING_MACGURMUKHI,
192 wxFONTENCODING_MACGUJARATI,
193 wxFONTENCODING_MACORIYA,
194 wxFONTENCODING_MACBENGALI,
195 wxFONTENCODING_MACTAMIL,
196 wxFONTENCODING_MACTELUGU,
197 wxFONTENCODING_MACKANNADA,
198 wxFONTENCODING_MACMALAJALAM,
199 wxFONTENCODING_MACSINHALESE,
200 wxFONTENCODING_MACBURMESE,
201 wxFONTENCODING_MACKHMER,
202 wxFONTENCODING_MACTHAI,
203 wxFONTENCODING_MACLAOTIAN,
204 wxFONTENCODING_MACGEORGIAN,
205 wxFONTENCODING_MACARMENIAN,
206 wxFONTENCODING_MACCHINESESIMP,
207 wxFONTENCODING_MACTIBETAN,
208 wxFONTENCODING_MACMONGOLIAN,
209 wxFONTENCODING_MACETHIOPIC,
210 wxFONTENCODING_MACCENTRALEUR,
211 wxFONTENCODING_MACVIATNAMESE,
212 wxFONTENCODING_MACARABICEXT,
213 wxFONTENCODING_MACSYMBOL,
214 wxFONTENCODING_MACDINGBATS,
215 wxFONTENCODING_MACTURKISH,
216 wxFONTENCODING_MACCROATIAN,
217 wxFONTENCODING_MACICELANDIC,
218 wxFONTENCODING_MACROMANIAN,
219 wxFONTENCODING_MACCELTIC,
220 wxFONTENCODING_MACGAELIC,
221 wxFONTENCODING_MACKEYBOARD,
222
223 // more CJK encodings (for historical reasons some are already declared
224 // above)
225 wxFONTENCODING_ISO2022_JP, //!< ISO-2022-JP JIS encoding
226
227 wxFONTENCODING_MAX, //!< highest enumerated encoding value
228
229 wxFONTENCODING_MACMIN = wxFONTENCODING_MACROMAN ,
230 wxFONTENCODING_MACMAX = wxFONTENCODING_MACKEYBOARD ,
231
232 // aliases for endian-dependent UTF encodings
233 wxFONTENCODING_UTF16, //!< native UTF-16
234 wxFONTENCODING_UTF32, //!< native UTF-32
235
236 /// Alias for the native Unicode encoding on this platform
237 /// (this is used by wxEncodingConverter and wxUTFFile only for now)
238 wxFONTENCODING_UNICODE,
239
240 // alternative names for Far Eastern encodings
241 // Chinese
242 wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese
243 wxFONTENCODING_BIG5 = wxFONTENCODING_CP950, //!< Traditional Chinese
244
245 // Japanese (see http://zsigri.tripod.com/fontboard/cjk/jis.html)
246 wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932 //!< Shift JIS
247 };
248
249
250
251 /**
252 @class wxFont
253
254 A font is an object which determines the appearance of text.
255 Fonts are used for drawing text to a device context, and setting the appearance
256 of a window's text.
257
258 This class uses @ref overview_refcount "reference counting and copy-on-write"
259 internally so that assignments between two instances of this class are very
260 cheap. You can therefore use actual objects instead of pointers without
261 efficiency problems. If an instance of this class is changed it will create
262 its own data internally so that other instances, which previously shared the
263 data using the reference counting, are not affected.
264
265 You can retrieve the current system font settings with wxSystemSettings.
266
267 @library{wxcore}
268 @category{gdi}
269
270 @stdobjects
271 ::wxNullFont, ::wxNORMAL_FONT, ::wxSMALL_FONT, ::wxITALIC_FONT, ::wxSWISS_FONT
272
273 @see @ref overview_font, wxDC::SetFont, wxDC::DrawText,
274 wxDC::GetTextExtent, wxFontDialog, wxSystemSettings
275 */
276 class wxFont : public wxGDIObject
277 {
278 public:
279 /**
280 Default ctor.
281 */
282 wxFont();
283
284 /**
285 Copy constructor, uses @ref overview_refcount "reference counting".
286 */
287 wxFont(const wxFont& font);
288
289 /**
290 Creates a font object with the specified attributes.
291
292 @param pointSize
293 Size in points. See SetPointSize() for more info.
294 @param family
295 The font family: a generic portable way of referring to fonts without specifying a
296 facename. This parameter must be one of the ::wxFontFamily enumeration values.
297 If the @a faceName argument is provided, then it overrides the font family.
298 @param style
299 One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
300 @param weight
301 Font weight, sometimes also referred to as font boldness.
302 One of the ::wxFontWeight enumeration values.
303 @param underline
304 The value can be @true or @false.
305 At present this has an effect on Windows and Motif 2.x only.
306 @param faceName
307 An optional string specifying the face name to be used.
308 If it is an empty string, a default face name will be chosen based on the family.
309 @param encoding
310 An encoding which may be one of the enumeration values of ::wxFontEncoding.
311 Briefly these can be summed up as:
312 <TABLE>
313 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
314 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
315 Default application encoding: this is the encoding set by calls to
316 SetDefaultEncoding() and which may be set to, say, KOI8 to create all
317 fonts by default with KOI8 encoding. Initially, the default application
318 encoding is the same as default system encoding.</TD></TR>
319 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
320 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
321 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
322 </TABLE>
323 If the specified encoding isn't available, no font is created
324 (see also @ref overview_fontencoding).
325
326 @remarks If the desired font does not exist, the closest match will be
327 chosen. Under Windows, only scalable TrueType fonts are used.
328 */
329 wxFont(int pointSize, wxFontFamily family, wxFontStyle style,
330 wxFontWeight weight,
331 bool underline = false,
332 const wxString& faceName = wxEmptyString,
333 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
334
335 /**
336 Creates a font object with the specified attributes.
337
338 @param pixelSize
339 Size in pixels. See SetPixelSize() for more info.
340 @param family
341 The font family: a generic portable way of referring to fonts without specifying a
342 facename. This parameter must be one of the ::wxFontFamily enumeration values.
343 If the @a faceName argument is provided, then it overrides the font family.
344 @param style
345 One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
346 @param weight
347 Font weight, sometimes also referred to as font boldness.
348 One of the ::wxFontWeight enumeration values.
349 @param underline
350 The value can be @true or @false.
351 At present this has an effect on Windows and Motif 2.x only.
352 @param faceName
353 An optional string specifying the face name to be used.
354 If it is an empty string, a default face name will be chosen based on the family.
355 @param encoding
356 An encoding which may be one of the enumeration values of ::wxFontEncoding.
357 Briefly these can be summed up as:
358 <TABLE>
359 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
360 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
361 Default application encoding: this is the encoding set by calls to
362 SetDefaultEncoding() and which may be set to, say, KOI8 to create all
363 fonts by default with KOI8 encoding. Initially, the default application
364 encoding is the same as default system encoding.</TD></TR>
365 <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
366 <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
367 <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
368 </TABLE>
369 If the specified encoding isn't available, no font is created
370 (see also @ref overview_fontencoding).
371
372 @remarks If the desired font does not exist, the closest match will be
373 chosen. Under Windows, only scalable TrueType fonts are used.
374 */
375 wxFont(const wxSize& pixelSize, wxFontFamily family,
376 wxFontStyle style, wxFontWeight weight,
377 bool underline = false,
378 const wxString& faceName = wxEmptyString,
379 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
380
381 /**
382 Constructor from font description string.
383
384 This constructor uses SetNativeFontInfo() to initialize the font.
385 If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
386 will return @false.
387 */
388 wxFont(const wxString& fontdesc);
389
390 /**
391 Destructor.
392
393 See @ref overview_refcount_destruct "reference-counted object destruction"
394 for more info.
395
396 @remarks Although all remaining fonts are deleted when the application
397 exits, the application should try to clean up all fonts
398 itself. This is because wxWidgets cannot know if a
399 pointer to the font object is stored in an application
400 data structure, and there is a risk of double deletion.
401 */
402 virtual ~wxFont();
403
404 /**
405 Returns the current application's default encoding.
406
407 @see @ref overview_fontencoding, SetDefaultEncoding()
408 */
409 static wxFontEncoding GetDefaultEncoding();
410
411 /**
412 Returns the encoding of this font.
413
414 Note that under wxGTK the returned value is always @c wxFONTENCODING_UTF8.
415
416 @see SetEncoding()
417 */
418 virtual wxFontEncoding GetEncoding() const;
419
420 /**
421 Returns the face name associated with the font, or the empty string if
422 there is no face information.
423
424 @see SetFaceName()
425 */
426 virtual wxString GetFaceName() const;
427
428 /**
429 Gets the font family.
430 As described in ::wxFontFamily docs the returned value acts as a rough,
431 basic classification of the main font properties (look, spacing).
432
433 If the current font face name is not recognized by wxFont or by the
434 underlying system, @c wxFONTFAMILY_UNKNOWN is returned.
435
436 @see SetFamily()
437 */
438 virtual wxFontFamily GetFamily() const;
439
440 /**
441 Returns the platform-dependent string completely describing this font.
442 Returned string is always non-empty.
443
444 Note that the returned string is not meant to be shown or edited by the user: a
445 typical use of this function is for serializing in string-form a wxFont object.
446
447 @see SetNativeFontInfo(), GetNativeFontInfoUserDesc()
448 */
449 wxString GetNativeFontInfoDesc() const;
450
451 /**
452 Returns a user-friendly string for this font object.
453 Returned string is always non-empty.
454
455 The string does not encode all wxFont infos under all platforms;
456 e.g. under wxMSW the font family is not present in the returned string.
457
458 Some examples of the formats of returned strings (which are platform-dependent)
459 are in SetNativeFontInfoUserDesc().
460
461 @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()
462 */
463 wxString GetNativeFontInfoUserDesc() const;
464
465 /**
466 Gets the point size.
467
468 @see SetPointSize()
469 */
470 virtual int GetPointSize() const;
471
472 /**
473 Gets the pixel size.
474
475 Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
476 a wxSize object with a null width value, you'll get a null width in
477 the returned object.
478
479 @see SetPixelSize()
480 */
481 virtual wxSize GetPixelSize() const;
482
483 /**
484 Gets the font style. See ::wxFontStyle for a list of valid styles.
485
486 @see SetStyle()
487 */
488 virtual wxFontStyle GetStyle() const;
489
490 /**
491 Returns @true if the font is underlined, @false otherwise.
492
493 @see SetUnderlined()
494 */
495 virtual bool GetUnderlined() const;
496
497 /**
498 Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
499
500 @see SetWeight()
501 */
502 virtual wxFontWeight GetWeight() const;
503
504 /**
505 Returns @true if the font is a fixed width (or monospaced) font,
506 @false if it is a proportional one or font is invalid.
507
508 Note that this function under some platforms is different than just testing
509 for the font family being equal to @c wxFONTFAMILY_TELETYPE because native
510 platform-specific functions are used for the check (resulting in a more
511 accurate return value).
512 */
513 virtual bool IsFixedWidth() const;
514
515 /**
516 Returns @true if this object is a valid font, @false otherwise.
517 */
518 virtual bool IsOk() const;
519
520 //@{
521 /**
522 This function takes the same parameters as the relative
523 @ref wxFont::wxFont "wxFont constructor" and returns a new font
524 object allocated on the heap.
525 */
526 static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
527 wxFontWeight weight,
528 bool underline = false,
529 const wxString& faceName = wxEmptyString,
530 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
531 static wxFont* New(int pointSize, wxFontFamily family,
532 int flags = wxFONTFLAG_DEFAULT,
533 const wxString& faceName = wxEmptyString,
534 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
535 static wxFont* New(const wxSize& pixelSize,
536 wxFontFamily family,
537 wxFontStyle style,
538 wxFontWeight weight,
539 bool underline = false,
540 const wxString& faceName = wxEmptyString,
541 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
542 static wxFont* New(const wxSize& pixelSize,
543 wxFontFamily family,
544 int flags = wxFONTFLAG_DEFAULT,
545 const wxString& faceName = wxEmptyString,
546 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
547 //@}
548
549 /**
550 Sets the default font encoding.
551
552 @see @ref overview_fontencoding, GetDefaultEncoding()
553 */
554 static void SetDefaultEncoding(wxFontEncoding encoding);
555
556 /**
557 Sets the encoding for this font.
558
559 Note that under wxGTK this function has no effect (because the underlying
560 Pango library always uses @c wxFONTENCODING_UTF8).
561
562 @see GetEncoding()
563 */
564 virtual void SetEncoding(wxFontEncoding encoding);
565
566 /**
567 Sets the facename for the font.
568 Returns @true if the given face name exists; @false otherwise.
569
570 @param faceName
571 A valid facename, which should be on the end-user's system.
572
573 @remarks To avoid portability problems, don't rely on a specific face,
574 but specify the font family instead or as well (see ::wxFontFamily).
575 A suitable font will be found on the end-user's system.
576 If both the family and the facename are specified, wxWidgets will
577 first search for the specific face, and then for a font belonging
578 to the same family.
579
580 @see GetFaceName(), SetFamily()
581 */
582 virtual bool SetFaceName(const wxString& faceName);
583
584 /**
585 Sets the font family.
586
587 @param family
588 One of the ::wxFontFamily values.
589
590 @see GetFamily(), SetFaceName()
591 */
592 virtual void SetFamily(wxFontFamily family);
593
594 /**
595 Creates the font corresponding to the given native font description string
596 which must have been previously returned by GetNativeFontInfoDesc().
597
598 If the string is invalid, font is unchanged.
599 This function is typically used for de-serializing a wxFont object
600 previously saved in a string-form.
601
602 @return @true if the creation was successful.
603
604 @see SetNativeFontInfoUserDesc()
605 */
606 bool SetNativeFontInfo(const wxString& info);
607
608 /**
609 Creates the font corresponding to the given native font description string and
610 returns @true if the creation was successful.
611
612 Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly.
613 Examples of accepted string formats are:
614
615 @beginTable
616 @hdr3col{platform, generic syntax, example}
617 @row3col{wxGTK2, <tt>[FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
618 @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
619 @endTable
620
621 @todo add an example for wxMac
622
623 For more detailed information about the allowed syntaxes you can look at the
624 documentation of the native API used for font-rendering
625 (e.g. @c pango_font_description_from_string on GTK).
626
627 Note that unlike SetNativeFontInfo(), this function doesn't always restore all
628 attributes of the wxFont object under all platforms; e.g. on wxMSW the font family
629 is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW).
630 If you want to serialize/deserialize a font in string form, you should use
631 GetNativeFontInfoDesc() and SetNativeFontInfo() instead.
632
633 @see SetNativeFontInfo()
634 */
635 bool SetNativeFontInfoUserDesc(const wxString& info);
636
637 /**
638 Sets the point size.
639
640 The <em>point size</em> is defined as 1/72 of the anglo-Saxon inch
641 (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
642
643 @param pointSize
644 Size in points.
645
646 @see GetPointSize()
647 */
648 virtual void SetPointSize(int pointSize);
649
650 /**
651 Sets the pixel size.
652
653 The height parameter of @a pixelSize must be positive while the width
654 parameter may also be zero (to indicate that you're not interested in the
655 width of the characters: a suitable width will be chosen for best rendering).
656
657 This feature (specifying the font pixel size) is directly supported only
658 under wxMSW and wxGTK currently; under other platforms a font with the
659 closest size to the given one is found using binary search (this maybe slower).
660
661 @see GetPixelSize()
662 */
663 virtual void SetPixelSize(const wxSize& pixelSize);
664
665 /**
666 Sets the font style.
667
668 @param style
669 One of the ::wxFontStyle enumeration values.
670
671 @see GetStyle()
672 */
673 virtual void SetStyle(wxFontStyle style);
674
675 /**
676 Sets underlining.
677
678 @param underlined
679 @true to underline, @false otherwise.
680
681 @see GetUnderlined()
682 */
683 virtual void SetUnderlined(bool underlined);
684
685 /**
686 Sets the font weight.
687
688 @param weight
689 One of the ::wxFontWeight values.
690
691 @see GetWeight()
692 */
693 virtual void SetWeight(wxFontWeight weight);
694
695 /**
696 Inequality operator.
697
698 See @ref overview_refcount_equality "reference-counted object comparison" for
699 more info.
700 */
701 bool operator!=(const wxFont& font) const;
702
703 /**
704 Equality operator.
705
706 See @ref overview_refcount_equality "reference-counted object comparison" for
707 more info.
708 */
709 bool operator==(const wxFont& font) const;
710
711 /**
712 Assignment operator, using @ref overview_refcount "reference counting".
713 */
714 wxFont& operator =(const wxFont& font);
715 };
716
717
718 /**
719 An empty wxFont.
720 */
721 wxFont wxNullFont;
722
723 /**
724 Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
725
726 @see wxSystemSettings
727 */
728 wxFont wxNORMAL_FONT;
729
730 /**
731 A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
732 ::wxNORMAL_FONT.
733 */
734 wxFont wxSMALL_FONT;
735
736 /**
737 A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
738 of the same size of ::wxNORMAL_FONT.
739 */
740 wxFont wxITALIC_FONT;
741
742 /**
743 A font identic to ::wxNORMAL_FONT except for the family used which is
744 @c wxFONTFAMILY_SWISS.
745 */
746 wxFont wxSWISS_FONT;
747
748
749 /**
750 @class wxFontList
751
752 A font list is a list containing all fonts which have been created.
753 There is only one instance of this class: ::wxTheFontList.
754
755 Use this object to search for a previously created font of the desired type
756 and create it if not already found.
757
758 In some windowing systems, the font may be a scarce resource, so it is best to
759 reuse old resources if possible. When an application finishes, all fonts will
760 be deleted and their resources freed, eliminating the possibility of 'memory
761 leaks'.
762
763 @library{wxcore}
764 @category{gdi}
765
766 @see wxFont
767 */
768 class wxFontList : public wxList
769 {
770 public:
771 /**
772 Constructor. The application should not construct its own font list:
773 use the object pointer ::wxTheFontList.
774 */
775 wxFontList();
776
777 /**
778 Finds a font of the given specification, or creates one and adds it to the
779 list. See the @ref wxFont "wxFont constructor" for details of the arguments.
780 */
781 wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
782 wxFontWeight weight, bool underline = false,
783 const wxString& facename = wxEmptyString,
784 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
785 };
786
787
788 /**
789 The global wxFontList instance.
790 */
791 wxFontList* wxTheFontList;
792
793
794 // ============================================================================
795 // Global functions/macros
796 // ============================================================================
797
798 /** @addtogroup group_funcmacro_misc */
799 //@{
800
801 /**
802 Converts string to a wxFont best represented by the given string. Returns
803 @true on success.
804
805 @see wxToString(const wxFont&)
806
807 @header{wx/font.h}
808 */
809 bool wxFromString(const wxString& string, wxFont* font);
810
811 /**
812 Converts the given wxFont into a string.
813
814 @see wxFromString(const wxString&, wxFont*)
815
816 @header{wx/font.h}
817 */
818 wxString wxToString(const wxFont& font);
819
820 //@}
821