- | wxFONTENCODING_SYSTEM | Default system encoding. |
- | wxFONTENCODING_DEFAULT |
- Default application encoding: this
- is the encoding set by calls to
- SetDefaultEncoding and which may be set to,
- say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the
- default application encoding is the same as default system encoding. |
- | wxFONTENCODING_ISO8859_1...15 | ISO8859 encodings. |
- | wxFONTENCODING_KOI8 | The standard Russian encoding for Internet. |
- | wxFONTENCODING_CP1250...1252 | Windows encodings similar to ISO8859 (but not identical). |
+ | @c wxFONTENCODING_SYSTEM | Default system encoding. |
+ | @c wxFONTENCODING_DEFAULT |
+ Default application encoding: this is the encoding set by calls to
+ SetDefaultEncoding() and which may be set to, say, KOI8 to create all
+ fonts by default with KOI8 encoding. Initially, the default application
+ encoding is the same as default system encoding. |
+ | @c wxFONTENCODING_ISO8859_1...15 | ISO8859 encodings. |
+ | @c wxFONTENCODING_KOI8 | The standard Russian encoding for Internet. |
+ | @c wxFONTENCODING_CP1250...1252 | Windows encodings similar to ISO8859 (but not identical). |
If the specified encoding isn't available, no font is created
- (see also font encoding overview).
+ (see also @ref overview_fontencoding).
@remarks If the desired font does not exist, the closest match will be
chosen. Under Windows, only scalable TrueType fonts are used.
*/
- wxFont(int pointSize, wxFontFamily family, int style,
+ wxFont(int pointSize, wxFontFamily family, wxFontStyle style,
wxFontWeight weight,
bool underline = false,
- const wxString& faceName = "",
+ const wxString& faceName = wxEmptyString,
wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
/**
Creates a font object with the specified attributes.
@param pixelSize
- Size in pixels: this is directly supported only under MSW currently
- where this constructor can be used directly, under other platforms a
- font with the closest size to the given one is found using binary search
- and the static New method must be used.
+ Size in pixels. See SetPixelSize() for more info.
@param family
- Font family, a generic way of referring to fonts without specifying actual
- facename. One of ::wxFontFamily enumeration values.
+ The font family: a generic portable way of referring to fonts without specifying a
+ facename. This parameter must be one of the ::wxFontFamily enumeration values.
+ If the @a faceName argument is provided, then it overrides the font family.
@param style
- One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC.
+ One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
@param weight
Font weight, sometimes also referred to as font boldness.
One of the ::wxFontWeight enumeration values.
@@ -336,35 +347,42 @@ public:
The value can be @true or @false.
At present this has an effect on Windows and Motif 2.x only.
@param faceName
- An optional string specifying the actual typeface to be used.
- If it is an empty string, a default typeface will be chosen based on the family.
+ An optional string specifying the face name to be used.
+ If it is an empty string, a default face name will be chosen based on the family.
@param encoding
An encoding which may be one of the enumeration values of ::wxFontEncoding.
Briefly these can be summed up as:
- | wxFONTENCODING_SYSTEM | Default system encoding. |
- | wxFONTENCODING_DEFAULT |
- Default application encoding: this
- is the encoding set by calls to
- SetDefaultEncoding and which may be set to,
- say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the
- default application encoding is the same as default system encoding. |
- | wxFONTENCODING_ISO8859_1...15 | ISO8859 encodings. |
- | wxFONTENCODING_KOI8 | The standard Russian encoding for Internet. |
- | wxFONTENCODING_CP1250...1252 | Windows encodings similar to ISO8859 (but not identical). |
+ | @c wxFONTENCODING_SYSTEM | Default system encoding. |
+ | @c wxFONTENCODING_DEFAULT |
+ Default application encoding: this is the encoding set by calls to
+ SetDefaultEncoding() and which may be set to, say, KOI8 to create all
+ fonts by default with KOI8 encoding. Initially, the default application
+ encoding is the same as default system encoding. |
+ | @c wxFONTENCODING_ISO8859_1...15 | ISO8859 encodings. |
+ | @c wxFONTENCODING_KOI8 | The standard Russian encoding for Internet. |
+ | @c wxFONTENCODING_CP1250...1252 | Windows encodings similar to ISO8859 (but not identical). |
If the specified encoding isn't available, no font is created
- (see also font encoding overview).
+ (see also @ref overview_fontencoding).
@remarks If the desired font does not exist, the closest match will be
chosen. Under Windows, only scalable TrueType fonts are used.
*/
wxFont(const wxSize& pixelSize, wxFontFamily family,
- int style, wxFontWeight weight,
+ wxFontStyle style, wxFontWeight weight,
bool underline = false,
- const wxString& faceName = "",
+ const wxString& faceName = wxEmptyString,
wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
- //@}
+
+ /**
+ Constructor from font description string.
+
+ This constructor uses SetNativeFontInfo() to initialize the font.
+ If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
+ will return @false.
+ */
+ wxFont(const wxString& fontdesc);
/**
Destructor.
@@ -380,24 +398,40 @@ public:
*/
virtual ~wxFont();
+
/**
- Returns the current application's default encoding.
+ @name Getters
+ */
+ //@{
- @see @ref overview_fontencoding, SetDefaultEncoding()
+ /**
+ Returns the encoding of this font.
+
+ Note that under wxGTK the returned value is always @c wxFONTENCODING_UTF8.
+
+ @see SetEncoding()
*/
- static wxFontEncoding GetDefaultEncoding();
+ virtual wxFontEncoding GetEncoding() const;
/**
- Returns the typeface name associated with the font, or the empty string if
- there is no typeface information.
+ Returns the face name associated with the font, or the empty string if
+ there is no face information.
@see SetFaceName()
*/
virtual wxString GetFaceName() const;
/**
- Gets the font family. See SetFamily() for a list of valid
- family identifiers.
+ Gets the font family.
+ As described in ::wxFontFamily docs the returned value acts as a rough,
+ basic classification of the main font properties (look, spacing).
+
+ If the current font face name is not recognized by wxFont or by the
+ underlying system, @c wxFONTFAMILY_UNKNOWN is returned.
+
+ Note that currently this function is rather unreliable (@c wxFONTFAMILY_UNKNOWN
+ is returned in too many cases) and not particularly useful.
+ Font families mostly make sense only for font creation; see SetFamily().
@see SetFamily()
*/
@@ -405,23 +439,30 @@ public:
/**
Returns the platform-dependent string completely describing this font.
- Returned string is always non-empty.
+
+ Returned string is always non-empty unless the font is invalid (in
+ which case an assert is triggered).
Note that the returned string is not meant to be shown or edited by the user: a
typical use of this function is for serializing in string-form a wxFont object.
- @see SetNativeFontInfo(),GetNativeFontInfoUserDesc()
+ @see SetNativeFontInfo(), GetNativeFontInfoUserDesc()
*/
wxString GetNativeFontInfoDesc() const;
/**
Returns a user-friendly string for this font object.
- Returned string is always non-empty.
+
+ Returned string is always non-empty unless the font is invalid (in
+ which case an assert is triggered).
+
+ The string does not encode all wxFont infos under all platforms;
+ e.g. under wxMSW the font family is not present in the returned string.
Some examples of the formats of returned strings (which are platform-dependent)
are in SetNativeFontInfoUserDesc().
- @see GetNativeFontInfoDesc()
+ @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()
*/
wxString GetNativeFontInfoUserDesc() const;
@@ -433,7 +474,18 @@ public:
virtual int GetPointSize() const;
/**
- Gets the font style. See wxFontStyle for a list of valid styles.
+ Gets the pixel size.
+
+ Note that under wxMSW if you passed to SetPixelSize() (or to the ctor)
+ a wxSize object with a null width value, you'll get a null width in
+ the returned object.
+
+ @see SetPixelSize()
+ */
+ virtual wxSize GetPixelSize() const;
+
+ /**
+ Gets the font style. See ::wxFontStyle for a list of valid styles.
@see SetStyle()
*/
@@ -447,7 +499,7 @@ public:
virtual bool GetUnderlined() const;
/**
- Gets the font weight. See wxFontWeight for a list of valid weight identifiers.
+ Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.
@see SetWeight()
*/
@@ -456,6 +508,11 @@ public:
/**
Returns @true if the font is a fixed width (or monospaced) font,
@false if it is a proportional one or font is invalid.
+
+ Note that this function under some platforms is different than just testing
+ for the font family being equal to @c wxFONTFAMILY_TELETYPE because native
+ platform-specific functions are used for the check (resulting in a more
+ accurate return value).
*/
virtual bool IsFixedWidth() const;
@@ -464,58 +521,158 @@ public:
*/
virtual bool IsOk() const;
+ //@}
+
+
+ /**
+ @name Similar fonts creation
+
+ The functions in this section either modify the font in place or create
+ a new font similar to the given one but with its weight, style or size
+ changed.
+ */
//@{
+
/**
- These functions take the same parameters as
- @ref wxFont::wxFont "wxFont constructors" and return a new font
- object allocated on the heap.
+ Returns a bold version of this font.
+
+ @see MakeBold()
+
+ @since 2.9.1
+ */
+ wxFont Bold() const;
+
+ /**
+ Returns an italic version of this font.
+
+ @see MakeItalic()
+
+ @since 2.9.1
+ */
+ wxFont Italic() const;
+
+ /**
+ Returns a larger version of this font.
+
+ The font size is multiplied by @c 1.2, the factor of @c 1.2 being
+ inspired by the W3C CSS specification.
+
+ @see MakeLarger(), Smaller(), Scaled()
+
+ @since 2.9.1
+ */
+ wxFont Larger() const;
+
+ /**
+ Returns a smaller version of this font.
+
+ The font size is divided by @c 1.2, the factor of @c 1.2 being
+ inspired by the W3C CSS specification.
+
+ @see MakeSmaller(), Larger(), Scaled()
+
+ @since 2.9.1
+ */
+ wxFont Smaller() const;
+
+ /**
+ Changes this font to be bold.
+
+ @see Bold()
+
+ @since 2.9.1
+ */
+ wxFont& MakeBold();
+
+ /**
+ Changes this font to be italic.
+
+ @see Italic()
+
+ @since 2.9.1
+ */
+ wxFont& MakeItalic();
+
+ /**
+ Changes this font to be larger.
+
+ The font size is multiplied by @c 1.2, the factor of @c 1.2 being
+ inspired by the W3C CSS specification.
+
+ @see Larger(), MakeSmaller(), Scale()
+
+ @since 2.9.1
+ */
+ wxFont& MakeLarger();
+
+ /**
+ Changes this font to be smaller.
+
+ The font size is divided by @c 1.2, the factor of @c 1.2 being
+ inspired by the W3C CSS specification.
+
+ @see Smaller(), MakeLarger(), Scale()
+
+ @since 2.9.1
+ */
+ wxFont& MakeSmaller();
+
+ /**
+ Changes the size of this font.
+
+ The font size is multiplied by the given factor (which may be less than
+ 1 to create a smaller version of the font).
+
+ @see Scaled(), MakeLarger(), MakeSmaller()
+
+ @since 2.9.1
+ */
+ wxFont& Scale(float x);
+
+ /**
+ Returns a scaled version of this font.
+
+ The font size is multiplied by the given factor (which may be less than
+ 1 to create a smaller version of the font).
+
+ @see Scale(), Larger(), Smaller()
+
+ @since 2.9.1
+ */
+ wxFont Scaled(float x) const;
- Using @c New() is currently the only way to directly create a font with
- the given size in pixels on platforms other than wxMSW.
- */
- static wxFont* New(int pointSize, wxFontFamily family, int style,
- wxFontWeight weight,
- bool underline = false,
- const wxString& faceName = "",
- wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
- static wxFont* New(int pointSize, wxFontFamily family,
- int flags = wxFONTFLAG_DEFAULT,
- const wxString& faceName = "",
- wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
- static wxFont* New(const wxSize& pixelSize,
- wxFontFamily family,
- int style,
- wxFontWeight weight,
- bool underline = false,
- const wxString& faceName = "",
- wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
- static wxFont* New(const wxSize& pixelSize,
- wxFontFamily family,
- int flags = wxFONTFLAG_DEFAULT,
- const wxString& faceName = "",
- wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
//@}
/**
- Sets the default font encoding.
+ @name Setters
- @see @ref overview_fontencoding, GetDefaultEncoding()
+ These functions internally recreate the native font object with the new
+ specified property.
*/
- static void SetDefaultEncoding(wxFontEncoding encoding);
+ //@{
+
+ /**
+ Sets the encoding for this font.
+
+ Note that under wxGTK this function has no effect (because the underlying
+ Pango library always uses @c wxFONTENCODING_UTF8).
+
+ @see GetEncoding()
+ */
+ virtual void SetEncoding(wxFontEncoding encoding);
/**
Sets the facename for the font.
- Returns @true if the given face name exists; @false otherwise.
@param faceName
A valid facename, which should be on the end-user's system.
@remarks To avoid portability problems, don't rely on a specific face,
- but specify the font family instead or as well.
- A suitable font will be found on the end-user's system.
- If both the family and the facename are specified,
- wxWidgets will first search for the specific face, and
- then for a font belonging to the same family.
+ but specify the font family instead (see ::wxFontFamily and SetFamily()).
+
+ @return @true if the given face name exists; if the face name doesn't exist
+ in the user's system then the font is invalidated (so that IsOk() will
+ return @false) and @false is returned.
@see GetFaceName(), SetFamily()
*/
@@ -524,6 +681,11 @@ public:
/**
Sets the font family.
+ As described in ::wxFontFamily docs the given @a family value acts as a rough,
+ basic indication of the main font properties (look, spacing).
+
+ Note that changing the font family results in changing the font face name.
+
@param family
One of the ::wxFontFamily values.
@@ -554,8 +716,8 @@ public:
@beginTable
@hdr3col{platform, generic syntax, example}
- @row3col{wxGTK2, @c [FACE-NAME] [bold] [oblique|italic] [POINTSIZE], Monospace bold 10}
- @row3col{wxMSW, @c [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING], Tahoma 10 WINDOWS-1252}
+ @row3col{wxGTK2,