Add support for multiline text and text alignment

Author: Starbuck5

buildconfig/stubs/pygame/__init__.pyi

@@ -181,6 +181,9 @@ from .constants import (
     FINGERDOWN as FINGERDOWN,
     FINGERMOTION as FINGERMOTION,
     FINGERUP as FINGERUP,
+    FONT_CENTER as FONT_CENTER,
+    FONT_LEFT as FONT_LEFT,
+    FONT_RIGHT as FONT_RIGHT,
     FULLSCREEN as FULLSCREEN,
     GL_ACCELERATED_VISUAL as GL_ACCELERATED_VISUAL,
     GL_ACCUM_ALPHA_SIZE as GL_ACCUM_ALPHA_SIZE,

buildconfig/stubs/pygame/constants.pyi

@@ -103,6 +103,9 @@ DROPTEXT: int
 FINGERDOWN: int
 FINGERMOTION: int
 FINGERUP: int
+FONT_CENTER: int
+FONT_LEFT: int
+FONT_RIGHT: int
 FULLSCREEN: int
 GL_ACCELERATED_VISUAL: int
 GL_ACCUM_ALPHA_SIZE: int

buildconfig/stubs/pygame/font.pyi

@@ -32,13 +32,15 @@ class Font:
     italic: bool
     underline: bool
     strikethrough: bool
+    align: int
     def __init__(self, name: Optional[FileArg], size: int) -> None: ...
     def render(
         self,
         text: Union[str, bytes, None],
         antialias: bool,
         color: ColorValue,
         background: Optional[ColorValue] = None,
+        wraplength: int = 0
     ) -> Surface: ...
     def size(self, text: Union[str, bytes]) -> Tuple[int, int]: ...
     def set_underline(self, value: bool) -> None: ...

buildconfig/stubs/pygame/locals.pyi

@@ -104,6 +104,9 @@ DROPTEXT: int
 FINGERDOWN: int
 FINGERMOTION: int
 FINGERUP: int
+FONT_CENTER: int
+FONT_LEFT: int
+FONT_RIGHT: int
 FULLSCREEN: int
 GL_ACCELERATED_VISUAL: int
 GL_ACCUM_ALPHA_SIZE: int

docs/reST/ref/font.rst

@@ -244,17 +244,32 @@ solves no longer exists, it will likely be removed in the future.
 
       .. ## Font.strikethrough ##
 
+   .. attribute:: align
+
+      | :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
+      `pygame.FONT_CENTER`. This controls the text alignment behavior for the
+      font.
+
+      Requires pygame built with SDL_ttf 2.20.0, as all official pygame
+      distributions are.
+
+      .. versionadded:: 2.1.4
+
+      .. ## Font.align ##
+
    .. method:: render
 
       | :sl:`draw text on a new Surface`
-      | :sg:`render(text, antialias, color, background=None) -> Surface`
+      | :sg:`render(text, antialias, color, background=None, wraplength=0) -> Surface`
 
       This creates a new Surface with the specified text rendered on it. 
       :mod:`pygame.font` provides no way to directly draw text on an existing
       Surface: instead you must use :func:`Font.render` to create an image
       (Surface) of the text, then blit this image onto another Surface.
 
-      The text can only be a single line: newline characters are not rendered.
       Null characters ('\x00') raise a TypeError. Both Unicode and char (byte)
       strings are accepted. For Unicode strings only UCS-2 characters
       ('\\u0001' to '\\uFFFF') were previously supported and any greater
@@ -266,6 +281,10 @@ solves no longer exists, it will likely be removed in the future.
       to use for the text background. If no background is passed the area
       outside the text will be transparent.
 
+      The `wraplength` argument describes the width (in pixels) a line of text
+      should be before wrapping to a new line. See
+      :attr:`pygame.font.Font.align` for line-alignment settings.
+
       The Surface returned will be of the dimensions required to hold the text.
       (the same as those returned by :func:`Font.size`). If an empty string is passed
       for the text, a blank surface will be returned that is zero pixel wide and
@@ -285,9 +304,6 @@ solves no longer exists, it will likely be removed in the future.
       cause the resulting image to maintain transparency information by
       colorkey rather than (much less efficient) alpha values.
 
-      If you render '\\n' an unknown char will be rendered. Usually a
-      rectangle. Instead you need to handle newlines yourself.
-
       Font rendering is not thread safe: only a single thread can render text
       at any time.
 
@@ -296,6 +312,11 @@ solves no longer exists, it will likely be removed in the future.
         pygame supports rendering UCS4 unicode including more languages and
         emoji.
 
+      .. versionchanged:: 2.1.4 newline characters now will break text into
+         multiple lines.
+
+      .. versionadded:: 2.1.4 wraplength parameter
+
       .. ## Font.render ##
 
    .. method:: size

src_c/constants.c

@@ -623,6 +623,11 @@ MODINIT_DEFINE(constants)
     // https://github.com/pygame-community/pygame-ce/issues/1845
     DEC_CONSTS(IS_CE, 1)
 
+    /* Font alignment constants */
+    DEC_CONSTS(FONT_LEFT, 0);
+    DEC_CONSTS(FONT_CENTER, 1);
+    DEC_CONSTS(FONT_RIGHT, 2);
+
     if (PyModule_AddObject(module, "__all__", all_list)) {
         Py_DECREF(all_list);
         Py_DECREF(module);

src_c/doc/font_doc.h

@@ -13,7 +13,8 @@
 #define DOC_FONTITALIC "italic -> bool\nGets or sets whether the font should be rendered in (faked) italics."
 #define DOC_FONTUNDERLINE "underline -> bool\nGets or sets whether the font should be rendered with an underline."
 #define DOC_FONTSTRIKETHROUGH "strikethrough -> bool\nGets or sets whether the font should be rendered with a strikethrough."
-#define DOC_FONTRENDER "render(text, antialias, color, background=None) -> Surface\ndraw text on a new Surface"
+#define DOC_FONTALIGN "align -> int\nSet how rendered text is aligned when given a wrap length"
+#define DOC_FONTRENDER "render(text, antialias, color, background=None, wraplength=0) -> Surface\ndraw text on a new Surface"
 #define DOC_FONTSIZE "size(text) -> (width, height)\ndetermine the amount of space needed to render text"
 #define DOC_FONTSETUNDERLINE "set_underline(bool) -> None\ncontrol if text is rendered with an underline"
 #define DOC_FONTGETUNDERLINE "get_underline() -> bool\ncheck if text will be rendered with an underline"
@@ -92,8 +93,12 @@ pygame.font.Font.strikethrough
  strikethrough -> bool
 Gets or sets whether the font should be rendered with a strikethrough.
 
+pygame.font.Font.align
+ align -> int
+Set how rendered text is aligned when given a wrap length
+
 pygame.font.Font.render
- render(text, antialias, color, background=None) -> Surface
+ render(text, antialias, color, background=None, wraplength=0) -> Surface
 draw text on a new Surface
 
 pygame.font.Font.size

src_c/font.c

@@ -72,6 +72,18 @@ static const char resourcefunc_name[] = "getResource";
 #endif
 static const char font_defaultname[] = "freesansbold.ttf";
 
+#ifndef SDL_TTF_VERSION_ATLEAST
+/**
+ *  This macro will evaluate to true if compiled with SDL_ttf at least X.Y.Z.
+ *  New in SDL_ttf 2.0.15 so here it is in pygame for compat
+ */
+#define SDL_TTF_VERSION_ATLEAST(X, Y, Z)                          \
+    ((SDL_TTF_MAJOR_VERSION >= X) &&                              \
+     (SDL_TTF_MAJOR_VERSION > X || SDL_TTF_MINOR_VERSION >= Y) && \
+     (SDL_TTF_MAJOR_VERSION > X || SDL_TTF_MINOR_VERSION > Y ||   \
+      SDL_TTF_PATCHLEVEL >= Z))
+#endif
+
 /*
  */
 #if !SDL_TTF_VERSION_ATLEAST(2, 0, 15)
@@ -393,6 +405,52 @@ font_setter_strikethrough(PyObject *self, PyObject *value, void *closure)
     return 0;
 }
 
+/* Implements getter for the align attribute */
+static PyObject *
+font_getter_align(PyObject *self, void *closure)
+{
+#if SDL_TTF_VERSION_ATLEAST(2, 20, 0)
+    TTF_Font *font = PyFont_AsFont(self);
+    return PyLong_FromLong(TTF_GetFontWrappedAlign(font));
+#else
+    return RAISE(pgExc_SDLError,
+                 "pygame.font not compiled with a new enough SDL_ttf version. "
+                 "Needs SDL_ttf 2.20.0 or above.");
+#endif
+}
+
+/* Implements setter for the align attribute */
+static int
+font_setter_align(PyObject *self, PyObject *value, void *closure)
+{
+#if SDL_TTF_VERSION_ATLEAST(2, 20, 0)
+    TTF_Font *font = PyFont_AsFont(self);
+
+    DEL_ATTR_NOT_SUPPORTED_CHECK("align", value);
+
+    long val = PyLong_AsLong(value);
+    if (val == -1 && PyErr_Occurred()) {
+        PyErr_SetString(PyExc_TypeError, "font.align should be an integer");
+        return -1;
+    }
+
+    if (val < 0 || val > 2) {
+        PyErr_SetString(
+            pgExc_SDLError,
+            "font.align should be FONT_LEFT, FONT_CENTER, or FONT_RIGHT");
+        return -1;
+    }
+
+    TTF_SetFontWrappedAlign(font, val);
+    return 0;
+#else
+    PyErr_SetString(pgExc_SDLError,
+                    "pygame.font not compiled with a new enough SDL_ttf "
+                    "version. Needs SDL_ttf 2.20.0 or above.");
+    return -1;
+#endif
+}
+
 /* Implements get_strikethrough() */
 static PyObject *
 font_get_strikethrough(PyObject *self, PyObject *args)
@@ -425,9 +483,10 @@ font_render(PyObject *self, PyObject *args)
     Uint8 rgba[] = {0, 0, 0, 0};
     SDL_Surface *surf;
     const char *astring = "";
+    int wraplength = 0;
 
-    if (!PyArg_ParseTuple(args, "OpO|O", &text, &antialias, &fg_rgba_obj,
-                          &bg_rgba_obj)) {
+    if (!PyArg_ParseTuple(args, "OpO|Oi", &text, &antialias, &fg_rgba_obj,
+                          &bg_rgba_obj, &wraplength)) {
         return NULL;
     }
 
@@ -452,6 +511,11 @@ font_render(PyObject *self, PyObject *args)
         return RAISE_TEXT_TYPE_ERROR();
     }
 
+    if (wraplength < 0) {
+        return RAISE(PyExc_ValueError,
+                     "wraplength parameter must be positive");
+    }
+
     if (PyUnicode_Check(text)) {
         Py_ssize_t _size = -1;
         astring = PyUnicode_AsUTF8AndSize(text, &_size);
@@ -484,19 +548,34 @@ font_render(PyObject *self, PyObject *args)
 #if !SDL_TTF_VERSION_ATLEAST(2, 0, 15)
         if (utf_8_needs_UCS_4(astring)) {
             return RAISE(PyExc_UnicodeError,
-                         "A Unicode character above '\\uFFFF' was found;"
+                         "a Unicode character above '\\uFFFF' was found;"
                          " not supported with SDL_ttf version below 2.0.15");
         }
 #endif
 
         if (antialias && bg_rgba_obj == Py_None) {
+#if SDL_TTF_VERSION_ATLEAST(2, 0, 18)
+            surf = TTF_RenderUTF8_Blended_Wrapped(font, astring, foreg,
+                                                  wraplength);
+#else
             surf = TTF_RenderUTF8_Blended(font, astring, foreg);
+#endif
         }
         else if (antialias) {
+#if SDL_TTF_VERSION_ATLEAST(2, 0, 18)
+            surf = TTF_RenderUTF8_Shaded_Wrapped(font, astring, foreg, backg,
+                                                 wraplength);
+#else
             surf = TTF_RenderUTF8_Shaded(font, astring, foreg, backg);
+#endif
         }
         else {
+#if SDL_TTF_VERSION_ATLEAST(2, 0, 18)
+            surf =
+                TTF_RenderUTF8_Solid_Wrapped(font, astring, foreg, wraplength);
+#else
             surf = TTF_RenderUTF8_Solid(font, astring, foreg);
+#endif
             /* If an explicit background was provided and the rendering options
             resolve to Render_Solid, that needs to be explicitly handled. */
             if (surf != NULL && bg_rgba_obj != Py_None) {
@@ -679,6 +758,8 @@ static PyGetSetDef font_getsets[] = {
      DOC_FONTUNDERLINE, NULL},
     {"strikethrough", (getter)font_getter_strikethrough,
      (setter)font_setter_strikethrough, DOC_FONTSTRIKETHROUGH, NULL},
+    {"align", (getter)font_getter_align, (setter)font_setter_align,
+     DOC_FONTALIGN, NULL},
     {NULL, NULL, NULL, NULL, NULL}};
 
 static PyMethodDef font_methods[] = {

test/font_test.py

@@ -268,6 +268,28 @@ def test_render_args(self):
             self.assertEqual(tuple(screen.get_at((0, 0)))[:3], (10, 10, 10))
             self.assertEqual(tuple(screen.get_at(font_rect.topleft))[:3], (10, 10, 10))
 
+    def test_render_multiline(self):
+        if pygame_font.__name__ == "pygame.ftfont":
+            return
+
+        if pygame.font.get_sdl_ttf_version() < (2, 0, 18):
+            # When the SDL_TTF version is too low, it just ignores the
+            # line wrap parameter and newlines
+            return
+
+        f = pygame_font.Font(None, 20)
+        one_line = f.render("hello", True, "black", "white", 200)
+        two_lines = f.render("hello\nworld", True, "black", "white", 200)
+        self.assertGreater(two_lines.get_height(), one_line.get_height())
+
+        one_line = f.render("hello", True, "black", None, 200)
+        two_lines = f.render("hello\nworld", True, "black", None, 200)
+        self.assertGreater(two_lines.get_height(), one_line.get_height())
+
+        one_line = f.render("hello", False, "black", None, 200)
+        two_lines = f.render("hello\nworld", False, "black", None, 200)
+        self.assertGreater(two_lines.get_height(), one_line.get_height())
+
 
 @unittest.skipIf(IS_PYPY, "pypy skip known failure")  # TODO
 class FontTypeTest(unittest.TestCase):
@@ -304,7 +326,7 @@ def test_get_height(self):
         self.assertTrue(isinstance(height, int))
         self.assertTrue(height > 0)
         s = f.render("X", False, (255, 255, 255))
-        self.assertTrue(s.get_size()[1] == height)
+        self.assertAlmostEqual(s.get_height(), height, delta=3)
 
     def test_get_linesize(self):
         # Checking linesize would need a custom test font to do properly.
@@ -484,6 +506,25 @@ def test_set_strikethrough_property(self):
             f.strikethrough = False
             self.assertFalse(f.strikethrough)
 
+    def test_set_align_property(self):
+        if pygame_font.__name__ == "pygame.ftfont":
+            return
+
+        f = pygame_font.Font(None, 20)
+
+        if pygame.font.get_sdl_ttf_version() < (2, 20, 0):
+            with self.assertRaises(pygame.error):
+                f.align = pygame.FONT_CENTER
+            return
+
+        self.assertEqual(f.align, pygame.FONT_LEFT)
+        f.align = pygame.FONT_CENTER
+        self.assertEqual(f.align, pygame.FONT_CENTER)
+        f.align = pygame.FONT_RIGHT
+        self.assertEqual(f.align, pygame.FONT_RIGHT)
+        f.align = pygame.FONT_LEFT
+        self.assertEqual(f.align, pygame.FONT_LEFT)
+
     def test_size(self):
         f = pygame_font.Font(None, 20)
         text = "Xg"