pyglet.text.layout¶
Render simple text and formatted documents efficiently.
Three layout classes are provided:
TextLayout
The entire document is laid out before it is rendered. The layout will be grouped with other layouts in the same batch (allowing for efficient rendering of multiple layouts).
Any change to the layout or document, and even querying some properties, will cause the entire document to be laid out again.
ScrollableTextLayout
Based on
TextLayout()
.A separate group is used for layout which crops the contents of the layout to the layout rectangle. Additionally, the contents of the layout can be “scrolled” within that rectangle with the
view_x
andview_y
properties.IncrementalTextLayout
Based on
ScrollableTextLayout
.When the layout or document are modified, only the affected regions are laid out again. This permits efficient interactive editing and styling of text.
Only the visible portion of the layout is actually rendered; as the viewport is scrolled additional sections are rendered and discarded as required. This permits efficient viewing and editing of large documents.
Additionally, this class provides methods for locating the position of a caret in the document, and for displaying interactive text selections.
All three layout classes can be used with either UnformattedDocument
or
FormattedDocument
, and can be either single-line or multiline
. The
combinations of these options effectively provides 12 different text display
possibilities.
Style attributes¶
The following character style attribute names are recognised by the layout classes. Data types and units are as specified.
Where an attribute is marked “as a distance” the value is assumed to be
in pixels if given as an int or float, otherwise a string of the form
"0u"
is required, where 0
is the distance and u
is the unit; one
of "px"
(pixels), "pt"
(points), "pc"
(picas), "cm"
(centimeters), "mm"
(millimeters) or "in"
(inches). For example,
"14pt"
is the distance covering 14 points, which at the default DPI of 96
is 18 pixels.
font_name
- Font family name, as given to
pyglet.font.load()
. font_size
- Font size, in points.
bold
- Boolean.
italic
- Boolean.
underline
- 4-tuple of ints in range (0, 255) giving RGBA underline color, or None (default) for no underline.
kerning
- Additional space to insert between glyphs, as a distance. Defaults to 0.
baseline
- Offset of glyph baseline from line baseline, as a distance. Positive values give a superscript, negative values give a subscript. Defaults to 0.
color
- 4-tuple of ints in range (0, 255) giving RGBA text color
background_color
- 4-tuple of ints in range (0, 255) giving RGBA text background color; or
None
for no background fill.
The following paragraph style attribute names are recognised. Note that paragraph styles are handled no differently from character styles by the document: it is the application’s responsibility to set the style over an entire paragraph, otherwise results are undefined.
align
left
(default),center
orright
.indent
- Additional horizontal space to insert before the first glyph of the first line of a paragraph, as a distance.
leading
- Additional space to insert between consecutive lines within a paragraph, as a distance. Defaults to 0.
line_spacing
- Distance between consecutive baselines in a paragraph, as a distance.
Defaults to
None
, which automatically calculates the tightest line spacing for each line based on the font ascent and descent. margin_left
- Left paragraph margin, as a distance.
margin_right
- Right paragraph margin, as a distance.
margin_top
- Margin above paragraph, as a distance.
margin_bottom
- Margin below paragraph, as a distance. Adjacent margins do not collapse.
tab_stops
- List of horizontal tab stops, as distances, measured from the left edge of the text layout. Defaults to the empty list. When the tab stops are exhausted, they implicitly continue at 50 pixel intervals.
wrap
char
,word
, True (default) or False. The boundaries at which to wrap text to prevent it overflowing a line. Withchar
, the line wraps anywhere in the text; withword
or True, the line wraps at appropriate boundaries between words; with False the line does not wrap, and may overflow the layout width.char
andword
styles are since pyglet 1.2.
Other attributes can be used to store additional style information within the document; they will be ignored by the built-in text classes.
New in version 1.1.
-
class
IncrementalTextLayout
(document, width, height, multiline=False, dpi=None, batch=None, group=None, wrap_lines=True)¶ Displayed text suitable for interactive editing and/or scrolling large documents.
Unlike
TextLayout()
andScrollableTextLayout
, this class generates vertex lists only for lines of text that are visible. As the document is scrolled, vertex lists are deleted and created as appropriate to keep video memory usage to a minimum and improve rendering speed.Changes to the document are quickly reflected in this layout, as only the affected line(s) are reflowed. Use begin_update and end_update to further reduce the amount of processing required.
The layout can also display a text selection (text with a different background color). The
Caret
class implements a visible text cursor and provides event handlers for scrolling, selecting and editing text in an incremental text layout.-
decoration_class
¶ alias of
IncrementalTextDecorationGroup
-
group_class
¶ alias of
IncrementalTextLayoutGroup
-
delete
()¶ Remove this layout from its batch.
-
ensure_line_visible
(line)¶ Adjust view_y so that the line with the given index is visible.
Parameters: - line : int
Line index.
-
ensure_x_visible
(x)¶ Adjust view_x so that the given X coordinate is visible.
The X coordinate is given relative to the current view_x.
Parameters: - x : int
X coordinate
-
get_line_count
()¶ Get the number of lines in the text layout.
Return type: int
-
get_line_from_point
(x, y)¶ Get the closest line index to a point.
Parameters: - x : int
X coordinate.
- y : int
Y coordinate.
Return type: int
-
get_line_from_position
(position)¶ Get the line index of a character position in the document.
Parameters: - position : int
Document position.
Return type: int
-
get_point_from_line
(line)¶ Get the X, Y coordinates of a line index.
Parameters: - line : int
Line index.
Return type: (int, int)
Returns: (x, y)
-
get_point_from_position
(position, line=None)¶ Get the X, Y coordinates of a position in the document.
The position that ends a line has an ambiguous point: it can be either the end of the line, or the beginning of the next line. You may optionally specify a line index to disambiguate the case.
The resulting Y coordinate gives the baseline of the line.
Parameters: - position : int
Character position within document.
- line : int
Line index.
Return type: (int, int)
Returns: (x, y)
-
get_position_from_line
(line)¶ Get the first document character position of a given line index.
Parameters: - line : int
Line index.
Return type: int
-
get_position_from_point
(x, y)¶ Get the closest document position to a point.
Parameters: - x : int
X coordinate
- y : int
Y coordinate
-
get_position_on_line
(line, x)¶ Get the closest document position for a given line index and X coordinate.
Parameters: - line : int
Line index.
- x : int
X coordinate.
Return type: int
-
on_delete_text
(start, end)¶ Event handler for AbstractDocument.on_delete_text.
The event handler is bound by the text layout; there is no need for applications to interact with this method.
-
on_insert_text
(start, text)¶ Event handler for AbstractDocument.on_insert_text.
The event handler is bound by the text layout; there is no need for applications to interact with this method.
-
on_layout_update
()¶ Some or all of the layout text was reflowed.
Text reflow is caused by document edits or changes to the layout’s size. Changes to the layout’s position or active selection, and certain document edits such as text color, do not cause a reflow.
Handle this event to update the position of a graphical element that depends on the laid out position of a glyph or line.
Event:
-
on_style_text
(start, end, attributes)¶ Event handler for AbstractDocument.on_style_text.
The event handler is bound by the text layout; there is no need for applications to interact with this method.
-
set_selection
(start, end)¶ Set the text selection range.
If
start
equalsend
no selection will be visible.Parameters: - start : int
Starting character position of selection.
- end : int
End of selection, exclusive.
-
anchor_x
¶ Horizontal anchor alignment.
This property determines the meaning of the x coordinate. It is one of the enumerants:
"left"
(default)- The X coordinate gives the position of the left edge of the layout.
"center"
- The X coordinate gives the position of the center of the layout.
"right"
- The X coordinate gives the position of the right edge of the layout.
For the purposes of calculating the position resulting from this alignment, the width of the layout is taken to be width if multiline is True and wrap_lines is True, otherwise content_width.
Type: str
-
anchor_y
¶ Vertical anchor alignment.
This property determines the meaning of the y coordinate. It is one of the enumerants:
"top"
- The Y coordinate gives the position of the top edge of the layout.
"center"
- The Y coordinate gives the position of the center of the layout.
"baseline"
- The Y coordinate gives the position of the baseline of the first line of text in the layout.
"bottom"
(default)- The Y coordinate gives the position of the bottom edge of the layout.
For the purposes of calculating the position resulting from this alignment, the height of the layout is taken to be the smaller of height and content_height.
See also content_valign.
Type: str
-
event_types
= ['on_layout_update']¶
-
height
¶ Height of the layout.
Type: int
-
multiline
¶ Set if multiline layout is enabled.
If multiline is False, newline and paragraph characters are ignored and text is not word-wrapped. If True, the text is word-wrapped only if the wrap_lines is True.
Type: bool
-
position
¶ The (X, Y, Z) coordinates of the layout, as a tuple.
See also
anchor_x
, andanchor_y
.Type: (int, int, int)
-
selection_background_color
¶ Background color of active selection.
The color is an RGBA tuple with components in range [0, 255].
Type: (int, int, int, int)
-
selection_color
¶ Text color of active selection.
The color is an RGBA tuple with components in range [0, 255].
Type: (int, int, int, int)
-
selection_end
¶ End position of the active selection (exclusive).
See: set_selection Type: int
-
selection_start
¶ Starting position of the active selection.
See: set_selection Type: int
-
view_x
¶ Horizontal scroll offset.
The initial value is 0, and the left edge of the text will touch the left side of the layout bounds. A positive value causes the text to “scroll” to the right. Values are automatically clipped into the range
[0, content_width - width]
Type: int
-
view_y
¶ Vertical scroll offset.
The initial value is 0, and the top of the text will touch the top of the layout bounds (unless the content height is less than the layout height, in which case content_valign is used).
A negative value causes the text to “scroll” upwards. Values outside of the range
[height - content_height, 0]
are automatically clipped in range.Type: int
-
width
¶ Width of the layout.
This property has no effect if multiline is False or wrap_lines is False.
Type: int
-
y
¶ Y coordinate of the layout.
See also anchor_y.
Type: int
-
-
class
IncrementalTextLayoutGroup
(texture, program, order=1, parent=None)¶ -
scissor_area
= (0, 0, 0, 0)¶
-
-
class
ScrollableTextDecorationGroup
(program, order=0, parent=None)¶ -
set_state
()¶ Apply the OpenGL state change.
The default implementation does nothing.
-
unset_state
()¶ Repeal the OpenGL state change.
The default implementation does nothing.
-
scissor_area
= (0, 0, 0, 0)¶
-
-
class
ScrollableTextLayout
(document, width, height, multiline=False, dpi=None, batch=None, group=None, wrap_lines=True)¶ Display text in a scrollable viewport.
This class does not display a scrollbar or handle scroll events; it merely clips the text that would be drawn in
TextLayout()
to the bounds of the layout given by x, y, width and height; and offsets the text by a scroll offset.Use view_x and view_y to scroll the text within the viewport.
-
decoration_class
¶ alias of
ScrollableTextDecorationGroup
-
group_class
¶ alias of
ScrollableTextLayoutGroup
-
anchor_x
¶ Horizontal anchor alignment.
This property determines the meaning of the x coordinate. It is one of the enumerants:
"left"
(default)- The X coordinate gives the position of the left edge of the layout.
"center"
- The X coordinate gives the position of the center of the layout.
"right"
- The X coordinate gives the position of the right edge of the layout.
For the purposes of calculating the position resulting from this alignment, the width of the layout is taken to be width if multiline is True and wrap_lines is True, otherwise content_width.
Type: str
-
anchor_y
¶ Vertical anchor alignment.
This property determines the meaning of the y coordinate. It is one of the enumerants:
"top"
- The Y coordinate gives the position of the top edge of the layout.
"center"
- The Y coordinate gives the position of the center of the layout.
"baseline"
- The Y coordinate gives the position of the baseline of the first line of text in the layout.
"bottom"
(default)- The Y coordinate gives the position of the bottom edge of the layout.
For the purposes of calculating the position resulting from this alignment, the height of the layout is taken to be the smaller of height and content_height.
See also content_valign.
Type: str
-
position
¶ The (X, Y, Z) coordinates of the layout, as a tuple.
See also
anchor_x
, andanchor_y
.Type: (int, int, int)
-
view_x
¶ Horizontal scroll offset.
The initial value is 0, and the left edge of the text will touch the left side of the layout bounds. A positive value causes the text to “scroll” to the right. Values are automatically clipped into the range
[0, content_width - width]
Type: int
-
view_y
¶ Vertical scroll offset.
The initial value is 0, and the top of the text will touch the top of the layout bounds (unless the content height is less than the layout height, in which case content_valign is used).
A negative value causes the text to “scroll” upwards. Values outside of the range
[height - content_height, 0]
are automatically clipped in range.Type: int
-
y
¶ Y coordinate of the layout.
See also anchor_y.
Type: int
-
-
class
ScrollableTextLayoutGroup
(texture, program, order=1, parent=None)¶ -
set_state
()¶ Apply the OpenGL state change.
The default implementation does nothing.
-
unset_state
()¶ Repeal the OpenGL state change.
The default implementation does nothing.
-
scissor_area
= (0, 0, 0, 0)¶
-
-
class
TextDecorationGroup
(program, order=0, parent=None)¶ -
set_state
()¶ Apply the OpenGL state change.
The default implementation does nothing.
-
unset_state
()¶ Repeal the OpenGL state change.
The default implementation does nothing.
-
-
class
TextLayout
(document, width=None, height=None, multiline=False, dpi=None, batch=None, group=None, wrap_lines=True)¶ Lay out and display documents.
This class is intended for displaying documents that do not change regularly – any change will cost some time to lay out the complete document again and regenerate all vertex lists.
The benefit of this class is that texture state is shared between all layouts of this class. The time to draw one
TextLayout()
may be roughly the same as the time to draw oneIncrementalTextLayout
; but drawing tenTextLayout()
objects in one batch is much faster than drawing ten incremental or scrollable text layouts.Label()
andHTMLLabel()
provide a convenient interface to this class.Ivariables: - content_width : int
Calculated width of the text in the layout. This may overflow the desired width if word-wrapping failed.
- content_height : int
Calculated height of the text in the layout.
- group_class : ~pyglet.graphics.Group
Top-level rendering group.
- background_decoration_group : ~pyglet.graphics.Group
Rendering group for background color.
- foreground_decoration_group : ~pyglet.graphics.Group
Rendering group for glyph underlines.
-
decoration_class
¶ alias of
TextDecorationGroup
-
group_class
¶ alias of
TextLayoutGroup
-
begin_update
()¶ Indicate that a number of changes to the layout or document are about to occur.
Changes to the layout or document between calls to begin_update and end_update do not trigger any costly relayout of text. Relayout of all changes is performed when end_update is called.
Note that between the begin_update and end_update calls, values such as content_width and content_height are undefined (i.e., they may or may not be updated to reflect the latest changes).
-
delete
()¶ Remove this layout from its batch.
-
draw
()¶ Draw this text layout.
Note that this method performs very badly if a batch was supplied to the constructor. If you add this layout to a batch, you should ideally use only the batch’s draw method.
-
end_update
()¶ Perform pending layout changes since begin_update.
See begin_update.
-
on_delete_text
(start, end)¶ Event handler for AbstractDocument.on_delete_text.
The event handler is bound by the text layout; there is no need for applications to interact with this method.
-
on_insert_text
(start, text)¶ Event handler for AbstractDocument.on_insert_text.
The event handler is bound by the text layout; there is no need for applications to interact with this method.
-
on_style_text
(start, end, attributes)¶ Event handler for AbstractDocument.on_style_text.
The event handler is bound by the text layout; there is no need for applications to interact with this method.
-
parse_distance
(distance)¶
-
anchor_x
¶ Horizontal anchor alignment.
This property determines the meaning of the x coordinate. It is one of the enumerants:
"left"
(default)- The X coordinate gives the position of the left edge of the layout.
"center"
- The X coordinate gives the position of the center of the layout.
"right"
- The X coordinate gives the position of the right edge of the layout.
For the purposes of calculating the position resulting from this alignment, the width of the layout is taken to be width if multiline is True and wrap_lines is True, otherwise content_width.
Type: str
-
anchor_y
¶ Vertical anchor alignment.
This property determines the meaning of the y coordinate. It is one of the enumerants:
"top"
- The Y coordinate gives the position of the top edge of the layout.
"center"
- The Y coordinate gives the position of the center of the layout.
"baseline"
- The Y coordinate gives the position of the baseline of the first line of text in the layout.
"bottom"
(default)- The Y coordinate gives the position of the bottom edge of the layout.
For the purposes of calculating the position resulting from this alignment, the height of the layout is taken to be the smaller of height and content_height.
See also content_valign.
Type: str
-
batch
¶ The Batch that this Layout is assigned to.
If no Batch is assigned, an internal Batch is created and used.
Type: Batch
-
content_valign
¶ Vertical alignment of content within larger layout box.
This property determines how content is positioned within the layout box when
content_height
is less thanheight
. It is one of the enumerants:top
(default)- Content is aligned to the top of the layout box.
center
- Content is centered vertically within the layout box.
bottom
- Content is aligned to the bottom of the layout box.
This property has no effect when
content_height
is greater thanheight
(in which case the content is aligned to the top) or whenheight
isNone
(in which case there is no vertical layout box dimension).Type: str
-
document
¶ Document to display.
For
IncrementalTextLayout
it is far more efficient to modify a document in-place than to replace the document instance on the layout.Type: AbstractDocument
-
dpi
¶ Get DPI used by this layout.
Type: float
-
group
¶
-
height
¶ Height of the layout.
Type: int
-
multiline
¶ Set if multiline layout is enabled.
If multiline is False, newline and paragraph characters are ignored and text is not word-wrapped. If True, the text is word-wrapped only if the wrap_lines is True.
Type: bool
-
position
¶ The (X, Y, Z) coordinates of the layout, as a tuple.
See also
anchor_x
, andanchor_y
.Type: (int, int, int)
-
rotation
¶ Rotation of the layout.
Type: float
-
visible
¶ True if the layout will be drawn.
Type: bool
-
width
¶ Width of the layout.
This property has no effect if multiline is False or wrap_lines is False.
Type: int
-
y
¶ Y coordinate of the layout.
See also anchor_y.
Type: int
-
z
¶ Z coordinate of the layout.
Type: int
-
class
TextLayoutGroup
(texture, program, order=1, parent=None)¶ -
set_state
()¶ Apply the OpenGL state change.
The default implementation does nothing.
-
unset_state
()¶ Repeal the OpenGL state change.
The default implementation does nothing.
-
-
get_default_decoration_shader
()¶
-
get_default_image_layout_shader
()¶
-
get_default_layout_shader
()¶