Adding icon_widget

adafruit_displayio_layout/widgets/icon_widget.py

@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: 2021 Tim Cocks
+#
+# SPDX-License-Identifier: MIT
+"""
+
+`icon_widget`
+================================================================================
+A touch enabled widget that includes an icon image with a small text label
+centered below it.
+
+* Author(s): Tim Cocks
+
+Implementation Notes
+--------------------
+
+**Hardware:**
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://github.com/adafruit/circuitpython/releases
+
+"""
+
+
+import terminalio
+from displayio import TileGrid
+import adafruit_imageload
+from adafruit_display_text import bitmap_label
+from adafruit_displayio_layout.widgets.control import Control
+from adafruit_displayio_layout.widgets.widget import Widget
+
+
+class IconWidget(Widget, Control):
+
+    """
+    A touch enabled widget that holds an icon image loaded with
+    adafruit_imageload and a text label centered beneath it.
+
+    :param string label_text: the text that will be shown beneath the icon image.
+    :param string icon: the filepath of the bmp image to be used as the icon.
+
+    :param int x: x location the icon widget should be placed. Pixel coordinates.
+    :param int y: y location the icon widget should be placed. Pixel coordinates.
+    :param anchor_point: (X,Y) values from 0.0 to 1.0 to define the anchor point relative to the
+     widget bounding box
+    :type anchor_point: Tuple[float,float]
+    :param int anchored_position: (x,y) pixel value for the location of the anchor_point
+    :type anchored_position: Tuple[int, int]
+    :param int max_size: (Optional) this will get passed through to the
+     displayio.Group constructor. If omitted we default to
+     grid_size width * grid_size height to make room for all (1, 1) sized cells.
+
+    """
+
+    def __init__(self, label_text, icon, **kwargs):
+        super().__init__(**kwargs)
+        image, palette = adafruit_imageload.load(icon)
+        tile_grid = TileGrid(image, pixel_shader=palette)
+        self.append(tile_grid)
+        _label = bitmap_label.Label(
+            terminalio.FONT,
+            scale=1,
+            text=label_text,
+            anchor_point=(0.5, 0),
+            anchored_position=(image.width // 2, image.height),
+        )
+        self.append(_label)
+        self.touch_boundary = (
+            self.x,
+            self.y,
+            image.width,
+            image.height + _label.bounding_box[3],
+        )
+
+    def contains(self, touch_point):  # overrides, then calls Control.contains(x,y)
+
+        """Checks if the IconWidget was touched.  Returns True if the touch_point is
+        within the IconWidget's touch_boundary.
+
+        :param touch_point: x,y location of the screen, converted to local coordinates.
+        :type touch_point: Tuple[x,y]
+        :return: Boolean
+        """
+
+        touch_x = (
+            touch_point[0] - self.x
+        )  # adjust touch position for the local position
+        touch_y = touch_point[1] - self.y
+
+        return super().contains((touch_x, touch_y, 0))

docs/api.rst

@@ -22,3 +22,7 @@
    :inherited-members:
 
 .. inheritance-diagram:: adafruit_displayio_layout.widgets.switch_round
+
+.. automodule:: adafruit_displayio_layout.widgets.icon_widget
+   :members:
+   :member-order: bysource

docs/conf.py

@@ -28,7 +28,13 @@
 # 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", "adafruit_display_shapes"]
+autodoc_mock_imports = [
+    "displayio",
+    "adafruit_display_shapes",
+    "terminalio",
+    "adafruit_imageload",
+    "adafruit_display_text",
+]
 
 
 intersphinx_mapping = {