Text - Pyglet/Glyph based

arcade.Text

class arcade.Text(text: str, start_x: float, start_y: float, color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]] = (255, 255, 255), font_size: float = 12, width: int = 0, align: str = 'left', font_name: Union[str, Tuple[str, ...]] = ('calibri', 'arial'), bold: bool = False, italic: bool = False, anchor_x: str = 'left', anchor_y: str = 'baseline', multiline: bool = False, rotation: float = 0)[source]

An object-oriented way to draw text to the screen.

Tip

Use this class when performance matters!

Unlike draw_text(), this class does not risk wasting time recalculating and re-setting any text each time draw() is called. This makes it faster while:

  • requiring you to manage instances and drawing yourself

  • using negligible extra RAM

The speed advantage scales as more text needs to be drawn to the screen.

The constructor arguments work identically to those of draw_text(). See its documentation for in-depth explanation for how to use each of them.

Parameters
  • text (str) – Initial text to display. Can be an empty string

  • start_x (float) – x position to align the text’s anchor point with

  • start_y (float) – y position to align the text’s anchor point with

  • color (Color) – Color of the text as a tuple or list of 3 (RGB) or 4 (RGBA) integers

  • font_size (float) – Size of the text in points

  • width (float) – A width limit in pixels

  • align (str) – Horizontal alignment; values other than “left” require width to be set

  • font_name (Union[str, Tuple[str, ...]]) – A font name, path to a font file, or list of names

  • bold (bool) – Whether to draw the text as bold

  • italic (bool) – Whether to draw the text as italic

  • anchor_x (str) – How to calculate the anchor point’s x coordinate

  • anchor_y (str) – How to calculate the anchor point’s y coordinate

  • multiline (bool) – Requires width to be set; enables word wrap rather than clipping

  • rotation (float) – rotation in degrees, counter-clockwise from horizontal

All constructor arguments other than text have a corresponding property. To access the current text, use the value property instead.

By default, the text is placed so that:

  • the left edge of its bounding box is at start_x

  • its baseline is at start_y

The baseline is located along the line the bottom of the text would be written on, excluding letters with tails such as y:

../_images/text_anchor_y.png

The blue line is the baseline for the string "Python"

rotation allows for the text to be rotated around the anchor point by the passed number of degrees. Positive values rotate counter-clockwise from horizontal, while negative values rotate clockwise:

../_images/text_rotation_degrees.png

Rotation around the default anchor ( anchor_y="baseline" and anchor_x="left")

draw() None[source]

Draw this label to the screen at its current x and y position.

property position: Union[Tuple[float, float], List[float]]

The current x, y position as a tuple. This wraps x and y.

property value: str

The current value to display.

arcade.create_text

arcade.create_text(*args, **kwargs)[source]

Legacy stub, returns a text object.

arcade.draw_text

arcade.draw_text(text: str, start_x: float, start_y: float, color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]] = (255, 255, 255), font_size: float = 12, width: int = 0, align: str = 'left', font_name: Union[str, Tuple[str, ...]] = ('calibri', 'arial'), bold: bool = False, italic: bool = False, anchor_x: str = 'left', anchor_y: str = 'baseline', multiline: bool = False, rotation: float = 0)[source]

A simple way for beginners to draw text.

Warning

Cameras affect text drawing!

If you want to draw a custom GUI that doesn’t move with the game world, you will need a second camera. For information on how to do this, see Move with a Scrolling Screen - Centered.

This function lets you start draw text easily with better performance than the old pillow-based text. If you need even higher performance, consider using Text.

Parameters
  • text (str) – Text to display

  • start_x (float) – x position to align the text’s anchor point with

  • start_y (float) – y position to align the text’s anchor point with

  • color (Color) – Color of the text as a tuple or list of 3 (RGB) or 4 (RGBA) integers

  • font_size (float) – Size of the text in points

  • width (float) – A width limit in pixels

  • align (str) – Horizontal alignment; values other than “left” require width to be set

  • font_name (Union[str, Tuple[str, ...]]) – A font name, path to a font file, or list of names

  • bold (bool) – Whether to draw the text as bold

  • italic (bool) – Whether to draw the text as italic

  • anchor_x (str) – How to calculate the anchor point’s x coordinate

  • anchor_y (str) – How to calculate the anchor point’s y coordinate

  • multiline (bool) – Requires width to be set; enables word wrap rather than clipping

  • rotation (float) – rotation in degrees, counter-clockwise from horizontal

By default, the text is placed so that:

  • the left edge of its bounding box is at start_x

  • its baseline is at start_y

The baseline of text is the line it would be written on:

../_images/text_anchor_y.png

The blue line is the baseline for the string "Python"

font_name can be any of the following:

  • a built-in font in the Built-In Resources

  • the name of a system font

  • a path to a font on the system

  • a tuple containing any mix of the previous three

Each entry provided will be tried in order until one is found. If none of the fonts are found, a default font will be chosen (usually Arial).

anchor_x and anchor_y specify how to calculate the anchor point, which affects how the text is:

  • Placed relative to start_x and start_y

  • Rotated

By default, the text is drawn so that start_x is at the left of the text’s bounding box and start_y is at the baseline.

You can set a custom anchor point by passing combinations of the following values for anchor_x and anchor_y:

Values allowed by anchor_x

String value

Practical Effect

Anchor Position

"left" (default)

Text drawn with its left side at start_x

Anchor point at the left side of the text’s bounding box

"center"

Text drawn horizontally centered on start_x

Anchor point at horizontal center of text’s bounding box

"right"

Text drawn with its right side at start_x

Anchor placed at the right side of the text’s bounding box

Values allowed by anchor_y

String value

Practical Effect

Anchor Position

"baseline" (default)

Text drawn with baseline on start_y.

Anchor placed at the text rendering baseline

"top"

Text drawn with its top aligned with start_y

Anchor point placed at the top of the text

"bottom"

Text drawn with its absolute bottom aligned with start_y, including the space for tails on letters such as y and g

Anchor point placed at the bottom of the text after the space allotted for letters such as y and g

"center"

Text drawn with its vertical center on start_y

Anchor placed at the vertical center of the text

rotation allows for the text to be rotated around the anchor point by the passed number of degrees. Positive values rotate counter-clockwise from horizontal, while negative values rotate clockwise:

../_images/text_rotation_degrees.png

Rotation around the default anchor point ( anchor_y="baseline" and anchor_x="left")

It can be helpful to think of this function working as follows:

  1. Text layout and alignment are calculated:

    1. The text’s characters are laid out within a bounding box according to the current styling options

    2. The anchor point on the text is calculated based on the text value, styling, as well as values for anchor_x and anchor_y

  2. The text is placed so its anchor point is at (start_x, start_y))

  3. The text is rotated around its anchor point before finally being drawn

This function is less efficient than using Text because some of the steps above can be repeated each time a call is made rather than fully cached as with the class.

arcade.load_font

arcade.load_font(font_name) None[source]

Load a font for later use.

Parameters

font_name

Raises

FileNotFoundError – if the font specified wasn’t found

Returns