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