adafruit_display_text

class adafruit_display_text.LabelBase(font, x: int = 0, y: int = 0, text: str = '', color: int = 16777215, background_color: int = None, line_spacing: float = 1.25, background_tight: bool = False, padding_top: int = 0, padding_bottom: int = 0, padding_left: int = 0, padding_right: int = 0, anchor_point: Tuple[float, float] = None, anchored_position: Tuple[int, int] = None, scale: int = 1, base_alignment: bool = False, tab_replacement: Tuple[int, str] = (4, ' '), label_direction: str = 'LTR', **kwargs)

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 (Font) – 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.
anchor_point

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

Position relative to the anchor_point. Tuple containing x,y pixel coordinates.

background_color

Color of the background as an RGB hex number.

bounding_box

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

color

Color of the text as an RGB hex number.

font

Font to use for text display.

height

The height of the label determined from the bounding box.

label_direction

Set the text direction of the label

line_spacing

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)

scale

Set the scaling of the label, in integer values

text

Text to be displayed.

width

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=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 (Font) – 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(font, **kwargs)

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 (Font) – 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. 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 ((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. 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(font, save_text=True, **kwargs)

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 (Font) – 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
  • 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 ((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
bitmap

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

Return type:displayio.Bitmap