pyglet.text

Submodules

Details

Text formatting, layout and display.

This module provides classes for loading styled documents from text files, HTML files and a pyglet-specific markup format. Documents can be styled with multiple fonts, colours, styles, text sizes, margins, paragraph alignments, and so on.

Using the layout classes, documents can be laid out on a single line or word-wrapped to fit a rectangle. A layout can then be efficiently drawn in a window or updated incrementally (for example, to support interactive text editing).

The label classes provide a simple interface for the common case where an application simply needs to display some text in a window.

A plain text label can be created with:

label = pyglet.text.Label('Hello, world',
                          font_name='Times New Roman',
                          font_size=36,
                          x=10, y=10)

Alternatively, a styled text label using HTML can be created with:

label = pyglet.text.HTMLLabel('<b>Hello</b>, <i>world</i>',
                              x=10, y=10)

Either label can then be drawn at any time with:

label.draw()

For details on the subset of HTML supported, see pyglet.text.formats.html.

Refer to the Programming Guide for advanced usage of the document and layout classes, including interactive editing, embedding objects within documents and creating scrollable layouts.

exception DocumentDecodeException

An error occurred decoding document text.

class DocumentDecoder

Abstract document decoder.

abstractmethod decode(
text: str,
location: Location | None = None,
) → AbstractDocument

Decode document text.

Parameters:

  • text (str) – Text to decode

  • location (Location | None) – Location to use as base path for additional resources referenced within the document (for example, HTML images).

Return type:

AbstractDocument

class DocumentLabel(
document: AbstractDocument,
x: float = 0.0,
y: float = 0.0,
z: float = 0.0,
width: int | None = None,
height: int | None = None,
anchor_x: AnchorX = 'left',
anchor_y: AnchorY = 'baseline',
rotation: float = 0.0,
multiline: bool = False,
dpi: int | None = None,
batch: Batch | None = None,
group: Group | None = None,
program: ShaderProgram | None = None,
decoration_shader: ShaderProgram | None = None,
effect_shader: ShaderProgram | None = None,
shaping: bool = True,
init_document: bool = True,
depth_sorting: bool = False,
) → None

Base label class.

A label is a layout that exposes convenience methods for manipulating the associated document.

Create a label for a given document.

Parameters:

  • document (AbstractDocument) – Document to attach to the layout.

  • x (float) – X coordinate of the label.

  • y (float) – Y coordinate of the label.

  • z (float) – Z coordinate of the label.

  • width (int | None) – Width of the label in pixels, or None

  • height (int | None) – Height of the label in pixels, or None

  • anchor_x (Literal['left', 'center', 'right']) – Anchor point of the X coordinate: one of "left", “center”` or "right".

  • anchor_y (Literal['top', 'bottom', 'center', 'baseline']) – Anchor point of the Y coordinate: one of "bottom", "baseline", "center" or "top".

  • rotation (float) – The amount to rotate the label in degrees. A positive amount will be a clockwise rotation, negative values will result in counter-clockwise rotation.

  • multiline (bool) – If True, the label will be word-wrapped and accept newline characters. You must also set the width of the label.

  • dpi (int | None) – Resolution of the fonts in this layout. Defaults to 96.

  • batch (Batch | None) – Optional graphics batch to add the label to.

  • group (Group | None) – Optional graphics group to use.

  • program (ShaderProgram | None) – Optional graphics shader to use. Will affect all glyphs. Label colors are uploaded as four unsigned bytes; custom programs must use vertex_layout=pyglet.graphics.VertexLayout(colors="4Bn") so the values are normalized for the shader.

  • decoration_shader (ShaderProgram | None) – Optional graphics shader to use for all text decorations.

  • effect_shader (ShaderProgram | None) – Optional graphics shader to use for all glyph-backed text effects.

  • shaping (bool) – Whether this label should use text shaping. The shaping backend is selected globally with pyglet.options.text_shaping. If False, glyph positions are based on their unshaped metrics.

  • init_document (bool) – If True, the document will be initialized. If you are passing an already-initialized document, then you can avoid duplicating work by setting this to False.

  • depth_sorting (bool) – Whether to enable depth testing and depth-safe ordering of the label’s background, effects, glyphs, and decorations.

Changed in version 3.0: Added the shaping parameter. Added the depth_sorting parameter.

get_style(name: str) → Any

Get a document style value by name.

If the document has more than one value of the named style, pyglet.text.document.STYLE_INDETERMINATE is returned.

Parameters:

name (str) – Style name to query. See documentation from pyglet.text.layout for known style names.

Return type:

Any

set_style(name: str, value: Any) → None

Set a document style value by name over the whole document.

Parameters:

  • name (str) – Name of the style to set. See documentation for pyglet.text.layout for known style names.

  • value (Any) – Value of the style.

Return type:

None

property color: tuple[int, int, int, int] | LinearGradient

Text color.

Color is an RGBA tuple or a LinearGradient.

property font: Font

The current font object used at the beginning of the text.

Setting this property will change the font for the entire document.

Added in version 3.0.

property font_name: str

The current font family name.

The value is read from the beginning of this document.

The font name, as passed to pyglet.font.load(). A list of names can optionally be given: the first matching font will be used.

property font_size: float

Font size, in points.

property italic: bool | str

Italic font style.

property opacity: int

Blend opacity.

This property sets the alpha component of the colour of the label’s vertices. With the default blend mode, this allows the layout to be drawn with fractional opacity, blending with the background.

An opacity of 255 (the default) has no effect. An opacity of 128 will make the label appear semi-translucent.

property shadow: DropShadow | None

Drop-shadow style, or None to disable it.

property stroke: Stroke | None

Text stroke style, or None to disable it.

property text: str

The text of the label.

property weight: Weight | str

The font weight (boldness or thickness), as a string.

See the Weight enum for valid cross-platform string values.

class DropShadow(
offset: tuple[int, int] = (1, -1),
color: RGBAColor | LinearGradient = (0, 0, 0, 255),
) → None

Style data for a text drop shadow.

Parameters:
color: Tuple[int, int, int, int] | LinearGradient
offset: tuple[int, int]
class HTMLLabel(
text: str = '',
x: float = 0.0,
y: float = 0.0,
z: float = 0.0,
width: int | None = None,
height: int | None = None,
anchor_x: Literal['left', 'center', 'right'] = 'left',
anchor_y: Literal['top', 'bottom', 'center', 'baseline'] = 'baseline',
rotation: float = 0.0,
multiline: bool = False,
dpi: int | None = None,
location: Location | None = None,
batch: Batch | None = None,
group: Group | None = None,
program: ShaderProgram | None = None,
decoration_shader: ShaderProgram | None = None,
effect_shader: ShaderProgram | None = None,
shaping: bool = True,
depth_sorting: bool = False,
) → None

HTML formatted text label.

A subset of HTML 4.01 is supported. See pyglet.text.formats.html for details.

Create a label with an HTML string.

Parameters:

  • text (str) – Text to display.

  • x (float) – X coordinate of the label.

  • y (float) – Y coordinate of the label.

  • z (float) – Z coordinate of the label.

  • width (int | None) – Width of the label in pixels, or None

  • height (int | None) – Height of the label in pixels, or None

  • anchor_x (Literal['left', 'center', 'right']) – Anchor point of the X coordinate: one of "left", "center" or "right".

  • anchor_y (Literal['top', 'bottom', 'center', 'baseline']) – Anchor point of the Y coordinate: one of "bottom", "baseline", "center" or "top".

  • rotation (float) – The amount to rotate the label in degrees. A positive amount will be a clockwise rotation, negative values will result in counter-clockwise rotation.

  • multiline (bool) – If True, the label will be word-wrapped and accept newline characters. You must also set the width of the label.

  • dpi (int | None) – Resolution of the fonts in this layout. Defaults to 96.

  • location (Location | None) – Location object for loading images referred to in the document. By default, the working directory is used.

  • batch (Batch | None) – Optional graphics batch to add the label to.

  • group (Group | None) – Optional graphics group to use.

  • program (ShaderProgram | None) – Optional graphics shader to use. Will affect all glyphs.

  • decoration_shader (ShaderProgram | None) – Optional graphics shader to use for all text decorations.

  • effect_shader (ShaderProgram | None) – Optional graphics shader to use for all glyph-backed text effects.

  • shaping (bool) – Whether this label should use text shaping. The shaping backend is selected globally with pyglet.options.text_shaping. If False, glyph positions are based on their unshaped metrics.

  • depth_sorting (bool) – Whether to enable depth testing and depth-safe ordering of the label’s background, effects, glyphs, and decorations.

Changed in version 3.0: Added the shaping parameter. Added the depth_sorting parameter.

property text: str

HTML formatted text of the label.

class Label(
text: str = '',
x: float = 0.0,
y: float = 0.0,
z: float = 0.0,
width: int | None = None,
height: int | None = None,
anchor_x: Literal['left', 'center', 'right'] = 'left',
anchor_y: Literal['top', 'bottom', 'center', 'baseline'] = 'baseline',
rotation: float = 0.0,
multiline: bool = False,
dpi: int | None = None,
font_name: str | None = None,
font_size: float | None = None,
weight: Weight | str = Weight.NORMAL,
style: Style | str = Style.NORMAL,
stretch: Stretch | str = Stretch.NORMAL,
color: tuple[int, int, int, int] | tuple[int, int, int] | LinearGradient = (255, 255, 255, 255),
shadow: DropShadow | None = None,
stroke: Stroke | None = None,
align: Literal['left', 'center', 'right'] = 'left',
batch: Batch | None = None,
group: Group | None = None,
program: ShaderProgram | None = None,
decoration_shader: ShaderProgram | None = None,
effect_shader: ShaderProgram | None = None,
shaping: bool = True,
depth_sorting: bool = False,
) → None

Plain text label.

Create a plain text label.

Parameters:

  • text (str) – Text to display.

  • x (float) – X coordinate of the label.

  • y (float) – Y coordinate of the label.

  • z (float) – Z coordinate of the label.

  • width (int | None) – Width of the label in pixels, or None

  • height (int | None) – Height of the label in pixels, or None

  • anchor_x (Literal['left', 'center', 'right']) – Anchor point of the X coordinate: one of "left", "center" or "right".

  • anchor_y (Literal['top', 'bottom', 'center', 'baseline']) – Anchor point of the Y coordinate: one of "bottom", "baseline", "center" or "top".

  • rotation (float) – The amount to rotate the label in degrees. A positive amount will be a clockwise rotation, negative values will result in counter-clockwise rotation.

  • multiline (bool) – If True, the label will be word-wrapped and accept newline characters. You must also set the width of the label.

  • dpi (int | None) – Resolution of the fonts in this layout. Defaults to 96.

  • font_name (str | None) – Font family name(s). A list of names can optionally be given: the first matching font will be used.

  • font_size (float | None) – Font size, in points.

  • weight (Weight | str) – The ‘weight’ of the font (boldness). See the Weight enum for valid cross-platform weight names.

  • style (Style | str) – Italic font style. See the Style enum for valid cross-platform style names.

  • stretch (Stretch | str) – Stretch font style. See the Stretch enum for valid cross-platform style names.

  • color (tuple[int, int, int, int] | tuple[int, int, int] | LinearGradient) – Font color as RGBA or RGB components, each within 0 <= component <= 255, or a LinearGradient.

  • shadow (DropShadow | None) – Optional DropShadow style. None (the default) disables the shadow.

  • stroke (Stroke | None) – Optional Stroke style. None (the default) disables the stroke.

  • align (Literal['left', 'center', 'right']) – Horizontal alignment of text on a line, only applies if a width is supplied. One of "left", "center" or "right".

  • batch (Batch | None) – Optional graphics batch to add the label to.

  • group (Group | None) – Optional graphics group to use.

  • program (ShaderProgram | None) – Optional graphics shader to use. Will affect all glyphs.

  • decoration_shader (ShaderProgram | None) – Optional graphics shader to use for all text decorations.

  • effect_shader (ShaderProgram | None) – Optional graphics shader to use for all glyph-backed text effects.

  • shaping (bool) – Whether this label should use text shaping. The shaping backend is selected globally with pyglet.options.text_shaping. If False, glyph positions are based on their unshaped metrics.

  • depth_sorting (bool) – Whether to enable depth testing and depth-safe ordering of the label’s background, effects, glyphs, and decorations.

Changed in version 3.0: Added the shaping parameter. Added the depth_sorting parameter.

class LinearGradient(
start: Tuple[int, int, int, int],
end: Tuple[int, int, int, int],
) → None

A horizontal gradient used as a text color style.

The gradient runs from the left to the right edge of each visual styled range. Wrapped ranges restart the gradient on each line.

Parameters:
end: Tuple[int, int, int, int]
start: Tuple[int, int, int, int]
class Stroke(
size: float = 1.0,
color: Tuple[int, int, int, int] | LinearGradient = (0, 0, 0, 255),
join: Literal['miter', 'round', 'bevel'] = 'round',
) → None

Style data for a text stroke.

Parameters:
color: Tuple[int, int, int, int] | LinearGradient
join: Literal['miter', 'round', 'bevel']
size: float
decode_attributed(text: str) → FormattedDocument

Create a document directly from some attributed text.

See pyglet.text.formats.attributed for a description of attributed text.

Return type:

FormattedDocument

decode_html(
text: str,
location: str | None = None,
) → FormattedDocument

Create a document directly from some HTML formatted text.

Parameters:

  • text (str) – HTML data to decode.

  • location (str | None) – Location giving the base path for additional resources referenced from the document (e.g., images).

Return type:

FormattedDocument

decode_text(text: str) → UnformattedDocument

Create a document directly from some plain text.

Return type:

UnformattedDocument

get_decoder(
filename: str | None,
mimetype: Literal['text/plain', 'text/html', 'text/vnd.pyglet-attributed'] | None = None,
) → DocumentDecoder

Get a document decoder for the given filename and MIME type.

If mimetype is omitted it is guessed from the filename extension.

The following MIME types are supported:

text/plain

Plain text

text/html

HTML 4 Transitional

text/vnd.pyglet-attributed

Attributed text; see pyglet.text.formats.attributed

Parameters:

  • filename (str | None) – Filename to guess the MIME type from. If a MIME type is given, the filename is ignored.

  • mimetype (Literal['text/plain', 'text/html', 'text/vnd.pyglet-attributed'] | None) – MIME type to lookup, or None to guess the type from the filename.

Raises:

DocumentDecodeException – If MIME type is not from the supported types.

Return type:

DocumentDecoder

load(
filename: str,
file: BinaryIO | None = None,
mimetype: Literal['text/plain', 'text/html', 'text/vnd.pyglet-attributed'] | None = None,
) → AbstractDocument

Load a document from a file.

Parameters:

  • filename (str) – Filename of document to load.

  • file (BinaryIO | None) – File object containing encoded data. If omitted, filename is loaded from disk.

  • mimetype (Literal['text/plain', 'text/html', 'text/vnd.pyglet-attributed'] | None) – MIME type of the document. If omitted, the filename extension is used to guess a MIME type. See get_decoder for a list of supported MIME types.

Return type:

AbstractDocument