Text Layout¶
Mapping a text string to screen coordinates within a widget is called text
layout. The Text widget’s default layout class supports
aligning text to the left, center or right, and can wrap text on space
characters, at any location, or clip text that is off the edge, optionally
inserting an ellipsis character.
Text("Showing some different alignment modes", align=...)
align='left' (default)
+----------------+ +------------------------+
|Showing some | |Showing some different |
|different | |alignment modes |
|alignment modes | +------------------------+
+----------------+
align='center'
+----------------+ +------------------------+
| Showing some | | Showing some different |
| different | | alignment modes |
|alignment modes | +------------------------+
+----------------+
align='right'
+----------------+ +------------------------+
| Showing some| | Showing some different|
| different| | alignment modes|
| alignment modes| +------------------------+
+----------------+
Text("Showing some different wrapping modes\nnewline", wrap=...)
wrap='space' (default)
+----------------+ +------------------------+
|Showing some | |Showing some different |
|different | |wrapping modes |
|wrapping modes | |newline |
|newline | +------------------------+
+----------------+
wrap='any'
+----------------+ +------------------------+
|Showing some dif| |Showing some different w|
|ferent wrapping | |rapping modes |
|modes | |newline |
|newline | +------------------------+
+----------------+
wrap='clip'
+----------------+ +------------------------+
|Showing some dif| |Showing some different w|
|newline | |newline |
+----------------+ +------------------------+
wrap='ellipsis'
+----------------+ +------------------------+
|Showing some di…| |Showing some different …|
|newline | |newline |
+----------------+ +------------------------+
If this is good enough for your application feel free to skip the rest of this section.
See also
Custom Text Layouts¶
The StandardTextLayout is set as the class variable
Text.layout. Individual Text
widgets may use a different layout class, or you can change the default by
setting the Text.layout class variable itself.
A custom text layout class should extend the
TextLayout base class and return text layout
structures from its layout() method.
See also
Text Layout Structures¶
"This is how a string of text might be displayed"
0----5---10---15---20---25---30---35---40---45--
0----5---10---15---+ right_aligned_text_layout = [
| This is how a| [(5, 0), (13, 0, 13)],
| string of text| [(4, 13), (14, 14, 28)],
|might be displayed| [(18, 29, 47)]
+------------------+ ]
The mapping from a text string to where that text will be displayed in the widget is expressed as a text layout structure.
Text layout structures are used both for rendering Text
widgets and for mapping (x, y) positions within a widget back to the
corresponding offsets in the text. The latter is used when moving the cursor in
Edit widgets up and down or by clicking with the mouse.
A text layout structure is a list of one or more line layouts. Each line layout corresponds to a row of text in the widget, starting from its top.
A line layout is a list zero or more of the following tuples, each expressing text to be displayed from left to right:
(column width, starting text offset, ending text offset)
(column width of space characters to insert, text offset or
None)(column width, text offset, new text to insert)``
Tuple A displays a segment of text from the Text widget.
Column width is explicitly specified because some characters within the text
may be zero width or double width.
Tuple B inserts any number of space characters, and if those characters correspond to an offset within the text, that may be specified.
Tuple C allows insertion of arbitrary text. This could be used for hyphenating
split words or any other effect not covered by A or B. The
StandardTextLayout does not currently use this
tuple in its line layouts.
