X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/060c4f90939040fbbbd04ace82b4d560870cce33..f2e4cf3dc689b4e9d362637a9f9347fb49fd18d4:/interface/wx/font.h diff --git a/interface/wx/font.h b/interface/wx/font.h index dd85872627..ffa5505743 100644 --- a/interface/wx/font.h +++ b/interface/wx/font.h @@ -3,7 +3,7 @@ // Purpose: interface of wxFont // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -19,28 +19,26 @@ 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. - + /// 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, + /// 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, - - /// Returned by wxFont::GetFamily() when the face name of the font cannot - /// be classified into one of the previous wxFontFamily values. - wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX, - wxFONTFAMILY_MAX + /// Invalid font family value, returned by wxFont::GetFamily() when the + /// font is invalid for example. + wxFONTFAMILY_UNKNOWN }; /** @@ -53,8 +51,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, @@ -111,7 +109,7 @@ enum wxFontFlag /** Font encodings. - + See wxFont::SetEncoding(). */ enum wxFontEncoding @@ -237,13 +235,10 @@ 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 }; @@ -298,7 +293,7 @@ public: @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. @@ -313,8 +308,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. @@ -359,8 +354,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. @@ -401,21 +396,21 @@ public: */ virtual ~wxFont(); - + /** @name Getters */ //@{ - + /** Returns the encoding of this font. - + Note that under wxGTK the returned value is always @c wxFONTENCODING_UTF8. - + @see SetEncoding() */ virtual wxFontEncoding GetEncoding() const; - + /** Returns the face name associated with the font, or the empty string if there is no face information. @@ -425,16 +420,17 @@ public: virtual wxString GetFaceName() const; /** - Gets the font family. + 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_UNKNOWN is returned. - - Note that currently this function is rather unreliable (wxFONTFAMILY_UNKNOWN is - returned in too many cases) and not particularly useful. - Font families mostly make sense only for font creation; see SetFamily(). + 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() */ @@ -442,7 +438,9 @@ 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. @@ -453,8 +451,10 @@ public: /** 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. @@ -474,7 +474,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. @@ -482,7 +482,7 @@ public: @see SetPixelSize() */ virtual wxSize GetPixelSize() const; - + /** Gets the font style. See ::wxFontStyle for a list of valid styles. @@ -507,7 +507,7 @@ 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 @@ -519,14 +519,132 @@ public: Returns @true if this object is a valid font, @false otherwise. */ 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. + */ + //@{ + + /** + 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; + //@} - - - + /** @name Setters - + These functions internally recreate the native font object with the new specified property. */ @@ -534,24 +652,26 @@ public: /** 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 (see ::wxFontFamily). - A suitable font will be found on the end-user's system. + 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() */ @@ -559,7 +679,7 @@ 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). @@ -604,7 +724,7 @@ public: For more detailed information about the allowed syntaxes you can look at the 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). @@ -617,9 +737,9 @@ public: /** 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. @@ -630,19 +750,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. @@ -672,7 +792,7 @@ public: @see GetWeight() */ virtual void SetWeight(wxFontWeight weight); - + //@} @@ -696,8 +816,8 @@ public: Assignment operator, using @ref overview_refcount "reference counting". */ wxFont& operator =(const wxFont& font); - - + + // statics /** @@ -713,7 +833,7 @@ public: @see @ref overview_fontencoding, GetDefaultEncoding() */ static void SetDefaultEncoding(wxFontEncoding encoding); - + //@{ /** This function takes the same parameters as the relative @@ -752,7 +872,7 @@ wxFont wxNullFont; /** Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT). - + @see wxSystemSettings */ wxFont wxNORMAL_FONT;