API Reference

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 and get_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 transparent

  • line_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 background_color: int

Color of the background as an RGB hex number.

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 color: int

Color of the text as an RGB hex number.

property font: fontio.FontProtocol

Font to use for text display.

property height: int

The height of the label determined from the bounding box.

property label_direction: str

Set the text direction of the label

property line_spacing: float

The amount of space between lines of text, in multiples of the font’s bounding-box height. (E.g. 1.0 is the bounding-box height)

property scale: int

Set the scaling of the label, in integer values

property text: str

Text to be displayed.

property width: int

The width of the label determined from the bounding box.

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

Parameters:

  • string (str) – The text to be wrapped

  • max_chars (int) – The maximum number of characters on a line before wrapping

Returns:

A list of lines where each line is separated based on the amount of max_chars provided

Return type:

List[str]

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 and indent1 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:

class adafruit_display_text.label.Label(*args: Any, **kwargs: Any)

A label displaying a string of text. The origin point set by x and y 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 and get_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 transparent

  • line_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-Right RTL-Right-To-Left TTB-Top-To-Bottom UPR-Upwards DWR-Downwards. It defaults to LTR

adafruit_display_text.bitmap_label

Text graphics handling for CircuitPython, including text boxes

  • Author(s): Kevin Matocha

Implementation Notes

Hardware:

Software and Dependencies:

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 a Bitmap to display the text. This method is memory-conserving relative to label.py.

For further reduction in memory usage, set save_text=False (text string will not be stored and line_spacing and font are immutable with save_text set to False).

The origin point set by x and y 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 and get_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 transparent

  • line_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-Right RTL-Right-To-Left UPD-Upside Down UPR-Upwards DWR-Downwards. It defaults to LTR

  • 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:

displayio.Bitmap

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:

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:

FontProtocol

property current_index: int

Index of the first visible character.

Return int:

The current index

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

adafruit_display_text.outlined_label

Subclass of BitmapLabel that adds outline color and stroke size functionalities.

  • Author(s): Tim Cocks

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_display_text.outlined_label.OutlinedLabel(*args: Any, **kwargs: Any)

OutlinedLabel - A BitmapLabel subclass that includes arguments and properties for specifying outline_size and outline_color to get drawn as a stroke around the text.

Parameters:

  • outline_color (Union[Tuple, int]) – The color of the outline stroke as RGB tuple, or hex.

  • outline_size (int) – The size in pixels of the outline stroke.

property outline_color

Color of the outline to draw around the text.

property outline_size

Stroke size of the outline to draw around the text.

adafruit_display_text.text_box

Text graphics handling for CircuitPython, including text boxes

  • Author(s): Tim Cocks

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_display_text.text_box.TextBox(*args: Any, **kwargs: Any)

TextBox has a constrained width and optionally height. You set the desired size when it’s initialized it will automatically wrap text to fit it within the allotted size.

Left, Right, and Center alignment of the text within the box are supported.

Parameters:

  • font – The font to use for the TextBox.

  • width – The width of the TextBox in pixels.

  • height – The height of the TextBox in pixels.

  • align – How to align the text within the box, valid values are ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT.

property align

Alignment of the text within the TextBox

property height: int

The height of the label determined from the bounding box.

property text: str

Text to be displayed.

property width: int

The width of the label determined from the bounding box.