diff --git a/README.md b/README.md index cc4ff54..01b5ffe 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Public `Graphik` methods: - `getGameDisplay()` — returns the bound display surface. - `getVersion()` — returns the installed graphik version string. - `drawRectangle(xpos, ypos, width, height, color)` — `xpos`/`ypos` are the rectangle's top-left corner. -- `drawText(text, xpos, ypos, size, color)` — `xpos`/`ypos` are the **center** of the rendered text, not its top-left corner. This differs from `drawRectangle`, `drawButton` and `drawImage`, which all position their top-left corner at the given coordinates. Glyph edges are antialiased, blending with whatever is already on the surface. +- `drawText(text, xpos, ypos, size, color)` — `xpos`/`ypos` are the **center** of the rendered text, not its top-left corner. This differs from `drawRectangle`, `drawButton` and `drawImage`, which all position their top-left corner at the given coordinates. Glyph edges are antialiased, blending with whatever is already on the surface. The text is always rendered as a single line — a `"\n"` is not a line break, so multi-line text needs one call per line — and a null character (`"\0"`) raises `ValueError` before anything is painted. - `drawButton(xpos, ypos, width, height, colorBox, colorText, sizeText, text, function)` — draws a rectangle and centered text, and calls `function()` on every call where the mouse is held inside the button with button 1 down (there is no click-edge detection, so a held-down mouse fires `function()` once per call, not once per click). Callers wanting once-per-click semantics must debounce on their side. The clickable region is exactly the drawn box — `xpos` through `xpos + width - 1`, and `ypos` through `ypos + height - 1` — so buttons laid out edge to edge share no clickable coordinate. The hit test uses `pygame.mouse.get_pos()`, which is in window coordinates, so this only holds when the `Graphik` is bound to the display itself (or another surface whose top-left sits at the window's origin): bound to a subsurface or an off-screen surface blitted elsewhere, the box is painted at that surface's position but stays clickable at `xpos`/`ypos` relative to the window. The label is not clipped to the box: one too large for it overflows past the box edges, and that overflow is painted but not clickable. Reading the mouse needs the video system, so unlike `drawRectangle` and `drawText` it raises `pygame.error` (after painting) when neither `pygame.init()` nor `pygame.display.init()` has been called, even for an off-screen surface; no display mode is needed. - `drawImage(filePath, xpos, ypos, width, height)` — caches the loaded and scaled surface by `filePath`, so an image edited on disk mid-run will not be picked up until the process restarts. Only the most recently requested size is kept per path, so drawing the same file at two alternating sizes rescales it on every call. Unlike the other draw methods, it raises `pygame.error` unless a display mode has been set with `pygame.display.set_mode`, even when the `Graphik` is bound to an off-screen surface. Only the first load of a path needs one: a path already in the cache keeps drawing to an off-screen surface with no display mode set. diff --git a/src/main/python/preponderous/graphik/graphik.py b/src/main/python/preponderous/graphik/graphik.py index fc043cc..54336d4 100644 --- a/src/main/python/preponderous/graphik/graphik.py +++ b/src/main/python/preponderous/graphik/graphik.py @@ -155,7 +155,10 @@ def drawText(self, text, xpos, ypos, size, color): surface, so a pixel-exact check should expect colors besides ``color``. Args: - text: The string to render. + text: The string to render, always as a single line: a ``"\\n"`` + is not a line break, so multi-line text needs one call per + line. A null character (``"\\0"``) raises ``ValueError`` + before anything is painted. xpos: X coordinate the text is centered on, in pixels. ypos: Y coordinate the text is centered on, in pixels. size: Font size in points, as an ``int`` (a float raises diff --git a/src/test/python/preponderous/graphik/test_graphik.py b/src/test/python/preponderous/graphik/test_graphik.py index 9a98448..18e7e79 100644 --- a/src/test/python/preponderous/graphik/test_graphik.py +++ b/src/test/python/preponderous/graphik/test_graphik.py @@ -717,6 +717,44 @@ def test_draw_text_accepts_an_empty_string_and_paints_nothing(): assert all(_rgb(display, (x, y)) == Graphik.green for x in range(width) for y in range(height)) +def test_draw_text_does_not_break_lines_at_a_newline(): + # drawText renders a single line: a "\n" is not a line break, so text + # meant for two lines stays on one, and a caller wanting several lines + # must call drawText once per line. If it did break, the ink of "A\nB" + # would span two line heights; on one line it fits within a single one. + graphik = _make_graphik((200, 200)) + display = graphik.getGameDisplay() + display.fill(Graphik.black) + + size = 20 + graphik.drawText("A\nB", 100, 100, size, Graphik.white) + + width, height = display.get_size() + inkedRows = [ + y + for y in range(height) + if any(_rgb(display, (x, y)) != Graphik.black for x in range(width)) + ] + assert inkedRows, "drawText left the surface untouched" + lineHeight = pygame.font.Font("freesansbold.ttf", size).get_linesize() + assert max(inkedRows) - min(inkedRows) < lineHeight + + +def test_draw_text_with_a_null_character_raises_value_error_and_paints_nothing(): + # pygame refuses to render text containing "\0", and drawText does not + # filter it out, so the ValueError reaches the caller before anything is + # blitted -- including the characters on either side of it. + graphik = _make_graphik((40, 40)) + display = graphik.getGameDisplay() + display.fill(Graphik.green) + + with pytest.raises(ValueError): + graphik.drawText("A\0B", 20, 20, 12, Graphik.white) + + width, height = display.get_size() + assert all(_rgb(display, (x, y)) == Graphik.green for x in range(width) for y in range(height)) + + def _count_font_constructions(monkeypatch): # Wrap pygame.font.Font so tests can observe how often it is built. constructed = []