Merge pull request #2175 from dr0id/enhancements/font/stylename

Starbuck5 · web-flow · commit 6d0c42e6aba1 · 2023-07-29T00:02:15.000-07:00
add style_name property to font and freetype font
diff --git a/README.rst b/README.rst
@@ -148,7 +148,7 @@ Dependency versions:
 +----------+------------------------+
 | SDL_image| >= 2.0.2               |
 +----------+------------------------+
-| SDL_ttf  | >= 2.0.11              |
+| SDL_ttf  | >= 2.0.12              |
 +----------+------------------------+
 | SDL_gfx  | (Optional, vendored in)|
 +----------+------------------------+
diff --git a/buildconfig/stubs/pygame/font.pyi b/buildconfig/stubs/pygame/font.pyi
@@ -34,14 +34,15 @@ class Font:
     underline: bool
     strikethrough: bool
     align: int
+    style_name: str
     def __init__(self, filename: Optional[FileArg] = None, size: int = 20) -> None: ...
     def render(
         self,
         text: Union[str, bytes, None],
         antialias: bool,
         color: ColorValue,
         bgcolor: Optional[ColorValue] = None,
-        wraplength: int = 0
+        wraplength: int = 0,
     ) -> Surface: ...
     def size(self, text: Union[str, bytes]) -> Tuple[int, int]: ...
     def set_underline(self, value: bool) -> None: ...
diff --git a/buildconfig/stubs/pygame/freetype.pyi b/buildconfig/stubs/pygame/freetype.pyi
@@ -45,6 +45,7 @@ class Font:
     ascender: int
     descender: int
     style: int
+    style_name: str
     underline: bool
     strong: bool
     oblique: bool
diff --git a/docs/reST/ref/font.rst b/docs/reST/ref/font.rst
@@ -211,6 +211,23 @@ solves no longer exists, it will likely be removed in the future.
 
       .. ## Font.name ##
 
+   .. attribute:: style_name
+
+      | :sl:`Gets the font's style_name.`
+      | :sg:`style_name -> str`
+
+      Read only. Returns the font's style name. Style names are arbitrary, can be an empty string. 
+      Here are some examples:
+
+        'Black', 'Bold', 'Bold Italic', 'BoldOblique', 'Book', 'BookOblique', 'Condensed', 'Condensed Oblique',
+        'ExtraLight', 'Italic', 'Light', 'LightOblique', 'Medium', 'MediumOblique', 'Oblique', 'Regular',
+        'Semibold', 'Semilight', 'Slanted'
+
+
+      .. versionadded:: 2.3.1
+
+      .. ## Font.style_name ##
+
    .. attribute:: italic
 
       | :sl:`Gets or sets whether the font should be rendered in (faked) italics.`
@@ -263,7 +280,7 @@ solves no longer exists, it will likely be removed in the future.
 
    .. attribute:: align
 
-      | :sl:`Set how rendered text is aligned when given a wrap length`
+      | :sl:`Set how rendered text is aligned when given a wrap length.`
       | :sg:`align -> int`
 
       Can be set to `pygame.FONT_LEFT`, `pygame.FONT_RIGHT`, or
diff --git a/docs/reST/ref/freetype.rst b/docs/reST/ref/freetype.rst
@@ -224,6 +224,22 @@ loaded. This module must be imported explicitly to be used. ::
       Read only. Returns the real (long) name of the font, as
       recorded in the font file.
 
+   .. attribute:: style_name
+
+      | :sl:`Gets the font's style_name.`
+      | :sg:`style_name -> str`
+
+      Read only. Returns the font's style name. Style names are arbitrary, can be an empty string. 
+      Here are some examples:
+
+        'Black', 'Bold', 'Bold Italic', 'BoldOblique', 'Book', 'BookOblique', 'Condensed', 'Condensed Oblique',
+        'ExtraLight', 'Italic', 'Light', 'LightOblique', 'Medium', 'MediumOblique', 'Oblique', 'Regular',
+        'Semibold', 'Semilight', 'Slanted'
+
+      .. versionadded:: 2.3.1
+
+      .. ## Font.style_name ##
+
    .. attribute:: path
 
       | :sl:`Font file path`
diff --git a/docs/readmes/README.fr.rst b/docs/readmes/README.fr.rst
@@ -152,7 +152,7 @@ Versions des dépendances:
 +----------+------------------------+
 | SDL_image| >= 2.0.2               |
 +----------+------------------------+
-| SDL_ttf  | >= 2.0.11              |
+| SDL_ttf  | >= 2.0.12              |
 +----------+------------------------+
 | SDL_gfx  | (Optional, vendored in)|
 +----------+------------------------+
diff --git a/docs/readmes/README.zh-cn.rst b/docs/readmes/README.zh-cn.rst
@@ -113,7 +113,7 @@ pygame显然依赖于SDL和Python。此外pygame还嵌入了几个较小的库
 +----------+------------------------+
 | SDL_image| >= 2.0.2               |
 +----------+------------------------+
-| SDL_ttf  | >= 2.0.11              |
+| SDL_ttf  | >= 2.0.12              |
 +----------+------------------------+
 | SDL_gfx  | （可选，内置）         |
 +----------+------------------------+
diff --git a/src_c/_freetype.c b/src_c/_freetype.c
@@ -115,6 +115,8 @@ _ftfont_setstyle(pgFontObject *, PyObject *, void *);
 static PyObject *
 _ftfont_getname(pgFontObject *, void *);
 static PyObject *
+_ftfont_getstylename(pgFontObject *, void *);
+static PyObject *
 _ftfont_getpath(pgFontObject *, void *);
 static PyObject *
 _ftfont_getscalable(pgFontObject *, void *);
@@ -550,6 +552,8 @@ static PyGetSetDef _ftfont_getsets[] = {
     {"descender", (getter)_ftfont_getfontmetric, 0,
      DOC_FREETYPE_FONT_DESCENDER, (void *)_PGFT_Font_GetDescender},
     {"name", (getter)_ftfont_getname, 0, DOC_FREETYPE_FONT_NAME, 0},
+    {"style_name", (getter)_ftfont_getstylename, 0,
+     DOC_FREETYPE_FONT_STYLENAME, 0},
     {"path", (getter)_ftfont_getpath, 0, DOC_FREETYPE_FONT_PATH, 0},
     {"scalable", (getter)_ftfont_getscalable, 0, DOC_FREETYPE_FONT_SCALABLE,
      0},
@@ -1097,7 +1101,21 @@ _ftfont_getname(pgFontObject *self, void *closure)
         const char *name = _PGFT_Font_GetName(self->freetype, self);
         return name ? PyUnicode_FromString(name) : 0;
     }
-    return PyObject_Repr((PyObject *)self);
+
+    PyErr_SetString(PyExc_AttributeError, "<uninitialized Font object>");
+    return NULL;
+}
+
+static PyObject *
+_ftfont_getstylename(pgFontObject *self, void *closure)
+{
+    if (pgFont_IS_ALIVE(self)) {
+        const char *stylename = _PGFT_Font_GetStyleName(self->freetype, self);
+        return stylename ? PyUnicode_FromString(stylename) : 0;
+    }
+
+    PyErr_SetString(PyExc_AttributeError, "<uninitialized Font object>");
+    return NULL;
 }
 
 static PyObject *
diff --git a/src_c/doc/font_doc.h b/src_c/doc/font_doc.h
@@ -11,10 +11,11 @@
 #define DOC_FONT_FONT "Font(filename=None, size=20) -> Font\nFont(filename, size) -> Font\nFont(pathlib.Path, size) -> Font\nFont(object, size) -> Font\ncreate a new Font object from a file"
 #define DOC_FONT_FONT_BOLD "bold -> bool\nGets or sets whether the font should be rendered in (faked) bold."
 #define DOC_FONT_FONT_NAME "name -> str\nGets the font's name."
+#define DOC_FONT_FONT_STYLENAME "style_name -> str\nGets the font's style_name."
 #define DOC_FONT_FONT_ITALIC "italic -> bool\nGets or sets whether the font should be rendered in (faked) italics."
 #define DOC_FONT_FONT_UNDERLINE "underline -> bool\nGets or sets whether the font should be rendered with an underline."
 #define DOC_FONT_FONT_STRIKETHROUGH "strikethrough -> bool\nGets or sets whether the font should be rendered with a strikethrough."
-#define DOC_FONT_FONT_ALIGN "align -> int\nSet how rendered text is aligned when given a wrap length"
+#define DOC_FONT_FONT_ALIGN "align -> int\nSet how rendered text is aligned when given a wrap length."
 #define DOC_FONT_FONT_RENDER "render(text, antialias, color, bgcolor=None, wraplength=0) -> Surface\ndraw text on a new Surface"
 #define DOC_FONT_FONT_SIZE "size(text) -> (width, height)\ndetermine the amount of space needed to render text"
 #define DOC_FONT_FONT_SETUNDERLINE "set_underline(bool) -> None\ncontrol if text is rendered with an underline"
diff --git a/src_c/doc/freetype_doc.h b/src_c/doc/freetype_doc.h
@@ -13,6 +13,7 @@
 #define DOC_FREETYPE_GETDEFAULTFONT "get_default_font() -> string\nGet the filename of the default font"
 #define DOC_FREETYPE_FONT "Font(file, size=0, font_index=0, resolution=0, ucs4=False) -> Font\nFont(pathlib.Path) -> Font\nCreate a new Font instance from a supported font file."
 #define DOC_FREETYPE_FONT_NAME "name -> string\nProper font name."
+#define DOC_FREETYPE_FONT_STYLENAME "style_name -> str\nGets the font's style_name."
 #define DOC_FREETYPE_FONT_PATH "path -> unicode\nFont file path"
 #define DOC_FREETYPE_FONT_SIZE "size -> float\nsize -> (float, float)\nThe default point size used in rendering"
 #define DOC_FREETYPE_FONT_GETRECT "get_rect(text, style=STYLE_DEFAULT, rotation=0, size=0) -> rect\nReturn the size and offset of rendered text"
diff --git a/src_c/font.c b/src_c/font.c
@@ -48,6 +48,10 @@
 #define RAISE_TEXT_TYPE_ERROR() \
     RAISE(PyExc_TypeError, "text must be a unicode or bytes");
 
+#define RAISE_FONT_QUIT_ERROR() \
+    RAISE(pgExc_SDLError,       \
+          "Invalid font (font module quit since font created)");
+
 /* For filtering out UCS-4 and larger characters when Python is
  * built with Py_UNICODE_WIDE.
  */
@@ -491,8 +495,7 @@ font_render(PyObject *self, PyObject *args, PyObject *kwds)
     int wraplength = 0;
 
     if (!PgFont_GenerationCheck(self)) {
-        return RAISE(pgExc_SDLError,
-                     "Invalid font (font module quit since font created)");
+        return RAISE_FONT_QUIT_ERROR()
     }
 
     static char *kwlist[] = {"text",    "antialias",  "color",
@@ -620,8 +623,7 @@ font_size(PyObject *self, PyObject *text)
     const char *string;
 
     if (!PgFont_GenerationCheck(self)) {
-        return RAISE(pgExc_SDLError,
-                     "Invalid font (font module quit since font created)");
+        return RAISE_FONT_QUIT_ERROR();
     }
 
     if (PyUnicode_Check(text)) {
@@ -653,10 +655,26 @@ font_size(PyObject *self, PyObject *text)
 static PyObject *
 font_getter_name(PyObject *self, void *closure)
 {
+    if (!PgFont_GenerationCheck(self)) {
+        return RAISE_FONT_QUIT_ERROR();
+    }
+
     TTF_Font *font = PyFont_AsFont(self);
     const char *font_name = TTF_FontFaceFamilyName(font);
 
-    return PyUnicode_FromString(font_name);
+    return PyUnicode_FromString(font_name ? font_name : "");
+}
+
+static PyObject *
+font_getter_style_name(PyObject *self, void *closure)
+{
+    if (!PgFont_GenerationCheck(self)) {
+        return RAISE_FONT_QUIT_ERROR();
+    }
+
+    TTF_Font *font = PyFont_AsFont(self);
+    const char *font_style_name = TTF_FontFaceStyleName(font);
+    return PyUnicode_FromString(font_style_name ? font_style_name : "");
 }
 
 static PyObject *
@@ -677,10 +695,8 @@ font_metrics(PyObject *self, PyObject *textobj)
     Uint16 ch;
     PyObject *temp;
     int surrogate;
-
     if (!PgFont_GenerationCheck(self)) {
-        return RAISE(pgExc_SDLError,
-                     "Invalid font (font module quit since font created)");
+        return RAISE_FONT_QUIT_ERROR();
     }
 
     if (PyUnicode_Check(textobj)) {
@@ -864,6 +880,8 @@ font_set_direction(PyObject *self, PyObject *arg, PyObject *kwarg)
  */
 static PyGetSetDef font_getsets[] = {
     {"name", (getter)font_getter_name, NULL, DOC_FONT_FONT_NAME, NULL},
+    {"style_name", (getter)font_getter_style_name, NULL,
+     DOC_FONT_FONT_STYLENAME, NULL},
     {"bold", (getter)font_getter_bold, (setter)font_setter_bold,
      DOC_FONT_FONT_BOLD, NULL},
     {"italic", (getter)font_getter_italic, (setter)font_setter_italic,
diff --git a/src_c/freetype/ft_wrap.c b/src_c/freetype/ft_wrap.c
@@ -155,6 +155,19 @@ _PGFT_Font_GetName(FreeTypeInstance *ft, pgFontObject *fontobj)
     return font->family_name ? font->family_name : "";
 }
 
+const char *
+_PGFT_Font_GetStyleName(FreeTypeInstance *ft, pgFontObject *fontobj)
+{
+    FT_Face font;
+    font = _PGFT_GetFont(ft, fontobj);
+
+    if (!font) {
+        PyErr_SetString(pgExc_SDLError, _PGFT_GetError(ft));
+        return 0;
+    }
+    return font->style_name ? font->style_name : "";
+}
+
 /* All the font metric functions raise an exception and return 0 on an error.
  * It is up to the caller to check PyErr_Occurred for a 0 return value.
  */
diff --git a/src_c/freetype/ft_wrap.h b/src_c/freetype/ft_wrap.h
@@ -283,6 +283,8 @@ _PGFT_Font_GetAvailableSize(FreeTypeInstance *, pgFontObject *, long, long *,
                             long *, long *, double *, double *);
 const char *
 _PGFT_Font_GetName(FreeTypeInstance *, pgFontObject *);
+const char *
+_PGFT_Font_GetStyleName(FreeTypeInstance *, pgFontObject *);
 int
 _PGFT_TryLoadFont_Filename(FreeTypeInstance *, pgFontObject *, const char *,
                            long);
diff --git a/test/font_test.py b/test/font_test.py
@@ -581,6 +581,20 @@ def test_set_name():
 
         self.assertRaises(AttributeError, test_set_name)
 
+    def test_font_style_name(self):
+        f = pygame_font.Font(None, 20)
+        self.assertNotEqual(f.style_name, "")
+        self.assertNotEqual(f.style_name, None)
+        self.assertIsInstance(f.style_name, str)
+
+    def test_font_style_name_is_readonly(self):
+        f = pygame_font.Font(None, 20)
+
+        def _set_style_name():
+            f.style_name = "Say my other name."
+
+        self.assertRaises(AttributeError, _set_style_name)
+
     def test_font_file_not_found(self):
         # A per BUG reported by Bo Jangeborg on pygame-user mailing list,
         # http://www.mail-archive.com/pygame-users@seul.org/msg11675.html
