remove semicolon from wxDECLARE_EVENT; having it there was inconsistent with other...

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

diff --git a/interface/wx/font.h b/interface/wx/font.h
index e4e99ae1dc566d0c4f43d6304d6f35ccc5f0fbb1..b1cb4e1b815a20493cca93274731566493d1d744 100644 (file)
--- a/interface/wx/font.h
+++ b/interface/wx/font.h
@@ -8,22 +8,39 @@
 
 
 /**
 
 
 /**

-    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.
-    wxFONTFAMILY_MAX,
-    wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX
+    
+    /// 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,
+    
+    /// 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

 };
 
 /**
 };
 
 /**


@@ -31,9 +48,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
 };
 


@@ -97,63 +121,63 @@ enum wxFontEncoding
     wxFONTENCODING_DEFAULT,         // current default encoding
 
     // ISO8859 standard defines a number of single-byte charsets
     wxFONTENCODING_DEFAULT,         // current default encoding
 
     // ISO8859 standard defines a number of single-byte charsets

-    wxFONTENCODING_ISO8859_1,       // West European (Latin1)
-    wxFONTENCODING_ISO8859_2,       // Central and East European (Latin2)
-    wxFONTENCODING_ISO8859_3,       // Esperanto (Latin3)
-    wxFONTENCODING_ISO8859_4,       // Baltic (old) (Latin4)
-    wxFONTENCODING_ISO8859_5,       // Cyrillic
-    wxFONTENCODING_ISO8859_6,       // Arabic
-    wxFONTENCODING_ISO8859_7,       // Greek
-    wxFONTENCODING_ISO8859_8,       // Hebrew
-    wxFONTENCODING_ISO8859_9,       // Turkish (Latin5)
-    wxFONTENCODING_ISO8859_10,      // Variation of Latin4 (Latin6)
-    wxFONTENCODING_ISO8859_11,      // Thai
-    wxFONTENCODING_ISO8859_12,      // doesn't exist currently, but put it
-                                    // here anyhow to make all ISO8859
-                                    // consecutive numbers
-    wxFONTENCODING_ISO8859_13,      // Baltic (Latin7)
-    wxFONTENCODING_ISO8859_14,      // Latin8
-    wxFONTENCODING_ISO8859_15,      // Latin9 (a.k.a. Latin0, includes euro)
+    wxFONTENCODING_ISO8859_1,       //!< West European (Latin1)
+    wxFONTENCODING_ISO8859_2,       //!< Central and East European (Latin2)
+    wxFONTENCODING_ISO8859_3,       //!< Esperanto (Latin3)
+    wxFONTENCODING_ISO8859_4,       //!< Baltic (old) (Latin4)
+    wxFONTENCODING_ISO8859_5,       //!< Cyrillic
+    wxFONTENCODING_ISO8859_6,       //!< Arabic
+    wxFONTENCODING_ISO8859_7,       //!< Greek
+    wxFONTENCODING_ISO8859_8,       //!< Hebrew
+    wxFONTENCODING_ISO8859_9,       //!< Turkish (Latin5)
+    wxFONTENCODING_ISO8859_10,      //!< Variation of Latin4 (Latin6)
+    wxFONTENCODING_ISO8859_11,      //!< Thai
+    wxFONTENCODING_ISO8859_12,      //!< doesn't exist currently, but put it
+                                    //!< here anyhow to make all ISO8859
+                                    //!< consecutive numbers
+    wxFONTENCODING_ISO8859_13,      //!< Baltic (Latin7)
+    wxFONTENCODING_ISO8859_14,      //!< Latin8
+    wxFONTENCODING_ISO8859_15,      //!< Latin9 (a.k.a. Latin0, includes euro)

     wxFONTENCODING_ISO8859_MAX,
 
     // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
     wxFONTENCODING_ISO8859_MAX,
 
     // Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)

-    wxFONTENCODING_KOI8,            // KOI8 Russian
-    wxFONTENCODING_KOI8_U,          // KOI8 Ukrainian
-    wxFONTENCODING_ALTERNATIVE,     // same as MS-DOS CP866
-    wxFONTENCODING_BULGARIAN,       // used under Linux in Bulgaria
+    wxFONTENCODING_KOI8,            //!< KOI8 Russian
+    wxFONTENCODING_KOI8_U,          //!< KOI8 Ukrainian
+    wxFONTENCODING_ALTERNATIVE,     //!< same as MS-DOS CP866
+    wxFONTENCODING_BULGARIAN,       //!< used under Linux in Bulgaria

 
     // what would we do without Microsoft? They have their own encodings
         // for DOS
 
     // what would we do without Microsoft? They have their own encodings
         // for DOS

-    wxFONTENCODING_CP437,           // original MS-DOS codepage
-    wxFONTENCODING_CP850,           // CP437 merged with Latin1
-    wxFONTENCODING_CP852,           // CP437 merged with Latin2
-    wxFONTENCODING_CP855,           // another cyrillic encoding
-    wxFONTENCODING_CP866,           // and another one
+    wxFONTENCODING_CP437,           //!< original MS-DOS codepage
+    wxFONTENCODING_CP850,           //!< CP437 merged with Latin1
+    wxFONTENCODING_CP852,           //!< CP437 merged with Latin2
+    wxFONTENCODING_CP855,           //!< another cyrillic encoding
+    wxFONTENCODING_CP866,           //!< and another one

         // and for Windows
         // and for Windows

-    wxFONTENCODING_CP874,           // WinThai
-    wxFONTENCODING_CP932,           // Japanese (shift-JIS)
-    wxFONTENCODING_CP936,           // Chinese simplified (GB)
-    wxFONTENCODING_CP949,           // Korean (Hangul charset)
-    wxFONTENCODING_CP950,           // Chinese (traditional - Big5)
-    wxFONTENCODING_CP1250,          // WinLatin2
-    wxFONTENCODING_CP1251,          // WinCyrillic
-    wxFONTENCODING_CP1252,          // WinLatin1
-    wxFONTENCODING_CP1253,          // WinGreek (8859-7)
-    wxFONTENCODING_CP1254,          // WinTurkish
-    wxFONTENCODING_CP1255,          // WinHebrew
-    wxFONTENCODING_CP1256,          // WinArabic
-    wxFONTENCODING_CP1257,          // WinBaltic (same as Latin 7)
+    wxFONTENCODING_CP874,           //!< WinThai
+    wxFONTENCODING_CP932,           //!< Japanese (shift-JIS)
+    wxFONTENCODING_CP936,           //!< Chinese simplified (GB)
+    wxFONTENCODING_CP949,           //!< Korean (Hangul charset)
+    wxFONTENCODING_CP950,           //!< Chinese (traditional - Big5)
+    wxFONTENCODING_CP1250,          //!< WinLatin2
+    wxFONTENCODING_CP1251,          //!< WinCyrillic
+    wxFONTENCODING_CP1252,          //!< WinLatin1
+    wxFONTENCODING_CP1253,          //!< WinGreek (8859-7)
+    wxFONTENCODING_CP1254,          //!< WinTurkish
+    wxFONTENCODING_CP1255,          //!< WinHebrew
+    wxFONTENCODING_CP1256,          //!< WinArabic
+    wxFONTENCODING_CP1257,          //!< WinBaltic (same as Latin 7)

     wxFONTENCODING_CP12_MAX,
 
     wxFONTENCODING_CP12_MAX,
 

-    wxFONTENCODING_UTF7,            // UTF-7 Unicode encoding
-    wxFONTENCODING_UTF8,            // UTF-8 Unicode encoding
-    wxFONTENCODING_EUC_JP,          // Extended Unix Codepage for Japanese
-    wxFONTENCODING_UTF16BE,         // UTF-16 Big Endian Unicode encoding
-    wxFONTENCODING_UTF16LE,         // UTF-16 Little Endian Unicode encoding
-    wxFONTENCODING_UTF32BE,         // UTF-32 Big Endian Unicode encoding
+    wxFONTENCODING_UTF7,            //!< UTF-7 Unicode encoding
+    wxFONTENCODING_UTF8,            //!< UTF-8 Unicode encoding
+    wxFONTENCODING_EUC_JP,          //!< Extended Unix Codepage for Japanese
+    wxFONTENCODING_UTF16BE,         //!< UTF-16 Big Endian Unicode encoding
+    wxFONTENCODING_UTF16LE,         //!< UTF-16 Little Endian Unicode encoding
+    wxFONTENCODING_UTF32BE,         //!< UTF-32 Big Endian Unicode encoding

     wxFONTENCODING_UTF32LE,         // UTF-32 Little Endian Unicode encoding
 
     wxFONTENCODING_UTF32LE,         // UTF-32 Little Endian Unicode encoding
 

-    wxFONTENCODING_MACROMAN,        // the standard mac encodings
+    wxFONTENCODING_MACROMAN,        //!< the standard mac encodings

     wxFONTENCODING_MACJAPANESE,
     wxFONTENCODING_MACCHINESETRAD,
     wxFONTENCODING_MACKOREAN,
     wxFONTENCODING_MACJAPANESE,
     wxFONTENCODING_MACCHINESETRAD,
     wxFONTENCODING_MACKOREAN,


@@ -196,37 +220,28 @@ enum wxFontEncoding
 
     // more CJK encodings (for historical reasons some are already declared
     // above)
 
     // more CJK encodings (for historical reasons some are already declared
     // above)

-    wxFONTENCODING_ISO2022_JP,      // ISO-2022-JP JIS encoding
+    wxFONTENCODING_ISO2022_JP,      //!< ISO-2022-JP JIS encoding

 
 

-    wxFONTENCODING_MAX,             // highest enumerated encoding value
+    wxFONTENCODING_MAX,             //!< highest enumerated encoding value

 
     wxFONTENCODING_MACMIN = wxFONTENCODING_MACROMAN ,
     wxFONTENCODING_MACMAX = wxFONTENCODING_MACKEYBOARD ,
 
     // aliases for endian-dependent UTF encodings
 
     wxFONTENCODING_MACMIN = wxFONTENCODING_MACROMAN ,
     wxFONTENCODING_MACMAX = wxFONTENCODING_MACKEYBOARD ,
 
     // aliases for endian-dependent UTF encodings

-#ifdef WORDS_BIGENDIAN
-    wxFONTENCODING_UTF16 = wxFONTENCODING_UTF16BE,  // native UTF-16
-    wxFONTENCODING_UTF32 = wxFONTENCODING_UTF32BE,  // native UTF-32
-#else // WORDS_BIGENDIAN
-    wxFONTENCODING_UTF16 = wxFONTENCODING_UTF16LE,  // native UTF-16
-    wxFONTENCODING_UTF32 = wxFONTENCODING_UTF32LE,  // native UTF-32
-#endif // WORDS_BIGENDIAN
-
-    // alias for the native Unicode encoding on this platform
-    // (this is used by wxEncodingConverter and wxUTFFile only for now)
-#if SIZEOF_WCHAR_T == 2
-    wxFONTENCODING_UNICODE = wxFONTENCODING_UTF16,
-#else // SIZEOF_WCHAR_T == 4
-    wxFONTENCODING_UNICODE = wxFONTENCODING_UTF32,
-#endif
+    wxFONTENCODING_UTF16,  //!< native UTF-16
+    wxFONTENCODING_UTF32,  //!< native UTF-32
+
+    /// Alias for the native Unicode encoding on this platform
+    /// (this is used by wxEncodingConverter and wxUTFFile only for now)
+    wxFONTENCODING_UNICODE,

 
     // alternative names for Far Eastern encodings
     // Chinese
 
     // 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)
 
         // Japanese (see http://zsigri.tripod.com/fontboard/cjk/jis.html)

-    wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932 // Shift JIS
+    wxFONTENCODING_SHIFT_JIS = wxFONTENCODING_CP932 //!< Shift JIS

 };
 
 
 };
 
 


@@ -259,7 +274,6 @@ enum wxFontEncoding
 class wxFont : public wxGDIObject
 {
 public:
 class wxFont : public wxGDIObject
 {
 public:

-    //@{

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


@@ -274,61 +288,59 @@ public:
         Creates a font object with the specified attributes.
 
         @param pointSize
         Creates a font object with the specified attributes.
 
         @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.
     */

-    wxFont(int pointSize, wxFontFamily family, int style,
+    wxFont(int pointSize, wxFontFamily family, wxFontStyle style,

            wxFontWeight weight,
            bool underline = false,
            wxFontWeight weight,
            bool underline = false,

-           const wxString& faceName = "",
+           const wxString& faceName = wxEmptyString,

            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 
     /**
         Creates a font object with the specified attributes.
 
         @param pixelSize
            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 
     /**
         Creates a font object with the specified attributes.
 
         @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.


@@ -336,35 +348,42 @@ 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.
     */
     wxFont(const wxSize& pixelSize, wxFontFamily family,
 
         @remarks If the desired font does not exist, the closest match will be
                  chosen. Under Windows, only scalable TrueType fonts are used.
     */
     wxFont(const wxSize& pixelSize, wxFontFamily family,

-           int style, wxFontWeight weight,
+           wxFontStyle style, wxFontWeight weight,

            bool underline = false,
            bool underline = false,

-           const wxString& faceName = "",
+           const wxString& faceName = wxEmptyString,

            wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
            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& fontdesc);

 
     /**
         Destructor.
 
     /**
         Destructor.


@@ -388,16 +407,20 @@ public:
     static wxFontEncoding GetDefaultEncoding();
 
     /**
     static wxFontEncoding GetDefaultEncoding();
 
     /**

-        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.
+        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.

 
         @see SetFamily()
     */
 
         @see SetFamily()
     */


@@ -410,18 +433,21 @@ 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.
 
         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.
     */
     wxString GetNativeFontInfoDesc() const;
 
     /**
         Returns a user-friendly string for this font object.
         Returned string is always non-empty.

+        
+        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;
 


@@ -433,7 +459,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()
     */


@@ -447,7 +484,7 @@ public:
     virtual bool GetUnderlined() const;
 
     /**
     virtual bool GetUnderlined() const;
 
     /**

-        Gets the font weight. See wxFontWeight for a list of valid weight identifiers.
+        Gets the font weight. See ::wxFontWeight for a list of valid weight identifiers.

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


@@ -456,6 +493,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;
 


@@ -466,33 +508,30 @@ public:
 
     //@{
     /**
 
     //@{
     /**

-        These functions take the same parameters as
-        @ref wxFont::wxFont "wxFont constructors" and return a new font
+        This function takes the same parameters as the relative
+        @ref wxFont::wxFont "wxFont constructor" and returns a new font

         object allocated on the heap.
         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,
+    static wxFont* New(int pointSize, wxFontFamily family, wxFontStyle style,

                        wxFontWeight weight,
                        bool underline = false,
                        wxFontWeight weight,
                        bool underline = false,

-                       const wxString& faceName = "",
+                       const wxString& faceName = wxEmptyString,

                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
     static wxFont* New(int pointSize, wxFontFamily family,
                        int flags = wxFONTFLAG_DEFAULT,
                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
     static wxFont* New(int pointSize, wxFontFamily family,
                        int flags = wxFONTFLAG_DEFAULT,

-                       const wxString& faceName = "",
+                       const wxString& faceName = wxEmptyString,

                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
     static wxFont* New(const wxSize& pixelSize,
                        wxFontFamily family,
                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
     static wxFont* New(const wxSize& pixelSize,
                        wxFontFamily family,

-                       int style,
+                       wxFontStyle style,

                        wxFontWeight weight,
                        bool underline = false,
                        wxFontWeight weight,
                        bool underline = false,

-                       const wxString& faceName = "",
+                       const wxString& faceName = wxEmptyString,

                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
     static wxFont* New(const wxSize& pixelSize,
                        wxFontFamily family,
                        int flags = wxFONTFLAG_DEFAULT,
                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
     static wxFont* New(const wxSize& pixelSize,
                        wxFontFamily family,
                        int flags = wxFONTFLAG_DEFAULT,

-                       const wxString& faceName = "",
+                       const wxString& faceName = wxEmptyString,

                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
     //@}
 
                        wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
     //@}
 


@@ -511,11 +550,11 @@ public:
             A valid facename, which should be on the end-user's system.
 
         @remarks To avoid portability problems, don't rely on a specific face,
             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.
+                 but specify the font family instead or as well (see ::wxFontFamily).

                  A suitable font will be found on the end-user's system.
                  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.
+                 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()
     */
 
         @see GetFaceName(), SetFamily()
     */


@@ -554,8 +593,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


@@ -563,6 +602,12 @@ 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).
         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).
+        If you want to serialize/deserialize a font in string form, you should use
+        GetNativeFontInfoDesc() and SetNativeFontInfo() instead.

 
         @see SetNativeFontInfo()
     */
 
         @see SetNativeFontInfo()
     */


@@ -570,6 +615,9 @@ public:
 
     /**
         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.


@@ -578,6 +626,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.
 


@@ -638,24 +701,26 @@ 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.
 */
 wxFont wxSMALL_FONT;
 
 /**
     ::wxNORMAL_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.
 */
 wxFont wxITALIC_FONT;
 
 /**
     A font identic to ::wxNORMAL_FONT except for the family used which is
     of the same size of ::wxNORMAL_FONT.
 */
 wxFont wxITALIC_FONT;
 
 /**
     A font identic to ::wxNORMAL_FONT except for the family used which is

-    wxFONTFAMILY_SWISS.
+    @c wxFONTFAMILY_SWISS.

 */
 wxFont wxSWISS_FONT;
 
 */
 wxFont wxSWISS_FONT;