implement wxNativeFontInfo::SetFamily for wxGTK with the same logic used by wxMSW; remove the now useless m_family from wxGTK's wxFont implementation; better docs for many wxFont functions (don't use typeface term; use the 'face name' one instead) and wxFontFamily

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@60119 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/font.h

@@ -8,22 +8,39 @@
 
 
 /**
-    Standard font families: these may be used only for the font creation, it
+    Standard font families: these are used mainly during wxFont creation to specify
-    doesn't make sense to query an existing font for its font family as,
+    the generic properties of the font without hardcoding in the sources a specific
-    especially if the font had been created from a native font description, it
+    face name.
-    may be unknown.
+
+    wxFontFamily thus allows to group the font face names of fonts with similar
+    properties. Most wxWidgets ports use lists of fonts for each font family
+    inspired by the data taken from http://www.codestyle.org/css/font-family.
 */
 enum wxFontFamily
 {
     wxFONTFAMILY_DEFAULT = wxDEFAULT,           //!< Chooses a default font.
+    
     wxFONTFAMILY_DECORATIVE = wxDECORATIVE,     //!< A decorative font.
     wxFONTFAMILY_ROMAN = wxROMAN,               //!< A formal, serif font.
     wxFONTFAMILY_SCRIPT = wxSCRIPT,             //!< A handwriting font.
     wxFONTFAMILY_SWISS = wxSWISS,               //!< A sans-serif font.
-    wxFONTFAMILY_MODERN = wxMODERN,             //!< A fixed pitch font.
+    
-    wxFONTFAMILY_TELETYPE = wxTELETYPE,         //!< A teletype font.
+    /// A fixed pitch font. Note that wxFont currently does not make distinctions
-    wxFONTFAMILY_MAX,
+    /// between @c wxFONTFAMILY_MODERN and @c wxFONTFAMILY_TELETYPE.
-    wxFONTFAMILY_UNKNOWN = wxFONTFAMILY_MAX
+    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
 };
 
 /**
@@ -273,8 +290,9 @@ public:
         @param pointSize
             Size in points. See SetPointSize() for more info.
         @param family
-            Font family, a generic way of referring to fonts without specifying actual
+            The font family: a generic portable way of referring to fonts without specifying a
-            facename. One of the ::wxFontFamily enumeration values.
+            facename. This parameter must be one of the ::wxFontFamily enumeration values.
+            If the @a faceName argument is provided, then it overrides the font family.
         @param style
             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
         @param weight
@@ -284,8 +302,8 @@ public:
             The value can be @true or @false.
             At present this has an effect on Windows and Motif 2.x only.
         @param faceName
-            An optional string specifying the actual typeface to be used.
+            An optional string specifying the face name to be used.
-            If it is an empty string, a default typeface will be chosen based on the family.
+            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:
@@ -318,8 +336,9 @@ public:
         @param pixelSize
             Size in pixels. See SetPixelSize() for more info.
         @param family
-            Font family, a generic way of referring to fonts without specifying actual
+            The font family: a generic portable way of referring to fonts without specifying a
-            facename. One of ::wxFontFamily enumeration values.
+            facename. This parameter must be one of the ::wxFontFamily enumeration values.
+            If the @a faceName argument is provided, then it overrides the font family.
         @param style
             One of @c wxFONTSTYLE_NORMAL, @c wxFONTSTYLE_SLANT and @c wxFONTSTYLE_ITALIC.
         @param weight
@@ -329,8 +348,8 @@ public:
             The value can be @true or @false.
             At present this has an effect on Windows and Motif 2.x only.
         @param faceName
-            An optional string specifying the actual typeface to be used.
+            An optional string specifying the face name to be used.
-            If it is an empty string, a default typeface will be chosen based on the family.
+            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:
@@ -360,8 +379,8 @@ public:
     /**
         Constructor from font description string.
 
-        This constructor uses SetNativeFontInfo() to initialize the font. If @a
+        This constructor uses SetNativeFontInfo() to initialize the font.
-        fontdesc is invalid font remains uninitialized, i.e. its IsOk() method
+        If @a fontdesc is invalid the font remains uninitialized, i.e. its IsOk() method
         will return @false.
      */
     wxFont(const wxString& fontdesc);
@@ -388,16 +407,20 @@ public:
     static wxFontEncoding GetDefaultEncoding();
 
     /**
-        Returns the typeface name associated with the font, or the empty string if
+        Returns the face name associated with the font, or the empty string if
-        there is no typeface information.
+        there is no face information.
 
         @see SetFaceName()
     */
     virtual wxString GetFaceName() const;
 
     /**
-        Gets the font family. See SetFamily() for a list of valid
+        Gets the font family.
-        family identifiers.
+        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()
     */
@@ -470,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.
+        
+        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;
 
@@ -522,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,
-                 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.
-                 If both the family and the facename are specified,
+                 If both the family and the facename are specified, wxWidgets will 
-                 wxWidgets will first search for the specific face, and
+                 first search for the specific face, and then for a font belonging 
-                 then for a font belonging to the same family.
+                 to the same family.
 
         @see GetFaceName(), SetFamily()
     */

src/gtk/font.cpp

@@ -93,7 +93,6 @@ protected:
     void InitFromNative();
 
 private:
-    wxFontFamily    m_family;
     wxFontEncoding  m_encoding;
     bool            m_underlined;
     bool            m_noAA;      // No anti-aliasing
@@ -118,7 +117,8 @@ void wxFontRefData::Init(int pointSize,
                          const wxString& faceName,
                          wxFontEncoding encoding)
 {
-    m_family = family == wxFONTFAMILY_DEFAULT ? wxFONTFAMILY_SWISS : family;
+    if (family == wxFONTFAMILY_DEFAULT)
+        family = wxFONTFAMILY_SWISS;
 
     m_underlined = underlined;
     m_encoding = encoding;
@@ -138,21 +138,7 @@ void wxFontRefData::Init(int pointSize,
     }
     else
     {
-        switch (m_family)
+        SetFamily(family);
-        {
-            case wxFONTFAMILY_MODERN:
-            case wxFONTFAMILY_TELETYPE:
-               pango_font_description_set_family( m_nativeFontInfo.description, "monospace" );
-               break;
-            case wxFONTFAMILY_ROMAN:
-               pango_font_description_set_family( m_nativeFontInfo.description, "serif" );
-               break;
-            case wxFONTFAMILY_SWISS:
-               // SWISS = sans serif
-            default:
-               pango_font_description_set_family( m_nativeFontInfo.description, "sans" );
-               break;
-        }
     }
 
     SetStyle( style == wxDEFAULT ? wxFONTSTYLE_NORMAL : style );
@@ -174,24 +160,6 @@ void wxFontRefData::InitFromNative()
     if (pango_size == 0)
         m_nativeFontInfo.SetPointSize(wxDEFAULT_FONT_SIZE);
 
-    wxString faceName = wxGTK_CONV_BACK_SYS(pango_font_description_get_family(desc));
-    if (faceName == wxT("monospace"))
-    {
-        m_family = wxFONTFAMILY_TELETYPE;
-    }
-    else if (faceName == wxT("sans"))
-    {
-        m_family = wxFONTFAMILY_SWISS;
-    }
-    else if (faceName == wxT("serif"))
-    {
-        m_family = wxFONTFAMILY_ROMAN;
-    }
-    else
-    {
-        m_family = wxFONTFAMILY_UNKNOWN;
-    }
-
     // Pango description are never underlined
     m_underlined = false;
 
@@ -202,7 +170,6 @@ void wxFontRefData::InitFromNative()
 wxFontRefData::wxFontRefData( const wxFontRefData& data )
              : wxGDIRefData()
 {
-    m_family = data.m_family;
     m_underlined = data.m_underlined;
     m_encoding = data.m_encoding;
     m_noAA = data.m_noAA;
@@ -268,25 +235,21 @@ bool wxFontRefData::SetPixelSize(const wxSize& pixelSize)
 
     return true;
 }
-
 */
 
 void wxFontRefData::SetFamily(wxFontFamily family)
 {
-    m_family = family;
+    m_nativeFontInfo.SetFamily(family);
-
-    // wxNativeInfo::SetFamily asserts because is currently not implemented---
-    // we just save the family here FIXME
 }
 
 void wxFontRefData::SetStyle(wxFontStyle style)
 {
-    m_nativeFontInfo.SetStyle((wxFontStyle)style);
+    m_nativeFontInfo.SetStyle(style);
 }
 
 void wxFontRefData::SetWeight(wxFontWeight weight)
 {
-    m_nativeFontInfo.SetWeight((wxFontWeight)weight);
+    m_nativeFontInfo.SetWeight(weight);
 }
 
 void wxFontRefData::SetUnderlined(bool underlined)
@@ -395,12 +358,7 @@ wxFontFamily wxFont::GetFamily() const
 {
     wxCHECK_MSG( IsOk(), wxFONTFAMILY_MAX, wxT("invalid font") );
 
-    wxFontFamily ret = M_FONTDATA->m_nativeFontInfo.GetFamily();
+    return M_FONTDATA->m_nativeFontInfo.GetFamily();
-
-    if (ret == wxFONTFAMILY_DEFAULT)
-        ret = M_FONTDATA->m_family;
-
-    return ret;
 }
 
 wxFontStyle wxFont::GetStyle() const

src/unix/fontutil.cpp

@@ -107,12 +107,10 @@ wxFontStyle wxNativeFontInfo::GetStyle() const
 
 wxFontWeight wxNativeFontInfo::GetWeight() const
 {
-#if 0
     // We seem to currently initialize only by string.
     // In that case PANGO_FONT_MASK_WEIGHT is always set.
-    if (!(pango_font_description_get_set_fields(description) & PANGO_FONT_MASK_WEIGHT))
+    // if (!(pango_font_description_get_set_fields(description) & PANGO_FONT_MASK_WEIGHT))
-        return wxFONTWEIGHT_NORMAL;
+    //    return wxFONTWEIGHT_NORMAL;
-#endif
 
     PangoWeight pango_weight = pango_font_description_get_weight( description );
 
@@ -143,7 +141,7 @@ wxString wxNativeFontInfo::GetFaceName() const
 
 wxFontFamily wxNativeFontInfo::GetFamily() const
 {
-    wxFontFamily ret = wxFONTFAMILY_DEFAULT;
+    wxFontFamily ret = wxFONTFAMILY_UNKNOWN;
 
     const char *family_name = pango_font_description_get_family( description );
 
@@ -154,11 +152,12 @@ wxFontFamily wxNativeFontInfo::GetFamily() const
         return ret;
     wxGtkString family_text(g_ascii_strdown(family_name, strlen(family_name)));
 
-    // Check for some common fonts, to salvage what we can from the current win32 centric wxFont API:
+    // Check for some common fonts, to salvage what we can from the current
-    if (strncmp( family_text, "monospace", 9 ) == 0)
+    // win32 centric wxFont API:
-        ret = wxFONTFAMILY_TELETYPE; // begins with "Monospace"
+    if (strncasecmp( family_text, "monospace", 9 ) == 0)
-    else if (strncmp( family_text, "courier", 7 ) == 0)
+        ret = wxFONTFAMILY_TELETYPE;    // begins with "Monospace"
-        ret = wxFONTFAMILY_TELETYPE; // begins with "Courier"
+    else if (strncasecmp( family_text, "courier", 7 ) == 0)
+        ret = wxFONTFAMILY_TELETYPE;    // begins with "Courier"
 #if defined(__WXGTK20__) || defined(HAVE_PANGO_FONT_FAMILY_IS_MONOSPACE)
     else
 #ifdef __WXGTK20__
@@ -191,29 +190,24 @@ wxFontFamily wxNativeFontInfo::GetFamily() const
         // Some gtk+ systems might query for a non-existing font from 
         // wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT) on initialization,
         // don't assert until wxSystemSettings::GetFont is checked for this - MR
-        // wxASSERT_MSG( family, 
+        // wxASSERT_MSG( family, "No appropriate PangoFontFamily found for ::description" );
-        //     "wxNativeFontInfo::GetFamily() - No appropriate PangoFontFamily found for ::description" );
-
-        //BCI: Cache the wxFontFamily inside the class. Validate cache with
-        //BCI: g_ascii_strcasecmp(pango_font_description_get_family(description), 
-        //                        pango_font_family_get_name(family)) == 0
 
         if (family != NULL && pango_font_family_is_monospace( family ))
             ret = wxFONTFAMILY_TELETYPE; // is deemed a monospace font by pango
     }
 #endif // GTK+ 2 || HAVE_PANGO_FONT_FAMILY_IS_MONOSPACE
 
-    if (ret == wxFONTFAMILY_DEFAULT)
+    if (ret == wxFONTFAMILY_UNKNOWN)
     {
-        if (strstr( family_text, "sans" ) != NULL) 
+        if (strstr( family_text, "sans" ) != NULL || strstr( family_text, "Sans" ) != NULL)
             // checked before serif, so that "* Sans Serif" fonts are detected correctly
-            ret = wxFONTFAMILY_SWISS; // contains "Sans"
+            ret = wxFONTFAMILY_SWISS;       // contains "Sans"
-        else if (strstr( family_text, "serif" ) != NULL)
+        else if (strstr( family_text, "serif" ) != NULL || strstr( family_text, "Serif" ) != NULL)
-            ret = wxFONTFAMILY_ROMAN; // contains "Serif"
+            ret = wxFONTFAMILY_ROMAN;       // contains "Serif"
-        else if (strncmp( family_text, "times", 5 ) == 0)
+        else if (strncasecmp( family_text, "times", 5 ) == 0)
-            ret = wxFONTFAMILY_ROMAN; // begins with "Times"
+            ret = wxFONTFAMILY_ROMAN;       // begins with "Times"
-        else if (strncmp( family_text, "old", 3 ) == 0)
+        else if (strncasecmp( family_text, "old", 3 ) == 0)
-            ret = wxFONTFAMILY_DECORATIVE; // begins with "Old" - "Old English", "Old Town"
+            ret = wxFONTFAMILY_DECORATIVE;  // begins with "Old" - "Old English", "Old Town"
     }
 
     return ret;
@@ -240,7 +234,7 @@ void wxNativeFontInfo::SetStyle(wxFontStyle style)
             pango_font_description_set_style( description, PANGO_STYLE_OBLIQUE );
             break;
         default:
-            wxFAIL_MSG( _T("unknown font style") );
+            wxFAIL_MSG( "unknown font style" );
             // fall through
         case wxFONTSTYLE_NORMAL:
             pango_font_description_set_style( description, PANGO_STYLE_NORMAL );
@@ -259,7 +253,7 @@ void wxNativeFontInfo::SetWeight(wxFontWeight weight)
             pango_font_description_set_weight(description, PANGO_WEIGHT_LIGHT);
             break;
         default:
-            wxFAIL_MSG( _T("unknown font weight") );
+            wxFAIL_MSG( "unknown font weight" );
             // fall through
         case wxFONTWEIGHT_NORMAL:
             pango_font_description_set_weight(description, PANGO_WEIGHT_NORMAL);
@@ -269,28 +263,84 @@ void wxNativeFontInfo::SetWeight(wxFontWeight weight)
 void wxNativeFontInfo::SetUnderlined(bool WXUNUSED(underlined))
 {
     // wxWindowDCImpl::DoDrawText will take care of rendering font with
-    // the underline attribute
+    // the underline attribute!
-    wxFAIL_MSG( _T("not implemented") );
+    wxFAIL_MSG( "not implemented" );
 }
 
 bool wxNativeFontInfo::SetFaceName(const wxString& facename)
 {
     pango_font_description_set_family(description, wxPANGO_CONV(facename));
-    
+
     // we return true because Pango doesn't tell us if the call failed or not;
     // instead on wxGTK wxFont::SetFaceName() will call wxFontBase::SetFaceName()
     // which does the check
     return true;
 }
 
-void wxNativeFontInfo::SetFamily(wxFontFamily WXUNUSED(family))
+void wxNativeFontInfo::SetFamily(wxFontFamily family)
 {
-    wxFAIL_MSG( _T("not implemented") );
+    wxArrayString facename;
+
+    // the list of fonts associated with a family was partially
+    // taken from http://www.codestyle.org/css/font-family
+
+    switch ( family )
+    {
+        case wxFONTFAMILY_SCRIPT:
+            // corresponds to the cursive font family in the page linked above
+            facename.Add(wxS("URW Chancery L"));
+            facename.Add(wxS("Comic Sans MS"));
+            break;
+
+        case wxFONTFAMILY_DECORATIVE:
+            // corresponds to the fantasy font family in the page linked above
+            facename.Add(wxS("Impact"));
+            break;
+
+        case wxFONTFAMILY_ROMAN:
+            // corresponds to the serif font family in the page linked above
+            facename.Add(wxS("Century Schoolbook L"));
+            facename.Add(wxS("URW Bookman L"));
+            facename.Add(wxS("URW Palladio L"));
+            facename.Add(wxS("DejaVu Serif"));
+            facename.Add(wxS("FreeSerif"));
+            facename.Add(wxS("Times New Roman"));
+            facename.Add(wxS("Times"));
+            break;
+
+        case wxFONTFAMILY_TELETYPE:
+        case wxFONTFAMILY_MODERN:
+            // corresponds to the monospace font family in the page linked above
+            facename.Add(wxS("DejaVu Sans Mono"));
+            facename.Add(wxS("Nimbus Mono L"));
+            facename.Add(wxS("Bitstream Vera Sans Mono"));
+            facename.Add(wxS("Andale Mono"));
+            facename.Add(wxS("Lucida Sans Typewriter"));
+            facename.Add(wxS("FreeMono"));
+            facename.Add(wxS("Courier New"));
+            facename.Add(wxS("Courier"));
+            break;
+
+        case wxFONTFAMILY_SWISS:
+        case wxFONTFAMILY_DEFAULT:
+        default:
+            // corresponds to the sans-serif font family in the page linked above
+            facename.Add(wxS("DejaVu Sans"));
+            facename.Add(wxS("URW Gothic L"));
+            facename.Add(wxS("Nimbus Sans L"));
+            facename.Add(wxS("Bitstream Vera Sans"));
+            facename.Add(wxS("Lucida Sans"));
+            facename.Add(wxS("Arial"));
+            facename.Add(wxS("FreeSans"));
+            break;
+    }
+
+    SetFaceName(facename);
 }
 
 void wxNativeFontInfo::SetEncoding(wxFontEncoding WXUNUSED(encoding))
 {
-    wxFAIL_MSG( _T("not implemented: Pango encoding is always UTF8") );
+    wxFAIL_MSG( "not implemented: Pango encoding is always UTF8" );
 }
 
 bool wxNativeFontInfo::FromString(const wxString& s)
@@ -306,15 +356,15 @@ bool wxNativeFontInfo::FromString(const wxString& s)
     // pango > 1.13. Note that the segfault could happen also for pointsize
     // smaller than this limit !!
     wxString str(s);
-    const size_t pos = str.find_last_of(_T(" "));
+    const size_t pos = str.find_last_of(wxS(" "));
     double size;
     if ( pos != wxString::npos && wxString(str, pos + 1).ToDouble(&size) )
     {
         wxString sizeStr;
         if ( size < 1 )
-            sizeStr = _T("1");
+            sizeStr = wxS("1");
         else if ( size >= 1E6 )
-            sizeStr = _T("1E6");
+            sizeStr = wxS("1E6");
 
         if ( !sizeStr.empty() )
         {

tests/font/fonttest.cpp

@@ -85,11 +85,14 @@ void FontTestCase::GetSet()
 
         // test Get/SetFamily()
 
-        test.SetFamily( wxFONTFAMILY_MODERN );
+        test.SetFamily( wxFONTFAMILY_ROMAN );
         CPPUNIT_ASSERT( test.IsOk() );
-        CPPUNIT_ASSERT_EQUAL( wxFONTFAMILY_MODERN, test.GetFamily() );
+        CPPUNIT_ASSERT( wxFONTFAMILY_ROMAN == test.GetFamily() || 
+                        wxFONTFAMILY_UNKNOWN == test.GetFamily() );
+            // note that there is always the possibility that GetFamily() returns
+            // wxFONTFAMILY_UNKNOWN so that we consider it as a valid return value
+
 
-        
         // test Get/SetEncoding()
 
         //test.SetEncoding( wxFONTENCODING_KOI8 );