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 = '', outline_accent_ranges: List[Tuple[int, int, int]] | None = None) → 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.

  • outline_accent_ranges (list) – List of outline accent ranges in the form of tuple (range_start, range_end, outline_size).

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, Tim Cocks

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.

Optionally supports:

  • Accented ranges of text with different colors

  • Outline stroke around the text

  • Fixed-width scrolling “marquee”

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) – The full text to show in the label. If this is longer than max_characters then the label will scroll to show everything.

  • 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

  • outline_color (Optional[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. Defaults to 1 pixel.

  • color_palette (Optional[displayio.Palette]) – The palette to use for the Label. Indexes 0, 1, and 2 will be filled with background, foreground, and outline colors automatically. Indexes 3 and above can be used for accent colors.

  • max_characters (Optional[int]) – The number of characters that sets the fixed-width. Default is None for unlimited width and no scrolling

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

property accent_ranges

The list of ranges that are accented. :return: List of Tuples containing (start, end, foreground_color, background_color).

add_accent_range(start, end, foreground_color, background_color, accent_type='foreground_background')

Set a range of text to get accented with the specified colors.

Parameters:

  • start – The start index of the range of text to accent, inclusive.

  • end – The end index of the range of text to accent, exclusive.

  • foreground_color – The color index within color_palette to use for the accent foreground color.

  • background_color – The color index within color_palette to use for the accent background color.

  • accent_type – The type of accent to use, either “foreground_background” or “outline”

Returns:

None

add_accent_to_substring(substring, foreground_color, background_color, accent_type='foreground_background', start=0)

Add accent to the first occurrence of substring found in the labels text, starting from start.

Parameters:

  • substring – the substring to accent within the text.

  • foreground_color – The color index within color_palette to use for the accent foreground color.

  • background_color – The color index within color_palette to use for the accent background color.

  • accent_type – The type of accent to use, either “foreground_background” or “outline”

  • start – The index within text to start searching for the substring. Defaults is 0 to search the whole text.

Returns:

True if the substring was found, False otherwise.

property bitmap: Bitmap

The Bitmap object that the text and background are drawn into.

Return type:

displayio.Bitmap

clear_accent_ranges()

Remove all accents from the text. All text will return to default foreground and background colors.

Returns:

None

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 max_characters

The maximum number of characters to display on screen.

Return int:

The maximum character length of this label.

property outline_color

Color of the outline to draw around the text. Or None for no outline.

property outline_size

Stroke size of the outline to draw around the text.

remove_accent_from_substring(substring, start=0)
Remove the accent for the first instance of the specified substring

starting at start.

Parameters:

  • substring – the substring to accent within the text.

  • start – The index within text to start searching for the substring. Defaults is 0 to search the whole text.

Returns:

True if the substring was found, False otherwise.

remove_accent_range(start)

Remove the accent that starts at the specified index within the text.

Parameters:

start – The start index of the range of accented text, inclusive.

Returns:

None

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.

property tilegrid: TileGrid

The TileGrid that contains the Bitmap for this Label.

update(force: bool = False) → bool

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:

bool updated: whether anything changed and the display needs to be refreshed.

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

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

The width of the label determined from the bounding box.