]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/font.h
Use explicit wxPGPropertyFlags enum type with wxPGProperty::SetFlag() and similar...
[wxWidgets.git] / interface / wx / font.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: font.h
e54c96f1 3// Purpose: interface of wxFont
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
0b70c946
FM
9
10/**
6aea1e4a
FM
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.
0b70c946
FM
18*/
19enum wxFontFamily
20{
21 wxFONTFAMILY_DEFAULT = wxDEFAULT, //!< Chooses a default font.
f76c0758 22
0b70c946
FM
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.
f76c0758 27
6aea1e4a
FM
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,
f76c0758 31
6aea1e4a 32 /// A teletype (i.e. monospaced) font.
f76c0758
VZ
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,
6aea1e4a
FM
35 /// functional font style.
36 /// See also wxFont::IsFixedWidth() for an easy way to test for monospace property.
37 wxFONTFAMILY_TELETYPE = wxTELETYPE,
f76c0758 38
6aea1e4a
FM
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
0b70c946
FM
44};
45
46/**
47 Font styles.
48*/
49enum wxFontStyle
50{
071de7a0 51 /// The font is drawn without slant.
0b70c946 52 wxFONTSTYLE_NORMAL = wxNORMAL,
071de7a0
FM
53
54 /// The font is slanted in an italic style.
0b70c946 55 wxFONTSTYLE_ITALIC = wxITALIC,
f76c0758
VZ
56
57 /// The font is slanted, but in a roman style.
071de7a0 58 /// Note that under wxMSW this style is the same as @c wxFONTSTYLE_ITALIC.
0b70c946 59 wxFONTSTYLE_SLANT = wxSLANT,
071de7a0 60
0b70c946
FM
61 wxFONTSTYLE_MAX
62};
63
64/**
65 Font weights.
66*/
67enum 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*/
78enum 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.
f76c0758 114
7ce58684 115 See wxFont::SetEncoding().
0b70c946
FM
116*/
117enum 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
9a6fda22
FM
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)
0b70c946
FM
143 wxFONTENCODING_ISO8859_MAX,
144
145 // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
9a6fda22
FM
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
0b70c946
FM
150
151 // what would we do without Microsoft? They have their own encodings
152 // for DOS
9a6fda22
FM
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
0b70c946 158 // and for Windows
9a6fda22
FM
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)
0b70c946
FM
172 wxFONTENCODING_CP12_MAX,
173
9a6fda22
FM
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
0b70c946
FM
180 wxFONTENCODING_UTF32LE, // UTF-32 Little Endian Unicode encoding
181
9a6fda22 182 wxFONTENCODING_MACROMAN, //!< the standard mac encodings
0b70c946
FM
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)
9a6fda22 225 wxFONTENCODING_ISO2022_JP, //!< ISO-2022-JP JIS encoding
0b70c946 226
9a6fda22 227 wxFONTENCODING_MAX, //!< highest enumerated encoding value
0b70c946
FM
228
229 wxFONTENCODING_MACMIN = wxFONTENCODING_MACROMAN ,
230 wxFONTENCODING_MACMAX = wxFONTENCODING_MACKEYBOARD ,
231
232 // aliases for endian-dependent UTF encodings
9a6fda22
FM
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,
0b70c946
FM
239
240 // alternative names for Far Eastern encodings
241 // Chinese
9a6fda22
FM
242 wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese
243 wxFONTENCODING_BIG5 = wxFONTENCODING_CP950, //!< Traditional Chinese
0b70c946
FM
244
245 // Japanese (see http://zsigri.tripod.com/fontboard/cjk/jis.html)
9a6fda22 246 wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932 //!< Shift JIS
0b70c946
FM
247};
248
249
250
23324ae1
FM
251/**
252 @class wxFont
7c913512 253
0b70c946
FM
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.
7c913512 257
0b70c946 258 This class uses @ref overview_refcount "reference counting and copy-on-write"
23324ae1
FM
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.
7c913512 264
23324ae1 265 You can retrieve the current system font settings with wxSystemSettings.
7c913512 266
23324ae1
FM
267 @library{wxcore}
268 @category{gdi}
7c913512 269
23324ae1 270 @stdobjects
65874118 271 ::wxNullFont, ::wxNORMAL_FONT, ::wxSMALL_FONT, ::wxITALIC_FONT, ::wxSWISS_FONT
7c913512 272
0b70c946
FM
273 @see @ref overview_font, wxDC::SetFont, wxDC::DrawText,
274 wxDC::GetTextExtent, wxFontDialog, wxSystemSettings
23324ae1
FM
275*/
276class wxFont : public wxGDIObject
277{
278public:
45a591fa 279 /**
0b70c946 280 Default ctor.
45a591fa
VZ
281 */
282 wxFont();
283
284 /**
0b70c946 285 Copy constructor, uses @ref overview_refcount "reference counting".
45a591fa
VZ
286 */
287 wxFont(const wxFont& font);
288
23324ae1
FM
289 /**
290 Creates a font object with the specified attributes.
3c4f71cc 291
7c913512 292 @param pointSize
b5791cc7 293 Size in points. See SetPointSize() for more info.
45a591fa 294 @param family
6aea1e4a
FM
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.
45a591fa 298 @param style
b5791cc7 299 One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
45a591fa 300 @param weight
f76c0758 301 Font weight, sometimes also referred to as font boldness.
b5791cc7 302 One of the ::wxFontWeight enumeration values.
45a591fa 303 @param underline
0b70c946
FM
304 The value can be @true or @false.
305 At present this has an effect on Windows and Motif 2.x only.
45a591fa 306 @param faceName
6aea1e4a
FM
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.
45a591fa 309 @param encoding
0b70c946
FM
310 An encoding which may be one of the enumeration values of ::wxFontEncoding.
311 Briefly these can be summed up as:
312 <TABLE>
b5791cc7
FM
313 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
314 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
8f1337ed 315 Default application encoding: this is the encoding set by calls to
f76c0758
VZ
316 SetDefaultEncoding() and which may be set to, say, KOI8 to create all
317 fonts by default with KOI8 encoding. Initially, the default application
8f1337ed 318 encoding is the same as default system encoding.</TD></TR>
b5791cc7
FM
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>
0b70c946 322 </TABLE>
45a591fa 323 If the specified encoding isn't available, no font is created
8f1337ed 324 (see also @ref overview_fontencoding).
45a591fa
VZ
325
326 @remarks If the desired font does not exist, the closest match will be
0b70c946 327 chosen. Under Windows, only scalable TrueType fonts are used.
45a591fa 328 */
882678eb 329 wxFont(int pointSize, wxFontFamily family, wxFontStyle style,
45a591fa 330 wxFontWeight weight,
11e3af6e 331 bool underline = false,
e9c3992c 332 const wxString& faceName = wxEmptyString,
45a591fa 333 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
0b70c946 334
45a591fa
VZ
335 /**
336 Creates a font object with the specified attributes.
337
7c913512 338 @param pixelSize
b5791cc7 339 Size in pixels. See SetPixelSize() for more info.
7c913512 340 @param family
6aea1e4a
FM
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.
4cc4bfaf 344 @param style
b5791cc7 345 One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
7c913512 346 @param weight
0b70c946
FM
347 Font weight, sometimes also referred to as font boldness.
348 One of the ::wxFontWeight enumeration values.
4cc4bfaf 349 @param underline
0b70c946
FM
350 The value can be @true or @false.
351 At present this has an effect on Windows and Motif 2.x only.
4cc4bfaf 352 @param faceName
6aea1e4a
FM
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.
7c913512 355 @param encoding
0b70c946
FM
356 An encoding which may be one of the enumeration values of ::wxFontEncoding.
357 Briefly these can be summed up as:
358 <TABLE>
b5791cc7
FM
359 <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
360 <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
8f1337ed 361 Default application encoding: this is the encoding set by calls to
f76c0758
VZ
362 SetDefaultEncoding() and which may be set to, say, KOI8 to create all
363 fonts by default with KOI8 encoding. Initially, the default application
8f1337ed 364 encoding is the same as default system encoding.</TD></TR>
b5791cc7
FM
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>
0b70c946 368 </TABLE>
4cc4bfaf 369 If the specified encoding isn't available, no font is created
8f1337ed 370 (see also @ref overview_fontencoding).
3c4f71cc 371
23324ae1 372 @remarks If the desired font does not exist, the closest match will be
0b70c946 373 chosen. Under Windows, only scalable TrueType fonts are used.
23324ae1 374 */
7c913512 375 wxFont(const wxSize& pixelSize, wxFontFamily family,
882678eb 376 wxFontStyle style, wxFontWeight weight,
11e3af6e 377 bool underline = false,
e9c3992c 378 const wxString& faceName = wxEmptyString,
7c913512 379 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
23324ae1 380
20cc4e19
VZ
381 /**
382 Constructor from font description string.
383
6aea1e4a
FM
384 This constructor uses SetNativeFontInfo() to initialize the font.
385 If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
20cc4e19
VZ
386 will return @false.
387 */
388 wxFont(const wxString& fontdesc);
389
23324ae1
FM
390 /**
391 Destructor.
0b70c946 392
674d80a7 393 See @ref overview_refcount_destruct "reference-counted object destruction"
0b70c946 394 for more info.
3c4f71cc 395
23324ae1 396 @remarks Although all remaining fonts are deleted when the application
4cc4bfaf
FM
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.
23324ae1 401 */
adaaa686 402 virtual ~wxFont();
23324ae1 403
f76c0758 404
23324ae1 405 /**
060c4f90 406 @name Getters
23324ae1 407 */
060c4f90 408 //@{
f76c0758 409
7ce58684
FM
410 /**
411 Returns the encoding of this font.
f76c0758 412
7ce58684 413 Note that under wxGTK the returned value is always @c wxFONTENCODING_UTF8.
f76c0758 414
7ce58684
FM
415 @see SetEncoding()
416 */
417 virtual wxFontEncoding GetEncoding() const;
f76c0758 418
23324ae1 419 /**
6aea1e4a
FM
420 Returns the face name associated with the font, or the empty string if
421 there is no face information.
3c4f71cc 422
4cc4bfaf 423 @see SetFaceName()
23324ae1 424 */
adaaa686 425 virtual wxString GetFaceName() const;
23324ae1
FM
426
427 /**
6aea1e4a
FM
428 Gets the font family.
429 As described in ::wxFontFamily docs the returned value acts as a rough,
430 basic classification of the main font properties (look, spacing).
f76c0758 431
6aea1e4a
FM
432 If the current font face name is not recognized by wxFont or by the
433 underlying system, @c wxFONTFAMILY_UNKNOWN is returned.
f76c0758 434
f7008bad 435 Note that currently this function is rather unreliable (@c wxFONTFAMILY_UNKNOWN
f76c0758 436 is returned in too many cases) and not particularly useful.
060c4f90 437 Font families mostly make sense only for font creation; see SetFamily().
3c4f71cc 438
4cc4bfaf 439 @see SetFamily()
23324ae1 440 */
26818748 441 virtual wxFontFamily GetFamily() const;
23324ae1
FM
442
443 /**
444 Returns the platform-dependent string completely describing this font.
64932e41
VZ
445
446 Returned string is always non-empty unless the font is invalid (in
447 which case an assert is triggered).
0b70c946 448
23324ae1 449 Note that the returned string is not meant to be shown or edited by the user: a
0b70c946 450 typical use of this function is for serializing in string-form a wxFont object.
3c4f71cc 451
a912ea26 452 @see SetNativeFontInfo(), GetNativeFontInfoUserDesc()
23324ae1 453 */
328f5751 454 wxString GetNativeFontInfoDesc() const;
23324ae1
FM
455
456 /**
0b70c946 457 Returns a user-friendly string for this font object.
64932e41
VZ
458
459 Returned string is always non-empty unless the font is invalid (in
460 which case an assert is triggered).
f76c0758 461
a912ea26
FM
462 The string does not encode all wxFont infos under all platforms;
463 e.g. under wxMSW the font family is not present in the returned string.
0b70c946 464
23324ae1
FM
465 Some examples of the formats of returned strings (which are platform-dependent)
466 are in SetNativeFontInfoUserDesc().
3c4f71cc 467
a912ea26 468 @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()
23324ae1 469 */
adaaa686 470 wxString GetNativeFontInfoUserDesc() const;
23324ae1
FM
471
472 /**
473 Gets the point size.
3c4f71cc 474
4cc4bfaf 475 @see SetPointSize()
23324ae1 476 */
adaaa686 477 virtual int GetPointSize() const;
23324ae1
FM
478
479 /**
b5791cc7 480 Gets the pixel size.
f76c0758 481
b5791cc7
FM
482 Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
483 a wxSize object with a null width value, you'll get a null width in
484 the returned object.
485
486 @see SetPixelSize()
487 */
488 virtual wxSize GetPixelSize() const;
f76c0758 489
b5791cc7
FM
490 /**
491 Gets the font style. See ::wxFontStyle for a list of valid styles.
3c4f71cc 492
4cc4bfaf 493 @see SetStyle()
23324ae1 494 */
26818748 495 virtual wxFontStyle GetStyle() const;
23324ae1
FM
496
497 /**
498 Returns @true if the font is underlined, @false otherwise.
3c4f71cc 499
4cc4bfaf 500 @see SetUnderlined()
23324ae1 501 */
adaaa686 502 virtual bool GetUnderlined() const;
23324ae1
FM
503
504 /**
b5791cc7 505 Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
3c4f71cc 506
4cc4bfaf 507 @see SetWeight()
23324ae1 508 */
26818748 509 virtual wxFontWeight GetWeight() const;
23324ae1
FM
510
511 /**
512 Returns @true if the font is a fixed width (or monospaced) font,
513 @false if it is a proportional one or font is invalid.
f76c0758 514
6aea1e4a
FM
515 Note that this function under some platforms is different than just testing
516 for the font family being equal to @c wxFONTFAMILY_TELETYPE because native
517 platform-specific functions are used for the check (resulting in a more
518 accurate return value).
23324ae1 519 */
adaaa686 520 virtual bool IsFixedWidth() const;
23324ae1
FM
521
522 /**
523 Returns @true if this object is a valid font, @false otherwise.
524 */
0004982c 525 virtual bool IsOk() const;
f76c0758
VZ
526
527 //@}
528
529
530 /**
531 @name Similar fonts creation
532
6e7d2550
VZ
533 The functions in this section either modify the font in place or create
534 a new font similar to the given one but with its weight, style or size
535 changed.
f76c0758
VZ
536 */
537 //@{
538
539 /**
540 Return a bold version of this font.
6e7d2550
VZ
541
542 @see MakeBold()
543
544 @since 2.9.1
f76c0758 545 */
6e7d2550 546 wxFont Bold() const;
f76c0758
VZ
547
548 /**
549 Return an italic version of this font.
6e7d2550
VZ
550
551 @see MakeItalic()
552
553 @since 2.9.1
f76c0758 554 */
6e7d2550 555 wxFont Italic() const;
f76c0758
VZ
556
557 /**
558 Return a larger version of this font.
559
560 The font size is multiplied by CSS specification inspired factor of @c
561 1.2.
562
6e7d2550
VZ
563 @see Larger(), MakeSmaller(), Scale()
564
565 @since 2.9.1
566 */
567 wxFont Larger() const;
568
569 /**
570 Changes this font to be bold.
571
572 @see Bold()
573
574 @since 2.9.1
575 */
576 wxFont& MakeBold();
577
578 /**
579 Changes this font to be italic.
580
581 @see Italic()
582
583 @since 2.9.1
f76c0758 584 */
6e7d2550
VZ
585 wxFont& MakeItalic();
586
587 /**
588 Changes this font to be larger.
589
590 The font size is multiplied by CSS specification inspired factor of @c
591 1.2.
592
593 @see Larger(), MakeSmaller(), Scale()
594
595 @since 2.9.1
596 */
597 wxFont& MakeLarger();
f76c0758
VZ
598
599 /**
600 Return a smaller version of this font.
601
602 The font size is divided by CSS specification inspired factor of @c
603 1.2.
604
6e7d2550
VZ
605 @see MakeLarger(), Scale(), Smaller()
606
607 @since 2.9.1
f76c0758 608 */
6e7d2550
VZ
609 wxFont& MakeSmaller();
610
611 /**
612 Changes the size of this font.
613
614 The font size is multiplied by the given factor (which may be less than
615 1 to create a smaller version of the font).
616
617 @see Scaled(), MakeLarger(), MakeSmaller()
618
619 @since 2.9.1
620 */
621 wxFont& Scale(float x);
f76c0758
VZ
622
623 /**
624 Return a scaled version of this font.
625
626 The font size is multiplied by the given factor (which may be less than
627 1 to create a smaller version of the font).
6e7d2550
VZ
628
629 @see Scale(), Larger(), Smaller()
630
631 @since 2.9.1
632 */
633 wxFont Scaled(float x) const;
634
635 /**
636 Return a smaller version of this font.
637
638 The font size is divided by CSS specification inspired factor of @c
639 1.2.
640
641 @see Larger(), MakeSmaller(), Scaled()
642
643 @since 2.9.1
f76c0758 644 */
6e7d2550 645 wxFont Smaller() const;
f76c0758 646
23324ae1 647 //@}
f76c0758 648
23324ae1 649 /**
060c4f90 650 @name Setters
f76c0758 651
060c4f90
FM
652 These functions internally recreate the native font object with the new
653 specified property.
23324ae1 654 */
060c4f90
FM
655 //@{
656
7ce58684
FM
657 /**
658 Sets the encoding for this font.
f76c0758 659
7ce58684
FM
660 Note that under wxGTK this function has no effect (because the underlying
661 Pango library always uses @c wxFONTENCODING_UTF8).
f76c0758 662
7ce58684
FM
663 @see GetEncoding()
664 */
665 virtual void SetEncoding(wxFontEncoding encoding);
23324ae1
FM
666
667 /**
668 Sets the facename for the font.
3c4f71cc 669
7c913512 670 @param faceName
4cc4bfaf 671 A valid facename, which should be on the end-user's system.
3c4f71cc 672
23324ae1 673 @remarks To avoid portability problems, don't rely on a specific face,
f7008bad
FM
674 but specify the font family instead (see ::wxFontFamily and SetFamily()).
675
676 @return @true if the given face name exists; if the face name doesn't exist
f76c0758 677 in the user's system then the font is invalidated (so that IsOk() will
f7008bad 678 return @false) and @false is returned.
3c4f71cc 679
4cc4bfaf 680 @see GetFaceName(), SetFamily()
23324ae1 681 */
adaaa686 682 virtual bool SetFaceName(const wxString& faceName);
23324ae1
FM
683
684 /**
685 Sets the font family.
f76c0758 686
060c4f90
FM
687 As described in ::wxFontFamily docs the given @a family value acts as a rough,
688 basic indication of the main font properties (look, spacing).
689
690 Note that changing the font family results in changing the font face name.
3c4f71cc 691
7c913512 692 @param family
0b70c946 693 One of the ::wxFontFamily values.
3c4f71cc 694
4cc4bfaf 695 @see GetFamily(), SetFaceName()
23324ae1 696 */
a44f3b5a 697 virtual void SetFamily(wxFontFamily family);
23324ae1
FM
698
699 /**
0b70c946
FM
700 Creates the font corresponding to the given native font description string
701 which must have been previously returned by GetNativeFontInfoDesc().
702
703 If the string is invalid, font is unchanged.
704 This function is typically used for de-serializing a wxFont object
705 previously saved in a string-form.
706
707 @return @true if the creation was successful.
3c4f71cc 708
4cc4bfaf 709 @see SetNativeFontInfoUserDesc()
23324ae1
FM
710 */
711 bool SetNativeFontInfo(const wxString& info);
712
713 /**
714 Creates the font corresponding to the given native font description string and
0b70c946 715 returns @true if the creation was successful.
3c4f71cc 716
0b70c946
FM
717 Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly.
718 Examples of accepted string formats are:
3c4f71cc 719
0b70c946
FM
720 @beginTable
721 @hdr3col{platform, generic syntax, example}
b5791cc7
FM
722 @row3col{wxGTK2, <tt>[FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
723 @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}
0b70c946 724 @endTable
3c4f71cc 725
0b70c946 726 @todo add an example for wxMac
3c4f71cc 727
23324ae1 728 For more detailed information about the allowed syntaxes you can look at the
0b70c946
FM
729 documentation of the native API used for font-rendering
730 (e.g. @c pango_font_description_from_string on GTK).
f76c0758 731
a912ea26
FM
732 Note that unlike SetNativeFontInfo(), this function doesn't always restore all
733 attributes of the wxFont object under all platforms; e.g. on wxMSW the font family
734 is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW).
735 If you want to serialize/deserialize a font in string form, you should use
736 GetNativeFontInfoDesc() and SetNativeFontInfo() instead.
3c4f71cc 737
4cc4bfaf 738 @see SetNativeFontInfo()
23324ae1
FM
739 */
740 bool SetNativeFontInfoUserDesc(const wxString& info);
741
742 /**
743 Sets the point size.
f76c0758
VZ
744
745 The <em>point size</em> is defined as 1/72 of the anglo-Saxon inch
746 (25.4 mm): it is approximately 0.0139 inch or 352.8 um.
3c4f71cc 747
7c913512 748 @param pointSize
4cc4bfaf 749 Size in points.
3c4f71cc 750
4cc4bfaf 751 @see GetPointSize()
23324ae1 752 */
adaaa686 753 virtual void SetPointSize(int pointSize);
23324ae1 754
b5791cc7
FM
755 /**
756 Sets the pixel size.
f76c0758 757
b5791cc7
FM
758 The height parameter of @a pixelSize must be positive while the width
759 parameter may also be zero (to indicate that you're not interested in the
760 width of the characters: a suitable width will be chosen for best rendering).
f76c0758
VZ
761
762 This feature (specifying the font pixel size) is directly supported only
763 under wxMSW and wxGTK currently; under other platforms a font with the
b5791cc7
FM
764 closest size to the given one is found using binary search (this maybe slower).
765
766 @see GetPixelSize()
767 */
768 virtual void SetPixelSize(const wxSize& pixelSize);
f76c0758 769
23324ae1
FM
770 /**
771 Sets the font style.
3c4f71cc 772
7c913512 773 @param style
0b70c946 774 One of the ::wxFontStyle enumeration values.
3c4f71cc 775
4cc4bfaf 776 @see GetStyle()
23324ae1 777 */
a44f3b5a 778 virtual void SetStyle(wxFontStyle style);
23324ae1
FM
779
780 /**
781 Sets underlining.
3c4f71cc 782
45a591fa 783 @param underlined
4cc4bfaf 784 @true to underline, @false otherwise.
3c4f71cc 785
4cc4bfaf 786 @see GetUnderlined()
23324ae1 787 */
26818748 788 virtual void SetUnderlined(bool underlined);
23324ae1
FM
789
790 /**
791 Sets the font weight.
3c4f71cc 792
7c913512 793 @param weight
0b70c946 794 One of the ::wxFontWeight values.
3c4f71cc 795
4cc4bfaf 796 @see GetWeight()
23324ae1 797 */
a44f3b5a 798 virtual void SetWeight(wxFontWeight weight);
f76c0758 799
060c4f90
FM
800 //@}
801
23324ae1
FM
802
803 /**
804 Inequality operator.
0b70c946 805
674d80a7 806 See @ref overview_refcount_equality "reference-counted object comparison" for
23324ae1
FM
807 more info.
808 */
fadc2df6 809 bool operator!=(const wxFont& font) const;
23324ae1 810
23324ae1
FM
811 /**
812 Equality operator.
0b70c946 813
674d80a7 814 See @ref overview_refcount_equality "reference-counted object comparison" for
23324ae1
FM
815 more info.
816 */
fadc2df6 817 bool operator==(const wxFont& font) const;
0b70c946
FM
818
819 /**
820 Assignment operator, using @ref overview_refcount "reference counting".
821 */
822 wxFont& operator =(const wxFont& font);
f76c0758
VZ
823
824
060c4f90
FM
825 // statics
826
827 /**
828 Returns the current application's default encoding.
829
830 @see @ref overview_fontencoding, SetDefaultEncoding()
831 */
832 static wxFontEncoding GetDefaultEncoding();
833
834 /**
835 Sets the default font encoding.
836
837 @see @ref overview_fontencoding, GetDefaultEncoding()
838 */
839 static void SetDefaultEncoding(wxFontEncoding encoding);
f76c0758 840
060c4f90
FM
841 //@{
842 /**
843 This function takes the same parameters as the relative
844 @ref wxFont::wxFont "wxFont constructor" and returns a new font
845 object allocated on the heap.
846 */
847 static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
848 wxFontWeight weight,
849 bool underline = false,
850 const wxString& faceName = wxEmptyString,
851 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
852 static wxFont* New(int pointSize, wxFontFamily family,
853 int flags = wxFONTFLAG_DEFAULT,
854 const wxString& faceName = wxEmptyString,
855 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
856 static wxFont* New(const wxSize& pixelSize,
857 wxFontFamily family,
858 wxFontStyle style,
859 wxFontWeight weight,
860 bool underline = false,
861 const wxString& faceName = wxEmptyString,
862 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
863 static wxFont* New(const wxSize& pixelSize,
864 wxFontFamily family,
865 int flags = wxFONTFLAG_DEFAULT,
866 const wxString& faceName = wxEmptyString,
867 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
868 //@}
23324ae1 869};
e54c96f1
FM
870
871
872/**
65874118 873 An empty wxFont.
e54c96f1 874*/
7fa7088e 875wxFont wxNullFont;
e54c96f1
FM
876
877/**
0b70c946 878 Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
f76c0758 879
b5791cc7 880 @see wxSystemSettings
e54c96f1 881*/
7fa7088e 882wxFont wxNORMAL_FONT;
e54c96f1
FM
883
884/**
b5791cc7 885 A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than
0b70c946 886 ::wxNORMAL_FONT.
e54c96f1 887*/
7fa7088e 888wxFont wxSMALL_FONT;
e54c96f1
FM
889
890/**
b5791cc7 891 A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and
0b70c946 892 of the same size of ::wxNORMAL_FONT.
e54c96f1 893*/
7fa7088e 894wxFont wxITALIC_FONT;
e54c96f1
FM
895
896/**
0b70c946 897 A font identic to ::wxNORMAL_FONT except for the family used which is
b5791cc7 898 @c wxFONTFAMILY_SWISS.
e54c96f1 899*/
7fa7088e
BP
900wxFont wxSWISS_FONT;
901
902
65874118
FM
903/**
904 @class wxFontList
65874118 905
0b70c946
FM
906 A font list is a list containing all fonts which have been created.
907 There is only one instance of this class: ::wxTheFontList.
908
909 Use this object to search for a previously created font of the desired type
910 and create it if not already found.
911
65874118
FM
912 In some windowing systems, the font may be a scarce resource, so it is best to
913 reuse old resources if possible. When an application finishes, all fonts will
0b70c946 914 be deleted and their resources freed, eliminating the possibility of 'memory
65874118
FM
915 leaks'.
916
917 @library{wxcore}
918 @category{gdi}
919
920 @see wxFont
921*/
922class wxFontList : public wxList
923{
924public:
925 /**
926 Constructor. The application should not construct its own font list:
0b70c946 927 use the object pointer ::wxTheFontList.
65874118
FM
928 */
929 wxFontList();
930
931 /**
932 Finds a font of the given specification, or creates one and adds it to the
0b70c946 933 list. See the @ref wxFont "wxFont constructor" for details of the arguments.
65874118 934 */
a44f3b5a
FM
935 wxFont* FindOrCreateFont(int point_size, wxFontFamily family, wxFontStyle style,
936 wxFontWeight weight, bool underline = false,
937 const wxString& facename = wxEmptyString,
65874118
FM
938 wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
939};
940
941
0b70c946
FM
942/**
943 The global wxFontList instance.
944*/
945wxFontList* wxTheFontList;
946
7fa7088e
BP
947
948// ============================================================================
949// Global functions/macros
950// ============================================================================
951
b21126db 952/** @addtogroup group_funcmacro_misc */
7fa7088e 953//@{
e54c96f1
FM
954
955/**
7fa7088e
BP
956 Converts string to a wxFont best represented by the given string. Returns
957 @true on success.
958
959 @see wxToString(const wxFont&)
960
961 @header{wx/font.h}
e54c96f1 962*/
7fa7088e 963bool wxFromString(const wxString& string, wxFont* font);
e54c96f1
FM
964
965/**
7fa7088e
BP
966 Converts the given wxFont into a string.
967
968 @see wxFromString(const wxString&, wxFont*)
969
970 @header{wx/font.h}
e54c96f1 971*/
7fa7088e 972wxString wxToString(const wxFont& font);
e54c96f1 973
7fa7088e 974//@}
e54c96f1 975