X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d4cb62411141afdf347cd70a9aa597ab9ec7690d..d3fa4bc22e84e3ca4d88cc1772f2d414140a1017:/interface/wx/font.h
diff --git a/interface/wx/font.h b/interface/wx/font.h
index 766ce5d225..6fe2e6eeb5 100644
--- a/interface/wx/font.h
+++ b/interface/wx/font.h
@@ -270,12 +270,155 @@ enum wxFontEncoding
};
+/**
+ @class wxFontInfo
+
+ This class is a helper used for wxFont creation using named parameter
+ idiom: it allows to specify various wxFont attributes using the chained
+ calls to its clearly named methods instead of passing them in the fixed
+ order to wxFont constructors.
+
+ For example, to create an italic font with the given face name and size you
+ could use:
+ @code
+ wxFont font(wxFontInfo(12).FaceName("Helvetica").Italic());
+ @endcode
+
+ Notice that all of the methods of this object return a reference to the
+ object itself, allowing the calls to them to be chained as in the example
+ above.
+
+ All methods taking boolean parameters can be used to turn the specified
+ font attribute on or off and turn it on by default.
+
+ @since 2.9.5
+ */
+class wxFontInfo
+{
+public:
+ /**
+ Default constructor uses the default font size for the current
+ platform.
+ */
+ wxFontInfo();
+
+ /**
+ Constructor setting the font size in points to use.
+
+ @see wxFont::SetPointSize()
+ */
+ explicit wxFontInfo(int pointSize);
+
+ /**
+ Constructor setting the font size in pixels to use.
+
+ @see wxFont::SetPixelSize()
+ */
+ explicit wxFontInfo(const wxSize& pixelSize);
+
+ /**
+ Set the font family.
+
+ The family is a generic portable way of referring to fonts without
+ specifying a precise face name. This parameter must be one of the
+ ::wxFontFamily enumeration values.
+
+ If the FaceName() is used, then it overrides the font family.
+
+ @see wxFont::SetFamily()
+ */
+ wxFontInfo& Family(wxFontFamily family);
+
+ /**
+ Set the font face name to use.
+
+ Face names are not portable, so prefer to use Family() in portable
+ code.
+
+ @see wxFont::SetFaceName()
+ */
+ wxFontInfo& FaceName(const wxString& faceName);
+
+ /**
+ Use a bold version of the font.
+
+ @see ::wxFontWeight, wxFont::SetWeight()
+ */
+ wxFontInfo& Bold(bool bold = true);
+
+ /**
+ Use a lighter version of the font.
+
+ @see ::wxFontWeight, wxFont::SetWeight()
+ */
+ wxFontInfo& Light(bool light = true);
+
+ /**
+ Use an italic version of the font.
+
+ @see ::wxFontStyle, wxFont::SetStyle()
+ */
+ wxFontInfo& Italic(bool italic = true);
+
+ /**
+ Use a slanted version of the font.
+
+ @see ::wxFontStyle, wxFont::SetStyle()
+ */
+ wxFontInfo& Slant(bool slant = true);
+
+ /**
+ Set anti-aliasing flag.
+
+ Force the use of anti-aliasing on or off.
+
+ Currently this is not implemented, i.e. using this method doesn't do
+ anything.
+ */
+ wxFontInfo& AntiAliased(bool antiAliased = true);
+
+ /**
+ Use an underlined version of the font.
+ */
+ wxFontInfo& Underlined(bool underlined = true);
+
+ /**
+ Use a strike-through version of the font.
+
+ Currently this is only implemented in wxMSW and wxGTK.
+ */
+ wxFontInfo& Strikethrough(bool strikethrough = true);
+
+ /**
+ Set the font encoding to use.
+
+ This is mostly unneeded in Unicode builds of wxWidgets.
+
+ @see ::wxFontEncoding, wxFont::SetEncoding()
+ */
+ wxFontInfo& Encoding(wxFontEncoding encoding);
+
+ /**
+ Set all the font attributes at once.
+
+ See ::wxFontFlag for the various flags that can be used.
+ */
+ wxFontInfo& AllFlags(int flags);
+};
+
/**
@class wxFont
A font is an object which determines the appearance of text.
+
Fonts are used for drawing text to a device context, and setting the appearance
- of a window's text.
+ of a window's text, see wxDC::SetFont() and wxWindow::SetFont().
+
+ The easiest way to create a custom font is to use wxFontInfo object to
+ specify the font attributes and then use wxFont::wxFont(const wxFontInfo&)
+ constructor. Alternatively, you could start with one of the pre-defined
+ fonts or use wxWindow::GetFont() and modify the font, e.g. by increasing
+ its size using MakeLarger() or changing its weight using MakeBold().
This class uses @ref overview_refcount "reference counting and copy-on-write"
internally so that assignments between two instances of this class are very
@@ -308,9 +451,36 @@ public:
*/
wxFont(const wxFont& font);
+ /**
+ Creates a font object using the specified font description.
+
+ This is the preferred way to create font objects as using this ctor
+ results in more readable code and it is also extensible, e.g. it could
+ continue to be used if support for more font attributes is added in the
+ future. For example, this constructor provides the only way of creating
+ fonts with strike-through style.
+
+ Example of creating a font using this ctor:
+ @code
+ wxFont font(wxFontInfo(10).Bold().Underlined());
+ @endcode
+
+ @since 2.9.5
+ */
+ wxFont(const wxFontInfo& font);
+
/**
Creates a font object with the specified attributes and size in points.
+ Notice that the use of this constructor is often more verbose and less
+ readable than the use of constructor from wxFontInfo, e.g. the example
+ in that constructor documentation would need to be written as
+ @code
+ wxFont font(10, wxFONTFAMILY_DEFAULT, wxFONTSTYLE_NORMAL,
+ wxFONTWEIGHT_BOLD, true);
+ @endcode
+ which is longer and less clear.
+
@param pointSize
Size in points. See SetPointSize() for more info.
@param family
@@ -357,6 +527,10 @@ public:
/**
Creates a font object with the specified attributes and size in pixels.
+ Notice that the use of this constructor is often more verbose and less
+ readable than the use of constructor from wxFontInfo, consider using
+ that constructor instead.
+
@param pixelSize
Size in pixels. See SetPixelSize() for more info.
@param family
@@ -400,25 +574,6 @@ public:
const wxString& faceName = wxEmptyString,
wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
- /**
- Creates a font object using font flags.
-
- This constructor is similar to the constructors above except it
- specifies the font styles such as underlined, italic, bold, ... in a
- single @a flags argument instead of using separate arguments for them.
- This parameter can be a combination of ::wxFontFlag enum elements.
- The meaning of the remaining arguments is the same as in the other
- constructors, please see their documentation for details.
-
- Notice that this constructor provides the only way of creating fonts
- with strike-through style.
-
- @since 2.9.4
- */
- wxFont(int pointSize, wxFontFamily family, int flags,
- const wxString& faceName = wxEmptyString,
- wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
-
/**
Constructor from font description string.
@@ -844,7 +999,7 @@ public:
/**
Sets the point size.
- The point size is defined as 1/72 of the anglo-Saxon inch
+ The point size is defined as 1/72 of the Anglo-Saxon inch
(25.4 mm): it is approximately 0.0139 inch or 352.8 um.
@param pointSize
@@ -981,6 +1136,9 @@ public:
This function takes the same parameters as the relative
@ref wxFont::wxFont "wxFont constructor" and returns a new font
object allocated on the heap.
+
+ Their use is discouraged, use wxFont constructor from wxFontInfo
+ instead.
*/
static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,
wxFontWeight weight,