synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / font.h

diff --git a/interface/wx/font.h b/interface/wx/font.h
index d00738a0dd048769a9348cc0ce5ac3a432639bbe..38238a2216679f7d9c0c8ec622c2d387520112d6 100644 (file)
--- a/interface/wx/font.h
+++ b/interface/wx/font.h
@@ -3,26 +3,42 @@
 // Purpose:     interface of wxFont
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // 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.
 */
 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_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,
     wxFONTFAMILY_MAX,

+    /// Invalid font family value, returned by wxFont::GetFamily() when the
+    /// font is invalid for example.

     wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX
 };
 
     wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX
 };
 


@@ -31,9 +47,16 @@ enum wxFontFamily
 */
 enum wxFontStyle
 {
 */
 enum wxFontStyle
 {

+    /// The font is drawn without slant.

     wxFONTSTYLE_NORMAL = wxNORMAL,
     wxFONTSTYLE_NORMAL = wxNORMAL,

+
+    /// The font is slanted in an italic style.

     wxFONTSTYLE_ITALIC = wxITALIC,
     wxFONTSTYLE_ITALIC = wxITALIC,

+
+    /// 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,
     wxFONTSTYLE_SLANT = wxSLANT,

+

     wxFONTSTYLE_MAX
 };
 
     wxFONTSTYLE_MAX
 };
 


@@ -48,6 +71,27 @@ enum wxFontWeight
     wxFONTWEIGHT_MAX
 };
 
     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.
 */
 /**
     The font flag bits for the new font ctor accepting one combined flags word.
 */


@@ -68,8 +112,10 @@ enum wxFontFlag
     wxFONTFLAG_ANTIALIASED      = 1 << 4,
     wxFONTFLAG_NOT_ANTIALIASED  = 1 << 5,
 
     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,
     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
     wxFONTFLAG_STRIKETHROUGH    = 1 << 7,
 
     /// the mask of all currently used flags


@@ -87,6 +133,8 @@ enum wxFontFlag
 
 /**
     Font encodings.
 
 /**
     Font encodings.

+
+    See wxFont::SetEncoding().

 */
 enum wxFontEncoding
 {
 */
 enum wxFontEncoding
 {


@@ -143,6 +191,8 @@ enum wxFontEncoding
     wxFONTENCODING_CP1255,          //!< WinHebrew
     wxFONTENCODING_CP1256,          //!< WinArabic
     wxFONTENCODING_CP1257,          //!< WinBaltic (same as Latin 7)
     wxFONTENCODING_CP1255,          //!< WinHebrew
     wxFONTENCODING_CP1256,          //!< WinArabic
     wxFONTENCODING_CP1257,          //!< WinBaltic (same as Latin 7)

+    wxFONTENCODING_CP1258,          //!< WinVietnamese (since 2.9.4)
+    wxFONTENCODING_CP1361,          //!< Johab Korean character set (since 2.9.4)

     wxFONTENCODING_CP12_MAX,
 
     wxFONTENCODING_UTF7,            //!< UTF-7 Unicode encoding
     wxFONTENCODING_CP12_MAX,
 
     wxFONTENCODING_UTF7,            //!< UTF-7 Unicode encoding


@@ -211,17 +261,15 @@ enum wxFontEncoding
     /// (this is used by wxEncodingConverter and wxUTFFile only for now)
     wxFONTENCODING_UNICODE,
 
     /// (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
     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
+    wxFONTENCODING_JOHAB = wxFONTENCODING_CP1361, //!< Korean Johab (since 2.9.4)
+    wxFONTENCODING_VIETNAMESE = wxFONTENCODING_CP1258 //!< Vietnamese (since 2.9.4)

 };
 
 
 };
 
 

-

 /**
     @class wxFont
 
 /**
     @class wxFont
 


@@ -250,7 +298,6 @@ enum wxFontEncoding
 class wxFont : public wxGDIObject
 {
 public:
 class wxFont : public wxGDIObject
 {
 public:

-    //@{

     /**
         Default ctor.
     */
     /**
         Default ctor.
     */


@@ -262,41 +309,41 @@ public:
     wxFont(const wxFont& font);
 
     /**
     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
 
         @param pointSize

-            Size in points.
+            Size in points. See SetPointSize() for more info.

         @param family
         @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
         @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
         @param weight

-            Font weight, sometimes also referred to as font boldness. One of
-            the ::wxFontWeight enumeration values.
+            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
         @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:
             <TABLE>
         @param encoding
             An encoding which may be one of the enumeration values of ::wxFontEncoding.
             Briefly these can be summed up as:
             <TABLE>

-                <TR><TD>wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
-                <TR><TD>wxFONTENCODING_DEFAULT</TD><TD>
-                    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.</TD></TR>
-                <TR><TD>wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
-                <TR><TD>wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
-                <TR><TD>wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
+                <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
+                <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
+                    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.</TD></TR>
+                <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
+                <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
+                <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>

             </TABLE>
             If the specified encoding isn't available, no font is created
             </TABLE>
             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.
 
         @remarks If the desired font does not exist, the closest match will be
                  chosen. Under Windows, only scalable TrueType fonts are used.


@@ -308,18 +355,16 @@ public:
            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 
     /**
            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
 
         @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
         @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
         @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.
         @param weight
             Font weight, sometimes also referred to as font boldness.
             One of the ::wxFontWeight enumeration values.


@@ -327,25 +372,24 @@ public:
             The value can be @true or @false.
             At present this has an effect on Windows and Motif 2.x only.
         @param faceName
             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:
             <TABLE>
         @param encoding
             An encoding which may be one of the enumeration values of ::wxFontEncoding.
             Briefly these can be summed up as:
             <TABLE>

-                <TR><TD>wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
-                <TR><TD>wxFONTENCODING_DEFAULT</TD><TD>
-                    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.</TD></TR>
-                <TR><TD>wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
-                <TR><TD>wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
-                <TR><TD>wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>
+                <TR><TD>@c wxFONTENCODING_SYSTEM</TD><TD>Default system encoding.</TD></TR>
+                <TR><TD>@c wxFONTENCODING_DEFAULT</TD><TD>
+                    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.</TD></TR>
+                <TR><TD>@c wxFONTENCODING_ISO8859_1...15</TD><TD>ISO8859 encodings.</TD></TR>
+                <TR><TD>@c wxFONTENCODING_KOI8</TD><TD>The standard Russian encoding for Internet.</TD></TR>
+                <TR><TD>@c wxFONTENCODING_CP1250...1252</TD><TD>Windows encodings similar to ISO8859 (but not identical).</TD></TR>

             </TABLE>
             If the specified encoding isn't available, no font is created
             </TABLE>
             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.
 
         @remarks If the desired font does not exist, the closest match will be
                  chosen. Under Windows, only scalable TrueType fonts are used.


@@ -355,7 +399,39 @@ public:
            bool underline = false,
            const wxString& faceName = wxEmptyString,
            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
            bool underline = false,
            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.
 
     /**
         Destructor.


@@ -371,24 +447,41 @@ public:
     */
     virtual ~wxFont();
 
     */
     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;
 
     /**
 
         @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()
     */
 
         @see SetFamily()
     */


@@ -396,26 +489,35 @@ public:
 
     /**
         Returns the platform-dependent string completely describing this font.
 
     /**
         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.
 
 
         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.
     */
     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().
 
 
         Some examples of the formats of returned strings (which are platform-dependent)
         are in SetNativeFontInfoUserDesc().
 

-        @see GetNativeFontInfoDesc()
+        @see SetNativeFontInfoUserDesc(), GetNativeFontInfoDesc()

     */
     wxString GetNativeFontInfoUserDesc() const;
 
     */
     wxString GetNativeFontInfoUserDesc() const;
 

+    const wxNativeFontInfo *GetNativeFontInfo() const;
+

     /**
         Gets the point size.
 
     /**
         Gets the point size.
 


@@ -424,7 +526,18 @@ public:
     virtual int GetPointSize() const;
 
     /**
     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()
     */
 
         @see SetStyle()
     */


@@ -438,7 +551,16 @@ public:
     virtual bool GetUnderlined() const;
 
     /**
     virtual bool GetUnderlined() const;
 
     /**

-        Gets the font weight. See wxFontWeight for a list of valid weight identifiers.
+        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.

 
         @see SetWeight()
     */
 
         @see SetWeight()
     */


@@ -447,6 +569,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.
     /**
         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;
 
     */
     virtual bool IsFixedWidth() const;
 


@@ -455,58 +582,198 @@ public:
     */
     virtual bool IsOk() const;
 
     */
     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;
+
+    /**
+        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.

 
 

-        Using @c New() is currently the only way to directly create a font with
-        the given size in pixels on platforms other than wxMSW.
+        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.
 
     /**
         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,
 
         @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()
     */
 
         @see GetFaceName(), SetFamily()
     */


@@ -515,6 +782,11 @@ public:
     /**
         Sets the font family.
 
     /**
         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.
 
         @param family
             One of the ::wxFontFamily values.
 


@@ -545,8 +817,8 @@ public:
 
         @beginTable
         @hdr3col{platform, generic syntax, example}
 
         @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, <tt>[FACE-NAME] [bold] [oblique|italic] [POINTSIZE]</tt>, Monospace bold 10}
+        @row3col{wxMSW, <tt>[light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING]</tt>, Tahoma 10 WINDOWS-1252}

         @endTable
 
         @todo add an example for wxMac
         @endTable
 
         @todo add an example for wxMac


@@ -555,13 +827,24 @@ public:
         documentation of the native API used for font-rendering
         (e.g. @c pango_font_description_from_string on GTK).
 
         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);
 
         @see SetNativeFontInfo()
     */
     bool SetNativeFontInfoUserDesc(const wxString& info);
 

+    void SetNativeFontInfo(const wxNativeFontInfo& info);
+        

     /**
         Sets the point size.
 
     /**
         Sets the point size.
 

+        The <em>point size</em> 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.
 
         @param pointSize
             Size in points.
 


@@ -569,6 +852,21 @@ public:
     */
     virtual void SetPointSize(int pointSize);
 
     */
     virtual void SetPointSize(int pointSize);
 

+    /**
+        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
+        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.
 
     /**
         Sets the font style.
 


@@ -579,6 +877,28 @@ public:
     */
     virtual void SetStyle(wxFontStyle style);
 
     */
     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.
 
     /**
         Sets underlining.
 


@@ -589,6 +909,20 @@ public:
     */
     virtual void SetUnderlined(bool underlined);
 
     */
     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.
 
     /**
         Sets the font weight.
 


@@ -599,6 +933,9 @@ public:
     */
     virtual void SetWeight(wxFontWeight weight);
 
     */
     virtual void SetWeight(wxFontWeight weight);
 

+    //@}
+
+

     /**
         Inequality operator.
 
     /**
         Inequality operator.
 


@@ -619,6 +956,57 @@ public:
         Assignment operator, using @ref overview_refcount "reference counting".
     */
     wxFont& operator =(const wxFont& font);
         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);
+
+    //@}

 };
 
 
 };
 
 


@@ -629,26 +1017,28 @@ wxFont wxNullFont;
 
 /**
     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).
 
 /**
     Equivalent to wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT).

+
+    @see wxSystemSettings

 */
 */

-wxFont wxNORMAL_FONT;
+wxFont* wxNORMAL_FONT;

 
 /**
 
 /**

-    A font using the wxFONTFAMILY_SWISS family and 2 points smaller than
+    A font using the @c wxFONTFAMILY_SWISS family and 2 points smaller than

     ::wxNORMAL_FONT.
 */
     ::wxNORMAL_FONT.
 */

-wxFont wxSMALL_FONT;
+wxFont* wxSMALL_FONT;

 
 /**
 
 /**

-    A font using the wxFONTFAMILY_ROMAN family and wxFONTSTYLE_ITALIC style and
+    A font using the @c wxFONTFAMILY_ROMAN family and @c wxFONTSTYLE_ITALIC style and

     of the same size of ::wxNORMAL_FONT.
 */
     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
 
 /**
     A font identic to ::wxNORMAL_FONT except for the family used which is

-    wxFONTFAMILY_SWISS.
+    @c wxFONTFAMILY_SWISS.

 */
 */

-wxFont wxSWISS_FONT;
+wxFont* wxSWISS_FONT;

 
 
 /**
 
 
 /**