adafruit_display_text
¶
- class adafruit_display_text.LabelBase(*args: Any, **kwargs: Any)¶
Superclass that all other types of labels will extend. This contains all of the properties and functions that work the same way in all labels.
Note: This should be treated as an abstract base class.
Subclasses should implement
_set_text
,_set_font
, and_set_line_spacing
to have the correct behavior for that type of label.- Parameters:
font (FontProtocol) – A font class that has
get_bounding_box
andget_glyph
. Must include a capital M for measuring character size.text (str) – Text to display
color (int) – Color of all text in RGB hex
background_color (int) – Color of the background, use
None
for transparentline_spacing (float) – Line spacing of text to display
background_tight (bool) – Set
True
only if you want background box to tightly surround text. When set to ‘True’ Padding parameters will be ignored.padding_top (int) – Additional pixels added to background bounding box at top
padding_bottom (int) – Additional pixels added to background bounding box at bottom
padding_left (int) – Additional pixels added to background bounding box at left
padding_right (int) – Additional pixels added to background bounding box at right
anchor_point ((float,float)) – Point that anchored_position moves relative to. Tuple with decimal percentage of width and height. (E.g. (0,0) is top left, (1.0, 0.5): is middle right.)
anchored_position ((int,int)) – Position relative to the anchor_point. Tuple containing x,y pixel coordinates.
scale (int) – Integer value of the pixel scaling
base_alignment (bool) – when True allows to align text label to the baseline. This is helpful when two or more labels need to be aligned to the same baseline
tab_replacement ((int,str)) – tuple with tab character replace information. When (4, “ “) will indicate a tab replacement of 4 spaces, defaults to 4 spaces by tab character
label_direction (str) – string defining the label text orientation. See the subclass documentation for the possible values.
verbose (bool) – print debugging information in some internal functions. Default to False
- property anchor_point: Tuple[float, float]¶
Point that anchored_position moves relative to. Tuple with decimal percentage of width and height. (E.g. (0,0) is top left, (1.0, 0.5): is middle right.)
- property anchored_position: Tuple[int, int]¶
Position relative to the anchor_point. Tuple containing x,y pixel coordinates.
- property bounding_box: Tuple[int, int]¶
An (x, y, w, h) tuple that completely covers all glyphs. The first two numbers are offset from the x, y origin of this group
- property font: fontio.FontProtocol¶
Font to use for text display.
- adafruit_display_text.wrap_text_to_lines(string: str, max_chars: int) List[str] ¶
wrap_text_to_lines function A helper that will return a list of lines with word-break wrapping
- adafruit_display_text.wrap_text_to_pixels(string: str, max_width: int, font: fontio.FontProtocol | None = None, indent0: str = '', indent1: str = '') List[str] ¶
wrap_text_to_pixels function A helper that will return a list of lines with word-break wrapping. Leading and trailing whitespace in your string will be removed. If you wish to use leading whitespace see
indent0
andindent1
parameters.- Parameters:
string (str) – The text to be wrapped.
max_width (int) – The maximum number of pixels on a line before wrapping.
font (FontProtocol) – The font to use for measuring the text.
indent0 (str) – Additional character(s) to add to the first line.
indent1 (str) – Additional character(s) to add to all other lines.
- Returns:
A list of the lines resulting from wrapping the input text at
max_width
pixels size- Return type:
List[str]
adafruit_display_text.label
¶
Displays text labels using CircuitPython’s displayio.
Author(s): Scott Shawcroft
Implementation Notes¶
Hardware:
Software and Dependencies:
Adafruit CircuitPython firmware for the supported boards: https://circuitpython.org/downloads
- class adafruit_display_text.label.Label(*args: Any, **kwargs: Any)¶
A label displaying a string of text. The origin point set by
x
andy
properties will be the left edge of the bounding box, and in the center of a M glyph (if its one line), or the (number of lines * linespacing + M)/2. That is, it will try to have it be center-left as close as possible.- Parameters:
font (FontProtocol) – A font class that has
get_bounding_box
andget_glyph
. Must include a capital M for measuring character size.text (str) – Text to display
color (int|Tuple(int, int, int)) – Color of all text in HEX or RGB
background_color (int|Tuple(int, int, int)|None) – Color of the background, use
None
for transparentline_spacing (float) – Line spacing of text to display
background_tight (bool) – Set
True
only if you want background box to tightly surround text. When set to ‘True’ Padding parameters will be ignored.padding_top (int) – Additional pixels added to background bounding box at top. This parameter could be negative indicating additional pixels subtracted from the background bounding box.
padding_bottom (int) – Additional pixels added to background bounding box at bottom. This parameter could be negative indicating additional pixels subtracted from the background bounding box.
padding_left (int) – Additional pixels added to background bounding box at left. This parameter could be negative indicating additional pixels subtracted from the background bounding box.
padding_right (int) – Additional pixels added to background bounding box at right. This parameter could be negative indicating additional pixels subtracted from the background bounding box.
anchor_point (Tuple(float, float)) – Point that anchored_position moves relative to. Tuple with decimal percentage of width and height. (E.g. (0,0) is top left, (1.0, 0.5): is middle right.)
anchored_position (Tuple(int, int)) – Position relative to the anchor_point. Tuple containing x,y pixel coordinates.
scale (int) – Integer value of the pixel scaling
base_alignment (bool) – when True allows to align text label to the baseline. This is helpful when two or more labels need to be aligned to the same baseline
tab_replacement (Tuple(int, str)) – tuple with tab character replace information. When (4, “ “) will indicate a tab replacement of 4 spaces, defaults to 4 spaces by tab character
label_direction (str) – string defining the label text orientation. There are 5 configurations possibles
LTR
-Left-To-RightRTL
-Right-To-LeftTTB
-Top-To-BottomUPR
-UpwardsDWR
-Downwards. It defaults toLTR
adafruit_display_text.bitmap_label
¶
Text graphics handling for CircuitPython, including text boxes
Author(s): Kevin Matocha
Implementation Notes¶
Hardware:
Software and Dependencies:
Adafruit CircuitPython firmware for the supported boards: https://circuitpython.org/downloads
- class adafruit_display_text.bitmap_label.Label(*args: Any, **kwargs: Any)¶
A label displaying a string of text that is stored in a bitmap. Note: This
bitmap_label.py
library utilizes aBitmap
to display the text. This method is memory-conserving relative tolabel.py
.For further reduction in memory usage, set
save_text=False
(text string will not be stored andline_spacing
andfont
are immutable withsave_text
set toFalse
).The origin point set by
x
andy
properties will be the left edge of the bounding box, and in the center of a M glyph (if its one line), or the (number of lines * linespacing + M)/2. That is, it will try to have it be center-left as close as possible.- Parameters:
font (FontProtocol) – A font class that has
get_bounding_box
andget_glyph
. Must include a capital M for measuring character size.text (str) – Text to display
color (int|Tuple(int, int, int)) – Color of all text in HEX or RGB
background_color (int|Tuple(int, int, int)|None) – Color of the background, use
None
for transparentline_spacing (float) – Line spacing of text to display
background_tight (bool) – Set
True
only if you want background box to tightly surround text. When set to ‘True’ Padding parameters will be ignored.padding_top (int) – Additional pixels added to background bounding box at top
padding_bottom (int) – Additional pixels added to background bounding box at bottom
padding_left (int) – Additional pixels added to background bounding box at left
padding_right (int) – Additional pixels added to background bounding box at right
anchor_point (Tuple(float, float)) – Point that anchored_position moves relative to. Tuple with decimal percentage of width and height. (E.g. (0,0) is top left, (1.0, 0.5): is middle right.)
anchored_position (Tuple(int, int)) – Position relative to the anchor_point. Tuple containing x,y pixel coordinates.
scale (int) – Integer value of the pixel scaling
save_text (bool) – Set True to save the text string as a constant in the label structure. Set False to reduce memory use.
base_alignment (bool) – when True allows to align text label to the baseline. This is helpful when two or more labels need to be aligned to the same baseline
tab_replacement (Tuple(int, str)) – tuple with tab character replace information. When (4, “ “) will indicate a tab replacement of 4 spaces, defaults to 4 spaces by tab character
label_direction (str) – string defining the label text orientation. There are 5 configurations possibles
LTR
-Left-To-RightRTL
-Right-To-LeftUPD
-Upside DownUPR
-UpwardsDWR
-Downwards. It defaults toLTR
verbose (bool) – print debugging information in some internal functions. Default to False
- property bitmap: Bitmap¶
The Bitmap object that the text and background are drawn into.
- Return type:
adafruit_display_text.scrolling_label
¶
Displays text into a fixed-width label that scrolls leftward if the full_text is large enough to need it.
Author(s): Tim Cocks
Implementation Notes¶
Hardware:
Software and Dependencies:
Adafruit CircuitPython firmware for the supported boards: https://circuitpython.org/downloads
- class adafruit_display_text.scrolling_label.ScrollingLabel(*args: Any, **kwargs: Any)¶
ScrollingLabel - A fixed-width label that will scroll to the left in order to show the full text if it’s larger than the fixed-width.
- Parameters:
font – The font to use for the label.
max_characters (int) – The number of characters that sets the fixed-width. Default is 10.
text (str) – The full text to show in the label. If this is longer than
max_characters
then the label will scroll to show everything.animate_time (float) – The number of seconds in between scrolling animation frames. Default is 0.3 seconds.
current_index (int) – The index of the first visible character in the label. Default is 0, the first character. Will increase while scrolling.
- Type:
- property full_text: str¶
The full text to be shown. If it’s longer than
max_characters
then scrolling will occur as needed.- Return str:
The full text of this label.
- property text¶
The full text to be shown. If it’s longer than
max_characters
then scrolling will occur as needed.- Return str:
The full text of this label.
- update(force: bool = False) None ¶
Attempt to update the display. If
animate_time
has elapsed since previews animation frame then move the characters over by 1 index. Must be called in the main loop of user code.- Parameters:
force (bool) – whether to ignore
animation_time
and force the update. Default is False.- Returns:
None