diff --git a/adafruit_display_text/__init__.py b/adafruit_display_text/__init__.py index e7e91be..9ab6725 100644 --- a/adafruit_display_text/__init__.py +++ b/adafruit_display_text/__init__.py @@ -8,14 +8,21 @@ """ try: - from typing import List, Tuple + from typing import Optional, Union, List, Tuple + from fontio import BuiltinFont + from adafruit_bitmap_font.bdf import BDF + from adafruit_bitmap_font.pcf import PCF except ImportError: pass from displayio import Group, Palette def wrap_text_to_pixels( - string: str, max_width: int, font=None, indent0: str = "", indent1: str = "" + string: str, + max_width: int, + font: Optional[Union[BuiltinFont, BDF, PCF]] = None, + indent0: str = "", + indent1: str = "", ) -> List[str]: # pylint: disable=too-many-branches, too-many-locals @@ -27,7 +34,8 @@ def wrap_text_to_pixels( :param str string: The text to be wrapped. :param int max_width: The maximum number of pixels on a line before wrapping. - :param Font font: The font to use for measuring the text. + :param font: The font to use for measuring the text. + :type font: ~BuiltinFont, ~BDF, or ~PCF :param str indent0: Additional character(s) to add to the first line. :param str indent1: Additional character(s) to add to all other lines. @@ -164,8 +172,9 @@ class LabelBase(Group): Subclasses should implement ``_set_text``, ``_set_font``, and ``_set_line_spacing`` to have the correct behavior for that type of label. - :param Font font: A font class that has ``get_bounding_box`` and ``get_glyph``. + :param font: A font class that has ``get_bounding_box`` and ``get_glyph``. Must include a capital M for measuring character size. + :type font: ~BuiltinFont, ~BDF, or ~PCF :param str text: Text to display :param int color: Color of all text in RGB hex :param int background_color: Color of the background, use `None` for transparent @@ -192,7 +201,7 @@ class LabelBase(Group): def __init__( self, - font, + font: Union[BuiltinFont, BDF, PCF], x: int = 0, y: int = 0, text: str = "", @@ -278,15 +287,15 @@ def _get_ascent_descent(self) -> Tuple[int, int]: return ascender_max, descender_max @property - def font(self) -> None: + def font(self) -> Union[BuiltinFont, BDF, PCF]: """Font to use for text display.""" return self._font - def _set_font(self, new_font) -> None: + def _set_font(self, new_font: Union[BuiltinFont, BDF, PCF]) -> None: raise NotImplementedError("{} MUST override '_set_font'".format(type(self))) @font.setter - def font(self, new_font) -> None: + def font(self, new_font: Union[BuiltinFont, BDF, PCF]) -> None: self._set_font(new_font) @property @@ -435,5 +444,5 @@ def label_direction(self, new_label_direction: str) -> None: raise RuntimeError("Please provide a valid text direction") self._set_label_direction(new_label_direction) - def _replace_tabs(self, text): + def _replace_tabs(self, text: str) -> str: return self._tab_text.join(text.split("\t")) diff --git a/adafruit_display_text/bitmap_label.py b/adafruit_display_text/bitmap_label.py index fc6716b..dd72a45 100755 --- a/adafruit_display_text/bitmap_label.py +++ b/adafruit_display_text/bitmap_label.py @@ -28,7 +28,10 @@ try: - from typing import Tuple + from typing import Union, Optional, Tuple + from fontio import BuiltinFont + from adafruit_bitmap_font.bdf import BDF + from adafruit_bitmap_font.pcf import PCF except ImportError: pass @@ -51,8 +54,9 @@ class Label(LabelBase): 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. - :param Font font: A font class that has ``get_bounding_box`` and ``get_glyph``. + :param font: A font class that has ``get_bounding_box`` and ``get_glyph``. Must include a capital M for measuring character size. + :type font: ~BuiltinFont, ~BDF, or ~PCF :param str text: Text to display :param int color: Color of all text in RGB hex :param int background_color: Color of the background, use `None` for transparent @@ -80,7 +84,9 @@ class Label(LabelBase): configurations possibles ``LTR``-Left-To-Right ``RTL``-Right-To-Left ``UPD``-Upside Down ``UPR``-Upwards ``DWR``-Downwards. It defaults to ``LTR``""" - def __init__(self, font, save_text=True, **kwargs) -> None: + def __init__( + self, font: Union[BuiltinFont, BDF, PCF], save_text: bool = True, **kwargs + ) -> None: self._bitmap = None @@ -102,10 +108,10 @@ def __init__(self, font, save_text=True, **kwargs) -> None: def _reset_text( self, - font=None, - text: str = None, - line_spacing: float = None, - scale: int = None, + font: Optional[Union[BuiltinFont, BDF, PCF]] = None, + text: Optional[str] = None, + line_spacing: Optional[float] = None, + scale: Optional[int] = None, ) -> None: # pylint: disable=too-many-branches, too-many-statements @@ -247,13 +253,15 @@ def _reset_text( self.anchored_position = self._anchored_position @staticmethod - def _line_spacing_ypixels(font, line_spacing: float) -> int: + def _line_spacing_ypixels( + font: Union[BuiltinFont, BDF, PCF], line_spacing: float + ) -> int: # Note: Scaling is provided at the Group level return_value = int(line_spacing * font.get_bounding_box()[1]) return return_value def _text_bounding_box( - self, text: str, font + self, text: str, font: Union[BuiltinFont, BDF, PCF] ) -> Tuple[int, int, int, int, int, int]: # pylint: disable=too-many-locals @@ -333,9 +341,9 @@ def _text_bounding_box( def _place_text( self, - bitmap, + bitmap: displayio.Bitmap, text: str, - font, + font: Union[BuiltinFont, BDF, PCF], xposition: int, yposition: int, skip_index: int = 0, # set to None to write all pixels, other wise skip this palette index @@ -432,10 +440,10 @@ def _place_text( def _blit( self, - bitmap, # target bitmap + bitmap: displayio.Bitmap, # target bitmap x: int, # target x upper left corner y: int, # target y upper left corner - source_bitmap, # source bitmap + source_bitmap: displayio.Bitmap, # source bitmap x_1: int = 0, # source x start y_1: int = 0, # source y start x_2: int = None, # source x end @@ -509,7 +517,7 @@ def _set_line_spacing(self, new_line_spacing: float) -> None: else: raise RuntimeError("line_spacing is immutable when save_text is False") - def _set_font(self, new_font) -> None: + def _set_font(self, new_font: Union[BuiltinFont, BDF, PCF]) -> None: self._font = new_font if self._save_text: self._reset_text(font=new_font, scale=self.scale) @@ -519,7 +527,7 @@ def _set_font(self, new_font) -> None: def _set_text(self, new_text: str, scale: int) -> None: self._reset_text(text=self._replace_tabs(new_text), scale=self.scale) - def _set_background_color(self, new_color): + def _set_background_color(self, new_color: Optional[int]): self._background_color = new_color if new_color is not None: self._palette[0] = new_color @@ -536,7 +544,7 @@ def _get_valid_label_directions(self) -> Tuple[str, ...]: return "LTR", "RTL", "UPD", "UPR", "DWR" @property - def bitmap(self): + def bitmap(self) -> displayio.Bitmap: """ The Bitmap object that the text and background are drawn into. diff --git a/adafruit_display_text/label.py b/adafruit_display_text/label.py index 943755f..3145c4f 100755 --- a/adafruit_display_text/label.py +++ b/adafruit_display_text/label.py @@ -27,7 +27,10 @@ try: - from typing import Tuple + from typing import Union, Optional, Tuple + from fontio import BuiltinFont + from adafruit_bitmap_font.bdf import BDF + from adafruit_bitmap_font.pcf import PCF except ImportError: pass @@ -44,8 +47,9 @@ class Label(LabelBase): 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. - :param Font font: A font class that has ``get_bounding_box`` and ``get_glyph``. + :param font: A font class that has ``get_bounding_box`` and ``get_glyph``. Must include a capital M for measuring character size. + :type font: ~BuiltinFont, ~BDF, or ~PCF :param str text: Text to display :param int color: Color of all text in RGB hex :param int background_color: Color of the background, use `None` for transparent @@ -79,7 +83,7 @@ class Label(LabelBase): configurations possibles ``LTR``-Left-To-Right ``RTL``-Right-To-Left ``TTB``-Top-To-Bottom ``UPR``-Upwards ``DWR``-Downwards. It defaults to ``LTR``""" - def __init__(self, font, **kwargs) -> None: + def __init__(self, font: Union[BuiltinFont, BDF, PCF], **kwargs) -> None: self._background_palette = Palette(1) self._added_background_tilegrid = False @@ -166,9 +170,11 @@ def _create_background_box(self, lines: int, y_offset: int) -> TileGrid: return tile_grid - def _set_background_color(self, new_color: int) -> None: + def _set_background_color(self, new_color: Optional[int]) -> None: """Private class function that allows updating the font box background color - :param int new_color: color as an RGB hex number.""" + + :param int new_color: Color as an RGB hex number, setting to None makes it transparent + """ if new_color is None: self._background_palette.make_transparent(0) @@ -397,7 +403,7 @@ def _reset_text(self, new_text: str) -> None: self._update_text(str(self._replace_tabs(new_text))) self.anchored_position = current_anchored_position - def _set_font(self, new_font) -> None: + def _set_font(self, new_font: Union[BuiltinFont, BDF, PCF]) -> None: old_text = self._text current_anchored_position = self.anchored_position self._text = "" diff --git a/docs/conf.py b/docs/conf.py index 6a6e475..665c103 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,7 @@ # Uncomment the below if you use native CircuitPython modules such as # digitalio, micropython and busio. List the modules you use. Without it, the # autodoc module docs will fail to generate with a warning. -autodoc_mock_imports = ["displayio"] +autodoc_mock_imports = ["displayio", "adafruit_bitmap_font"] intersphinx_mapping = {