Files
2026-11-04 21:01:26 +01:00

350 lines
12 KiB
Python

from collections.abc import Callable, Hashable, Iterable
from typing import Literal
from pygame.surface import Surface
from pygame.typing import ColorLike, FileLike
from typing_extensions import deprecated # added in 3.13
# TODO: Figure out a way to type this attribute such that mypy knows it's not
# always defined at runtime
UCS4: Literal[1]
def init() -> None: ...
def quit() -> None: ...
def get_init() -> bool: ...
def get_sdl_ttf_version(linked: bool = True) -> tuple[int, int, int]:
"""
Gets SDL_ttf version.
Returns a tuple of integers that identify SDL_ttf's version,
``(major, minor, patch)``. SDL_ttf is the underlying font rendering library,
written in C, on which pygame's font module depends. If 'linked' is True
(the default), the function returns the version of the linked TTF library.
Otherwise this function returns the version of TTF pygame was compiled with.
.. versionadded:: 2.1.3
"""
def get_default_font() -> str:
"""
Get the filename of the default font.
Return the filename of the system font. This is not the full path to the
file. This file can usually be found in the same directory as the font
module, but it can also be bundled in separate archives.
"""
def get_fonts() -> list[str]:
"""Get all available fonts.
Returns a list of all the fonts available on the system. The names of the
fonts will be set to lowercase with all spaces and punctuation removed. This
works on most systems, but some will return an empty list if they cannot
find fonts.
.. versionchanged:: 2.1.3 Checks through user fonts instead of just global fonts for Windows.
"""
def match_font(
name: str | bytes | Iterable[str | bytes],
bold: Hashable = False,
italic: Hashable = False,
) -> str | None:
"""Find a specific font on the system.
Returns the full path to a font file on the system. If bold or italic are
set to true, this will attempt to find the correct family of font.
The font name can also be an iterable of font names, a string of
comma-separated font names, or a bytes of comma-separated font names, in
which case the set of names will be searched in order.
If none of the given names are found, None is returned.
.. versionaddedold:: 2.0.1 Accept an iterable of font names.
.. versionchanged:: 2.1.3 Checks through user fonts instead of just global fonts for Windows.
Example::
>>> pygame.font.match_font('Arial')
'C:\\WINDOWS\\Fonts\\arial.ttf'
"""
def SysFont(
name: str | bytes | Iterable[str | bytes] | None,
size: int,
bold: Hashable = False,
italic: Hashable = False,
constructor: Callable[[str | None, int, bool, bool], Font] | None = None,
) -> Font: ...
class Font:
@property
def name(self) -> str: ...
@property
def style_name(self) -> str: ...
@property
def bold(self) -> bool: ...
@bold.setter
def bold(self, value: bool) -> None: ...
@property
def italic(self) -> bool: ...
@italic.setter
def italic(self, value: bool) -> None: ...
@property
def underline(self) -> bool: ...
@underline.setter
def underline(self, value: bool) -> None: ...
@property
def strikethrough(self) -> bool: ...
@strikethrough.setter
def strikethrough(self, value: bool) -> None: ...
@property
def align(self) -> int: ...
@align.setter
def align(self, value: int) -> None: ...
@property
def point_size(self) -> int: ...
@point_size.setter
def point_size(self, value: int) -> None: ...
@property
def outline(self) -> int: ...
@outline.setter
def outline(self, value: int) -> None: ...
def __init__(self, filename: FileLike | None = None, size: int = 20) -> None: ...
def render(
self,
text: str | bytes | None,
antialias: bool,
color: ColorLike,
bgcolor: ColorLike | None = None,
wraplength: int = 0,
) -> Surface: ...
def size(self, text: str | bytes, /) -> tuple[int, int]:
"""
Determine the amount of space needed to render text.
Returns the dimensions (width, height) needed to render the text.
This can be used to help determine the positioning needed for text
before it is rendered. It can also be used for word wrapping and other
layout effects.
Be aware that most fonts use kerning which adjusts the widths for
specific letter pairs. For example, the width for "ae" will not always
match the width for "a" + "e".
"""
def set_underline(self, value: bool, /) -> None:
"""
Control if text is rendered with an underline.
When enabled, all rendered fonts will include an underline. The underline
is always one pixel thick, regardless of font size. This can be mixed
with the bold, italic and strikethrough modes.
.. note:: This is the same as the :attr:`underline` attribute.
"""
def get_underline(self) -> bool:
"""
Check if text will be rendered with an underline.
Return True when the font underline is enabled.
.. note:: This is the same as the :attr:`underline` attribute.
"""
def set_strikethrough(self, value: bool, /) -> None:
"""
Control if text is rendered with a strikethrough.
When enabled, all rendered fonts will include a strikethrough. The
strikethrough is always one pixel thick, regardless of font size.
This can be mixed with the bold, italic and underline modes.
.. note:: This is the same as the :attr:`strikethrough` attribute.
.. versionadded:: 2.1.3
"""
def get_strikethrough(self) -> bool:
"""
Check if text will be rendered with a strikethrough.
Return True when the font strikethrough is enabled.
.. note:: This is the same as the :attr:`strikethrough` attribute.
.. versionadded:: 2.1.3
"""
def set_bold(self, value: bool, /) -> None:
"""
Enable fake rendering of bold text.
Enables the bold rendering of text. This is a fake stretching of the font
that doesn't look good on many font types. If possible load the font from
a real bold font file. While bold, the font will have a different width
than when normal. This can be mixed with the italic, underline and
strikethrough modes.
.. note:: This is the same as the :attr:`bold` attribute.
"""
def get_bold(self) -> bool:
"""
Check if text will be rendered bold.
Return True when the font bold rendering mode is enabled.
.. note:: This is the same as the :attr:`bold` attribute.
"""
def set_italic(self, value: bool, /) -> None:
"""
Enable fake rendering of italic text.
Enables fake rendering of italic text. This is a fake skewing of the font
that doesn't look good on many font types. If possible load the font from
a real italic font file. While italic the font will have a different
width than when normal. This can be mixed with the bold, underline and
strikethrough modes.
.. note:: This is the same as the :attr:`italic` attribute.
"""
def metrics(
self, text: str | bytes, /
) -> list[tuple[int, int, int, int, int] | None]:
"""
Gets the metrics for each character in the passed string.
The list contains tuples for each character, which contain the minimum
``X`` offset, the maximum ``X`` offset, the minimum ``Y`` offset, the
maximum ``Y`` offset and the advance offset (bearing plus width) of the
character. [(minx, maxx, miny, maxy, advance), (minx, maxx, miny, maxy,
advance), ...]. None is entered in the list for each unrecognized
character.
.. versionchanged:: 2.5.4 This function now supports all unicode codepoints.
Previously, only a subset that was representable in UCS-2 was supported.
"""
def get_italic(self) -> bool:
"""
Check if the text will be rendered italic.
Return True when the font italic rendering mode is enabled.
.. note:: This is the same as the :attr:`italic` attribute.
"""
def get_linesize(self) -> int:
"""
Get the line space of the font text.
Return the height in pixels for a line of text with the font. When
rendering multiple lines of text this is the recommended amount of space
between lines.
See also :meth:`set_linesize`.
"""
def set_linesize(self, linesize: int, /) -> None:
"""
Set the line space of the font text.
Set the height in pixels for a line of text with the font. When rendering
multiple lines of text this refers to the amount of space between lines.
The value must be non-negative.
See also :meth:`get_linesize`.
.. versionadded:: 2.5.4
"""
def get_height(self) -> int:
"""
Get the height of the font.
Return the height in pixels of the actual rendered text. This is the
average size for each glyph in the font.
"""
def get_point_size(self) -> int:
"""
Get the point size of the font.
Returns the point size of the font. Will not be accurate upon
initializing the font object when the font name is initialized
as ``None``.
.. note:: This is the same as the :attr:`point_size` attribute.
.. versionadded:: 2.3.1
"""
def set_point_size(self, val: int, /) -> None:
"""
Set the point size of the font.
.. note:: This is the same as the :attr:`point_size` attribute.
.. versionadded:: 2.3.1
"""
def get_ascent(self) -> int:
"""
Get the ascent of the font.
Return the height in pixels for the font ascent. The ascent is the number
of pixels from the font baseline to the top of the font.
"""
def get_descent(self) -> int:
"""
Get the descent of the font.
Return the height in pixels for the font descent. The descent is the
number of pixels from the font baseline to the bottom of the font.
"""
def set_script(self, script_code: str, /) -> None:
"""
Set the script code for text shaping.
Sets the script used by HarfBuzz text shaping, taking a 4 character
script code as input. For example, Hindi is written in the Devanagari
script, for which the script code is `"Deva"`. See the full list of
script codes in `ISO 15924 <https://www.unicode.org/iso15924/iso15924-codes.html>`_.
This method requires pygame built with SDL_ttf 2.20.0 or above. Otherwise the
method will raise a pygame.error.
.. versionadded:: 2.1.4
"""
def set_direction(self, direction: int) -> None:
"""
Set the script direction for text shaping.
Sets the font direction for HarfBuzz text rendering, taking in an integer
between 0 and 3 (inclusive) as input. There are convenient constants defined
for use in this method.
* ``pygame.DIRECTION_LTR`` is for left-to-right text
* ``pygame.DIRECTION_RTL`` is for right-to-left text
* ``pygame.DIRECTION_TTB`` is for top-to-bottom text
* ``pygame.DIRECTION_BTT`` is for bottom-to-top text
This method requires pygame built with SDL_ttf 2.20.0 or above. Otherwise the
method will raise a pygame.error.
.. note:: multiline renders with :meth:`render` do not play nicely with top-to-bottom
or bottom-to-top rendering.
.. versionadded:: 2.1.4
"""
@deprecated("Use `Font` instead (FontType is an old alias)")
class FontType(Font): ...