X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/font.h diff --git a/interface/font.h b/interface/font.h index 02020ace46..a3eeaba9fe 100644 --- a/interface/font.h +++ b/interface/font.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: font.h -// Purpose: documentation for wxFont class +// Purpose: interface of wxFont // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -29,19 +29,9 @@ @category{gdi} @stdobjects - Objects: - wxNullFont - Pointers: - wxNORMAL_FONT + ::wxNullFont, ::wxNORMAL_FONT, ::wxSMALL_FONT, ::wxITALIC_FONT, ::wxSWISS_FONT - wxSMALL_FONT - - wxITALIC_FONT - - wxSWISS_FONT - - @seealso - @ref overview_wxfontoverview "wxFont overview", wxDC::SetFont, wxDC::DrawText, + @see @ref overview_wxfontoverview, wxDC::SetFont, wxDC::DrawText, wxDC::GetTextExtent, wxFontDialog, wxSystemSettings */ class wxFont : public wxGDIObject @@ -50,136 +40,228 @@ public: //@{ /** Creates a font object with the specified attributes. - + @param pointSize - Size in points. - + Size in points. @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: 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. @param family - Font family, a generic way of referring to fonts without specifying actual + Font family, a generic way of referring to fonts without specifying actual facename. One of: - - - wxFONTFAMILY_DEFAULT - - - Chooses a default font. - - wxFONTFAMILY_DECORATIVE - - - A decorative font. - - wxFONTFAMILY_ROMAN - - - A formal, serif font. - - wxFONTFAMILY_SCRIPT - - - A handwriting font. - - wxFONTFAMILY_SWISS - - - A sans-serif font. - - wxFONTFAMILY_MODERN - - - A fixed pitch font. - - wxFONTFAMILY_TELETYPE - - - A teletype font. - + + + + + + + + wxFONTFAMILY_DEFAULT + + + + + Chooses a default font. + + + + + + wxFONTFAMILY_DECORATIVE + + + + + A decorative font. + + + + + + wxFONTFAMILY_ROMAN + + + + + A formal, serif font. + + + + + + wxFONTFAMILY_SCRIPT + + + + + A handwriting font. + + + + + + wxFONTFAMILY_SWISS + + + + + A sans-serif font. + + + + + + wxFONTFAMILY_MODERN + + + + + A fixed pitch font. + + + + + + wxFONTFAMILY_TELETYPE + + + + + A teletype font. @param style - One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. - + One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. @param weight - Font weight, sometimes also referred to as font boldness. One of: - - - wxFONTWEIGHT_NORMAL - - - Normal font. - - wxFONTWEIGHT_LIGHT - - - Light font. - - wxFONTWEIGHT_BOLD - - - Bold font. - + Font weight, sometimes also referred to as font boldness. One of: + + + + + + + + wxFONTWEIGHT_NORMAL + + + + + Normal font. + + + + + + wxFONTWEIGHT_LIGHT + + + + + Light font. + + + + + + wxFONTWEIGHT_BOLD + + + + + Bold font. @param underline - The value can be @true or @false. At present this has an effect on Windows and - Motif 2.x only. - + 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 actual typeface to be used. If it is an + empty string, + a default typeface will be chosen based on the family. @param encoding - An encoding which may be one of - - 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). - - If the specified encoding isn't available, no font is created - (see also font encoding overview). - + An encoding which may be one of + + + + + + + + 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). + + + + + + If the specified encoding isn't available, no font is created + (see also font encoding overview). + @remarks If the desired font does not exist, the closest match will be - chosen. Under Windows, only scalable TrueType fonts - are used. + chosen. Under Windows, only scalable TrueType fonts are + used. */ wxFont(); wxFont(const wxFont& font); wxFont(int pointSize, wxFontFamily family, int style, wxFontWeight weight, - const bool underline = @false, + const bool underline = false, const wxString& faceName = "", wxFontEncoding encoding = wxFONTENCODING_DEFAULT); wxFont(const wxSize& pixelSize, wxFontFamily family, int style, wxFontWeight weight, - const bool underline = @false, + const bool underline = false, const wxString& faceName = "", wxFontEncoding encoding = wxFONTENCODING_DEFAULT); //@} @@ -188,21 +270,19 @@ public: Destructor. See @ref overview_refcountdestruct "reference-counted object destruction" for more info. - + @remarks Although all remaining fonts are deleted when the application - exits, the application should try to clean up all - fonts itself. This is because wxWidgets cannot know - if a pointer to the font object is stored in an - application data structure, and there is a risk of - double deletion. + exits, the application should try to clean up all fonts + itself. This is because wxWidgets cannot know if a + pointer to the font object is stored in an application + data structure, and there is a risk of double deletion. */ ~wxFont(); /** Returns the current application's default encoding. - - @sa @ref overview_wxfontencodingoverview "Font encoding overview", - SetDefaultEncoding() + + @see @ref overview_wxfontencodingoverview, SetDefaultEncoding() */ static wxFontEncoding GetDefaultEncoding(); @@ -210,18 +290,18 @@ public: Returns the typeface name associated with the font, or the empty string if there is no typeface information. - - @sa SetFaceName() + + @see SetFaceName() */ - wxString GetFaceName(); + wxString GetFaceName() const; /** Gets the font family. See SetFamily() for a list of valid family identifiers. - - @sa SetFamily() + + @see SetFamily() */ - wxFontFamily GetFamily(); + wxFontFamily GetFamily() const; /** Returns the platform-dependent string completely describing this font. @@ -229,163 +309,203 @@ public: 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. - - @sa SetNativeFontInfo(),GetNativeFontInfoUserDesc() + + @see SetNativeFontInfo(),GetNativeFontInfoUserDesc() */ - wxString GetNativeFontInfoDesc(); + wxString GetNativeFontInfoDesc() const; /** Returns a user-friendly string for this font object. Returned string is always non-empty. Some examples of the formats of returned strings (which are platform-dependent) are in SetNativeFontInfoUserDesc(). - - @sa GetNativeFontInfoDesc() + + @see GetNativeFontInfoDesc() */ wxString GetNativeFontInfoUserDesc(); /** Gets the point size. - - @sa SetPointSize() + + @see SetPointSize() */ - int GetPointSize(); + int GetPointSize() const; /** Gets the font style. See wxFont() for a list of valid styles. - - @sa SetStyle() + + @see SetStyle() */ - int GetStyle(); + int GetStyle() const; /** Returns @true if the font is underlined, @false otherwise. - - @sa SetUnderlined() + + @see SetUnderlined() */ - bool GetUnderlined(); + bool GetUnderlined() const; /** Gets the font weight. See wxFont() for a list of valid weight identifiers. - - @sa SetWeight() + + @see SetWeight() */ - wxFontWeight GetWeight(); + wxFontWeight GetWeight() const; /** Returns @true if the font is a fixed width (or monospaced) font, @false if it is a proportional one or font is invalid. */ - bool IsFixedWidth(); + bool IsFixedWidth() const; /** Returns @true if this object is a valid font, @false otherwise. */ -#define bool IsOk() /* implementation is private */ + bool IsOk() const; //@{ /** These functions take the same parameters as @ref ctor() wxFont constructor and return a new font object allocated on the heap. - 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, - const 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, - const 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); + static wxFont* New(int pointSize, wxFontFamily family, int style, + wxFontWeight weight, + const 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, + const 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. - - @sa @ref overview_wxfontencodingoverview "Font encoding overview", - GetDefaultEncoding() + + @see @ref overview_wxfontencodingoverview, GetDefaultEncoding() */ static void SetDefaultEncoding(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. - + 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. - - @sa GetFaceName(), SetFamily() + 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. + + @see GetFaceName(), SetFamily() */ bool SetFaceName(const wxString& faceName); /** Sets the font family. - + @param family - One of: - - - wxFONTFAMILY_DEFAULT - - - Chooses a default font. - - wxFONTFAMILY_DECORATIVE - - - A decorative font. - - wxFONTFAMILY_ROMAN - - - A formal, serif font. - - wxFONTFAMILY_SCRIPT - - - A handwriting font. - - wxFONTFAMILY_SWISS - - - A sans-serif font. - - wxFONTFAMILY_MODERN - - - A fixed pitch font. - - wxFONTFAMILY_TELETYPE - - - A teletype font. - - @sa GetFamily(), SetFaceName() + One of: + + + + + + + + wxFONTFAMILY_DEFAULT + + + + + Chooses a default font. + + + + + + wxFONTFAMILY_DECORATIVE + + + + + A decorative font. + + + + + + wxFONTFAMILY_ROMAN + + + + + A formal, serif font. + + + + + + wxFONTFAMILY_SCRIPT + + + + + A handwriting font. + + + + + + wxFONTFAMILY_SWISS + + + + + A sans-serif font. + + + + + + wxFONTFAMILY_MODERN + + + + + A fixed pitch font. + + + + + + wxFONTFAMILY_TELETYPE + + + + + A teletype font. + + @see GetFamily(), SetFaceName() */ void SetFamily(wxFontFamily family); @@ -398,8 +518,8 @@ public: invalid, font is unchanged. This function is typically used for de-serializing a wxFont object previously saved in a string-form. - - @sa SetNativeFontInfoUserDesc() + + @see SetNativeFontInfoUserDesc() */ bool SetNativeFontInfo(const wxString& info); @@ -410,88 +530,102 @@ public: Unlike SetNativeFontInfo(), this function accepts strings which are user-friendly. Examples of accepted string formats are: - - + Generic syntax - - + Example - + on @b wxGTK2: @c [FACE-NAME] [bold] [oblique|italic] [POINTSIZE] - - + Monospace bold 10 - + on @b wxMSW: @c [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING] - - + Tahoma 10 WINDOWS-1252 - + on @b wxMac: FIXME - - + FIXME - + For more detailed information about the allowed syntaxes you can look at the documentation of the native API used for font-rendering (e.g. pango_font_description_from_string). - - @sa SetNativeFontInfo() + + @see SetNativeFontInfo() */ bool SetNativeFontInfoUserDesc(const wxString& info); /** Sets the point size. - + @param pointSize - Size in points. - - @sa GetPointSize() + Size in points. + + @see GetPointSize() */ void SetPointSize(int pointSize); /** Sets the font style. - + @param style - One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. - - @sa GetStyle() + One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. + + @see GetStyle() */ void SetStyle(int style); /** Sets underlining. - + @param underlining - @true to underline, @false otherwise. - - @sa GetUnderlined() + @true to underline, @false otherwise. + + @see GetUnderlined() */ void SetUnderlined(const bool underlined); /** Sets the font weight. - + @param weight - One of: - - - wxFONTWEIGHT_NORMAL - - - Normal font. - - wxFONTWEIGHT_LIGHT - - - Light font. - - wxFONTWEIGHT_BOLD - - - Bold font. - - @sa GetWeight() + One of: + + + + + + + + wxFONTWEIGHT_NORMAL + + + + + Normal font. + + + + + + wxFONTWEIGHT_LIGHT + + + + + Light font. + + + + + + wxFONTWEIGHT_BOLD + + + + + Bold font. + + @see GetWeight() */ void SetWeight(wxFontWeight weight); @@ -514,3 +648,101 @@ public: */ bool operator ==(const wxFont& font); }; + + +/** + An empty wxFont. +*/ +wxFont wxNullFont; + +/** + FIXME +*/ +wxFont wxNORMAL_FONT; + +/** + FIXME +*/ +wxFont wxSMALL_FONT; + +/** + FIXME +*/ +wxFont wxITALIC_FONT; + +/** + FIXME +*/ +wxFont wxSWISS_FONT; + + +/** + @class wxFontList + @wxheader{gdicmn.h} + + A font list is a list containing all fonts which have been created. There + is only one instance of this class: @b wxTheFontList. Use this object to search + for a previously created font of the desired type and create it if not already + found. + In some windowing systems, the font may be a scarce resource, so it is best to + reuse old resources if possible. When an application finishes, all fonts will + be + deleted and their resources freed, eliminating the possibility of 'memory + leaks'. + + @library{wxcore} + @category{gdi} + + @see wxFont +*/ +class wxFontList : public wxList +{ +public: + /** + Constructor. The application should not construct its own font list: + use the object pointer @b wxTheFontList. + */ + wxFontList(); + + /** + Finds a font of the given specification, or creates one and adds it to the + list. See the @ref wxFont::ctor "wxFont constructor" for + details of the arguments. + */ + wxFont* FindOrCreateFont(int point_size, int family, int style, + int weight, + bool underline = false, + const wxString& facename = NULL, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + Converts string to a wxFont best represented by the given string. Returns + @true on success. + + @see wxToString(const wxFont&) + + @header{wx/font.h} +*/ +bool wxFromString(const wxString& string, wxFont* font); + +/** + Converts the given wxFont into a string. + + @see wxFromString(const wxString&, wxFont*) + + @header{wx/font.h} +*/ +wxString wxToString(const wxFont& font); + +//@} +