X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/071de7a097edd90a8f39d4624b26b5744560e677..f115bfec38b810f06ccc47544a4e2e2e410f73b1:/interface/wx/font.h diff --git a/interface/wx/font.h b/interface/wx/font.h index d0f7f25ca9..dab6d19b2a 100644 --- a/interface/wx/font.h +++ b/interface/wx/font.h @@ -3,26 +3,42 @@ // Purpose: interface of wxFont // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** - Standard font families: these may be used only for the font creation, it - doesn't make sense to query an existing font for its font family as, - especially if the font had been created from a native font description, it - may be unknown. + Standard font families: these are used mainly during wxFont creation to specify + the generic properties of the font without hardcoding in the sources a specific + face name. + + wxFontFamily thus allows to group the font face names of fonts with similar + properties. Most wxWidgets ports use lists of fonts for each font family + inspired by the data taken from http://www.codestyle.org/css/font-family. */ enum wxFontFamily { wxFONTFAMILY_DEFAULT = wxDEFAULT, //!< Chooses a default font. + wxFONTFAMILY_DECORATIVE = wxDECORATIVE, //!< A decorative font. wxFONTFAMILY_ROMAN = wxROMAN, //!< A formal, serif font. wxFONTFAMILY_SCRIPT = wxSCRIPT, //!< A handwriting font. wxFONTFAMILY_SWISS = wxSWISS, //!< A sans-serif font. - wxFONTFAMILY_MODERN = wxMODERN, //!< A fixed pitch font. - wxFONTFAMILY_TELETYPE = wxTELETYPE, //!< A teletype font. + + /// A fixed pitch font. Note that wxFont currently does not make distinctions + /// between @c wxFONTFAMILY_MODERN and @c wxFONTFAMILY_TELETYPE. + wxFONTFAMILY_MODERN = wxMODERN, + + /// A teletype (i.e. monospaced) font. + /// Monospace fonts have a fixed width like typewriters and often have strong angular + /// or block serifs. Monospace font faces are often used code samples and have a simple, + /// functional font style. + /// See also wxFont::IsFixedWidth() for an easy way to test for monospace property. + wxFONTFAMILY_TELETYPE = wxTELETYPE, + wxFONTFAMILY_MAX, + /// Invalid font family value, returned by wxFont::GetFamily() when the + /// font is invalid for example. wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX }; @@ -36,8 +52,8 @@ enum wxFontStyle /// The font is slanted in an italic style. wxFONTSTYLE_ITALIC = wxITALIC, - - /// The font is slanted, but in a roman style. + + /// The font is slanted, but in a roman style. /// Note that under wxMSW this style is the same as @c wxFONTSTYLE_ITALIC. wxFONTSTYLE_SLANT = wxSLANT, @@ -55,6 +71,27 @@ enum wxFontWeight wxFONTWEIGHT_MAX }; +/** + Symbolic font sizes. + + The elements of this enum correspond to CSS absolute size specifications, + see http://www.w3.org/TR/CSS21/fonts.html#font-size-props + + @see wxFont::SetSymbolicSize() + + @since 2.9.2 + */ +enum wxFontSymbolicSize +{ + wxFONTSIZE_XX_SMALL = -3, //!< Extra small. + wxFONTSIZE_X_SMALL, //!< Very small. + wxFONTSIZE_SMALL, //!< Small. + wxFONTSIZE_MEDIUM, //!< Normal. + wxFONTSIZE_LARGE, //!< Large. + wxFONTSIZE_X_LARGE, //!< Very large. + wxFONTSIZE_XX_LARGE //!< Extra large. +}; + /** The font flag bits for the new font ctor accepting one combined flags word. */ @@ -75,8 +112,10 @@ enum wxFontFlag wxFONTFLAG_ANTIALIASED = 1 << 4, wxFONTFLAG_NOT_ANTIALIASED = 1 << 5, - /// underlined/strikethrough flags (default: no lines) + /// Underlined style (not underlined by default). wxFONTFLAG_UNDERLINED = 1 << 6, + + /// Strike-through style (only supported in wxMSW and wxGTK currently). wxFONTFLAG_STRIKETHROUGH = 1 << 7, /// the mask of all currently used flags @@ -94,6 +133,8 @@ enum wxFontFlag /** Font encodings. + + See wxFont::SetEncoding(). */ enum wxFontEncoding { @@ -218,17 +259,13 @@ enum wxFontEncoding /// (this is used by wxEncodingConverter and wxUTFFile only for now) wxFONTENCODING_UNICODE, - // alternative names for Far Eastern encodings - // Chinese wxFONTENCODING_GB2312 = wxFONTENCODING_CP936, //!< Simplified Chinese wxFONTENCODING_BIG5 = wxFONTENCODING_CP950, //!< Traditional Chinese - - // Japanese (see http://zsigri.tripod.com/fontboard/cjk/jis.html) - wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932 //!< Shift JIS + wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932, //!< Shift JIS + wxFONTENCODING_EUC_KR = wxFONTENCODING_CP949 //!< Korean }; - /** @class wxFont @@ -268,24 +305,25 @@ public: wxFont(const wxFont& font); /** - Creates a font object with the specified attributes. + Creates a font object with the specified attributes and size in points. @param pointSize Size in points. See SetPointSize() for more info. @param family - Font family, a generic way of referring to fonts without specifying actual - facename. One of the ::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 @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC. @param weight - Font weight, sometimes also referred to as font boldness. + Font weight, sometimes also referred to as font boldness. One of the ::wxFontWeight enumeration values. @param underline 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: @@ -293,8 +331,8 @@ public: @c wxFONTENCODING_SYSTEMDefault 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 + 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...15ISO8859 encodings. @c wxFONTENCODING_KOI8The standard Russian encoding for Internet. @@ -313,13 +351,14 @@ public: wxFontEncoding encoding = wxFONTENCODING_DEFAULT); /** - Creates a font object with the specified attributes. + Creates a font object with the specified attributes and size in pixels. @param pixelSize 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 @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC. @param weight @@ -329,8 +368,8 @@ 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: @@ -338,8 +377,8 @@ public: @c wxFONTENCODING_SYSTEMDefault 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 + 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...15ISO8859 encodings. @c wxFONTENCODING_KOI8The standard Russian encoding for Internet. @@ -357,6 +396,39 @@ 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. + + 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& nativeInfoString); + + /** + Construct font from a native font info structure. + */ + wxFont(const wxNativeFontInfo& nativeInfo); + /** Destructor. @@ -371,24 +443,41 @@ 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 if possible. + + 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_DEFAULT is returned. + + Note that currently this function is not very precise and so not + particularly useful. Font families mostly make sense only for font + creation, see SetFamily(). @see SetFamily() */ @@ -396,26 +485,35 @@ 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; + const wxNativeFontInfo *GetNativeFontInfo() const; + /** Gets the point size. @@ -425,7 +523,7 @@ public: /** 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. @@ -433,7 +531,7 @@ public: @see SetPixelSize() */ virtual wxSize GetPixelSize() const; - + /** Gets the font style. See ::wxFontStyle for a list of valid styles. @@ -448,6 +546,15 @@ public: */ virtual bool GetUnderlined() const; + /** + Returns @true if the font is stricken-through, @false otherwise. + + @see SetStrikethrough() + + @since 2.9.4 + */ + virtual bool GetStrikethrough() const; + /** Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers. @@ -458,6 +565,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; @@ -466,55 +578,198 @@ 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. + */ //@{ + /** - This function takes the same parameters as the relative - @ref wxFont::wxFont "wxFont constructor" and returns 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; + + /** + Returns underlined version of this font. + + @see MakeUnderlined() + + @since 2.9.2 + */ + wxFont Underlined() const; + + /** + Returns stricken-through version of this font. + + Currently stricken-through fonts are only supported in wxMSW and wxGTK. + + @see MakeStrikethrough() + + @since 2.9.4 + */ + wxFont Strikethrough() 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 this font to be underlined. + + @see Underlined() + + @since 2.9.2 + */ + wxFont& MakeUnderlined(); + + /** + Changes this font to be stricken-through. + + Currently stricken-through fonts are only supported in wxMSW and wxGTK. + + @see Strikethrough() + + @since 2.9.4 */ - static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style, - wxFontWeight weight, - bool underline = false, - const wxString& faceName = wxEmptyString, - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - static wxFont* New(int pointSize, wxFontFamily family, - int flags = wxFONTFLAG_DEFAULT, - const wxString& faceName = wxEmptyString, - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - static wxFont* New(const wxSize& pixelSize, - wxFontFamily family, - wxFontStyle style, - wxFontWeight weight, - bool underline = false, - const wxString& faceName = wxEmptyString, - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - static wxFont* New(const wxSize& pixelSize, - wxFontFamily family, - int flags = wxFONTFLAG_DEFAULT, - const wxString& faceName = wxEmptyString, - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + wxFont& MakeStrikethrough(); + + /** + 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; + //@} /** - 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() */ @@ -523,6 +778,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. @@ -563,15 +823,23 @@ public: documentation of the native API used for font-rendering (e.g. @c pango_font_description_from_string on GTK). + Note that unlike SetNativeFontInfo(), this function doesn't always restore all + attributes of the wxFont object under all platforms; e.g. on wxMSW the font family + is not restored (because GetNativeFontInfoUserDesc doesn't return it on wxMSW). + If you want to serialize/deserialize a font in string form, you should use + GetNativeFontInfoDesc() and SetNativeFontInfo() instead. + @see SetNativeFontInfo() */ bool SetNativeFontInfoUserDesc(const wxString& info); + void SetNativeFontInfo(const wxNativeFontInfo& info); + /** Sets the point size. - - 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. + + 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 Size in points. @@ -582,19 +850,19 @@ public: /** Sets the pixel size. - + The height parameter of @a pixelSize must be positive while the width parameter may also be zero (to indicate that you're not interested in the width of the characters: a suitable width will be chosen for best rendering). - - This feature (specifying the font pixel size) is directly supported only - under wxMSW and wxGTK currently; under other platforms a font with the + + This feature (specifying the font pixel size) is directly supported only + under wxMSW and wxGTK currently; under other platforms a font with the closest size to the given one is found using binary search (this maybe slower). @see GetPixelSize() */ virtual void SetPixelSize(const wxSize& pixelSize); - + /** Sets the font style. @@ -605,6 +873,28 @@ public: */ virtual void SetStyle(wxFontStyle style); + /** + Sets the font size using a predefined symbolic size name. + + This function allows to change font size to be (very) large or small + compared to the standard font size. + + @see SetSymbolicSizeRelativeTo(). + + @since 2.9.2 + */ + void SetSymbolicSize(wxFontSymbolicSize size); + + /** + Sets the font size compared to the base font size. + + This is the same as SetSymbolicSize() except that it uses the given + font size as the normal font size instead of the standard font size. + + @since 2.9.2 + */ + void SetSymbolicSizeRelativeTo(wxFontSymbolicSize size, int base); + /** Sets underlining. @@ -615,6 +905,20 @@ public: */ virtual void SetUnderlined(bool underlined); + /** + Sets strike-through attribute of the font. + + Currently stricken-through fonts are only supported in wxMSW and wxGTK. + + @param strikethrough + @true to add strike-through style, @false to remove it. + + @see GetStrikethrough() + + @since 2.9.4 + */ + virtual void SetStrikethrough(bool strikethrough); + /** Sets the font weight. @@ -625,6 +929,9 @@ public: */ virtual void SetWeight(wxFontWeight weight); + //@} + + /** Inequality operator. @@ -645,6 +952,57 @@ public: Assignment operator, using @ref overview_refcount "reference counting". */ wxFont& operator =(const wxFont& font); + + + // statics + + /** + Returns the current application's default encoding. + + @see @ref overview_fontencoding, SetDefaultEncoding() + */ + static wxFontEncoding GetDefaultEncoding(); + + /** + Sets the default font encoding. + + @see @ref overview_fontencoding, GetDefaultEncoding() + */ + static void SetDefaultEncoding(wxFontEncoding encoding); + + //@{ + /** + This function takes the same parameters as the relative + @ref wxFont::wxFont "wxFont constructor" and returns a new font + object allocated on the heap. + */ + static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style, + wxFontWeight weight, + bool underline = false, + const wxString& faceName = wxEmptyString, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(int pointSize, wxFontFamily family, + int flags = wxFONTFLAG_DEFAULT, + const wxString& faceName = wxEmptyString, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(const wxSize& pixelSize, + wxFontFamily family, + wxFontStyle style, + wxFontWeight weight, + bool underline = false, + const wxString& faceName = wxEmptyString, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(const wxSize& pixelSize, + wxFontFamily family, + int flags = wxFONTFLAG_DEFAULT, + const wxString& faceName = wxEmptyString, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + + + static wxFont *New(const wxNativeFontInfo& nativeInfo); + static wxFont *New(const wxString& nativeInfoString); + + //@} }; @@ -655,28 +1013,28 @@ wxFont wxNullFont; /** Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT). - + @see wxSystemSettings */ -wxFont wxNORMAL_FONT; +wxFont* wxNORMAL_FONT; /** A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than ::wxNORMAL_FONT. */ -wxFont wxSMALL_FONT; +wxFont* wxSMALL_FONT; /** A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and of the same size of ::wxNORMAL_FONT. */ -wxFont wxITALIC_FONT; +wxFont* wxITALIC_FONT; /** A font identic to ::wxNORMAL_FONT except for the family used which is @c wxFONTFAMILY_SWISS. */ -wxFont wxSWISS_FONT; +wxFont* wxSWISS_FONT; /**