Add more annotations, improve documentation

Added type annotations for button.py, as well as correcting/updating documentation.

Author: ch4nsuk3

adafruit_button/button.py

@@ -26,36 +26,49 @@
 from adafruit_display_shapes.roundrect import RoundRect
 from adafruit_button.button_base import ButtonBase, _check_color
 
+try:
+    from typing import Optional, Union, Tuple, Any, List
+    from fontio import FontProtocol
+except ImportError:
+    pass
+
 __version__ = "0.0.0+auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Display_Button.git"
 
 
 class Button(ButtonBase):
     # pylint: disable=too-many-instance-attributes, too-many-locals
-    """Helper class for creating UI buttons for ``displayio``.
-
-    :param x: The x position of the button.
-    :param y: The y position of the button.
-    :param width: The width of the button in pixels.
-    :param height: The height of the button in pixels.
-    :param name: The name of the button.
+    """Helper class for creating UI buttons for ``displayio``. Provides the following
+    buttons:
+    RECT: A rectangular button. SHAWDOWRECT adds a drop shadow.
+    ROUNDRECT: A rectangular button with rounded corners. SHADOWROUNDRECT adds
+    a drop shadow.
+
+    :param int x: The x position of the button.
+    :param int y: The y position of the button.
+    :param int width: The width of the button in pixels.
+    :param int height: The height of the button in pixels.
+    :param str name: The name of the button.
     :param style: The style of the button. Can be RECT, ROUNDRECT, SHADOWRECT, SHADOWROUNDRECT.
                   Defaults to RECT.
-    :param fill_color: The color to fill the button. Defaults to 0xFFFFFF.
-    :param outline_color: The color of the outline of the button.
-    :param label: The text that appears inside the button. Defaults to not displaying the label.
-    :param label_font: The button label font.
-    :param label_color: The color of the button label text. Defaults to 0x0.
-    :param selected_fill: Inverts the fill color.
-    :param selected_outline: Inverts the outline color.
-    :param selected_label: Inverts the label color.
+    :param int|Tuple(int, int, int) fill_color: The color to fill the button. Defaults to 0xFFFFFF.
+    :param int|Tuple(int, int, int) outline_color: The color of the outline of the button.
+    :param str label: The text that appears inside the button. Defaults to not displaying the label.
+    :param FontProtocol label_font: The button label font. Defaults to terminalio.FONT
+    :param int|Tuple(int, int, int) label_color: The color of the button label text. Defaults to 0x0.
+    :param int|Tuple(int, int, int) selected_fill: The fill color when the button is selected.
+    Defaults to the inverse of the fill_color.
+    :param int|Tuple(int, int, int) selected_outline: The outline color when the button is selected.
+    Defaults to the inverse of outline_color.
+    :param selected_label: The label color when the button is selected.
+    Defaults to inverting the label_color.
     """
 
-    def _empty_self_group(self):
+    def _empty_self_group(self) -> None:
         while len(self) > 0:
             self.pop()
 
-    def _create_body(self):
+    def _create_body(self) -> None:
         if (self.outline_color is not None) or (self.fill_color is not None):
             if self.style == Button.RECT:
                 self.body = Rect(
@@ -117,21 +130,21 @@ def _create_body(self):
     def __init__(
         self,
         *,
-        x,
-        y,
-        width,
-        height,
-        name=None,
-        style=RECT,
-        fill_color=0xFFFFFF,
-        outline_color=0x0,
-        label=None,
-        label_font=None,
-        label_color=0x0,
-        selected_fill=None,
-        selected_outline=None,
-        selected_label=None,
-        label_scale=None
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+        name: Optional[str] = None,
+        style = RECT,
+        fill_color: Optional[Union[int, tuple[int, int, int]]] = 0xFFFFFF,
+        outline_color: Optional[Union[int, tuple[int, int, int]]] = 0x0,
+        label: Optional[str] = None,
+        label_font: Optional[FontProtocol] = None,
+        label_color: Optional[int] = 0x0,
+        selected_fill: Optional[Union[int, tuple[int, int , int]]] = None,
+        selected_outline: Optional[Union[int, tuple[int, int, int]]] = None,
+        selected_label: Optional[Union[int, tuple[int, int, int]]] = None,
+        label_scale: Optional[int] = 1
     ):
         super().__init__(
             x=x,
@@ -167,7 +180,7 @@ def __init__(
 
         self.label = label
 
-    def _subclass_selected_behavior(self, value):
+    def _subclass_selected_behavior(self, value: Optional[Any]) -> None:
         if self._selected:
             new_fill = self.selected_fill
             new_out = self.selected_outline
@@ -180,7 +193,7 @@ def _subclass_selected_behavior(self, value):
             self.body.outline = new_out
 
     @property
-    def group(self):
+    def group(self) -> "Button":
         """Return self for compatibility with old API."""
         print(
             "Warning: The group property is being deprecated. "
@@ -189,7 +202,7 @@ def group(self):
         )
         return self
 
-    def contains(self, point):
+    def contains(self, point: List[int]) -> bool:
         """Used to determine if a point is contained within a button. For example,
         ``button.contains(touch)`` where ``touch`` is the touch point on the screen will allow for
         determining that a button has been touched.
@@ -199,56 +212,56 @@ def contains(self, point):
         )
 
     @property
-    def fill_color(self):
+    def fill_color(self) -> Optional[int]:
         """The fill color of the button body"""
         return self._fill_color
 
     @fill_color.setter
-    def fill_color(self, new_color):
+    def fill_color(self, new_color: Optional[Union[int, tuple[int, int, int]]]) -> None:
         self._fill_color = _check_color(new_color)
         if not self.selected:
             self.body.fill = self._fill_color
 
     @property
-    def outline_color(self):
+    def outline_color(self) -> Optional[int]:
         """The outline color of the button body"""
         return self._outline_color
 
     @outline_color.setter
-    def outline_color(self, new_color):
+    def outline_color(self, new_color: Optional[Union[int, tuple[int, int, int]]]) -> None:
         self._outline_color = _check_color(new_color)
         if not self.selected:
             self.body.outline = self._outline_color
 
     @property
-    def selected_fill(self):
+    def selected_fill(self) -> Optional[int]:
         """The fill color of the button body when selected"""
         return self._selected_fill
 
     @selected_fill.setter
-    def selected_fill(self, new_color):
+    def selected_fill(self, new_color: Optional[Union[int, tuple[int, int, int]]]) -> None:
         self._selected_fill = _check_color(new_color)
         if self.selected:
             self.body.fill = self._selected_fill
 
     @property
-    def selected_outline(self):
+    def selected_outline(self) -> Optional[int]:
         """The outline color of the button body when selected"""
         return self._selected_outline
 
     @selected_outline.setter
-    def selected_outline(self, new_color):
+    def selected_outline(self, new_color: Optional[Union[int, tuple[int, int, int]]]) -> None:
         self._selected_outline = _check_color(new_color)
         if self.selected:
             self.body.outline = self._selected_outline
 
     @property
-    def width(self):
+    def width(self) -> int:
         """The width of the button"""
         return self._width
 
     @width.setter
-    def width(self, new_width):
+    def width(self, new_width: int) -> None:
         self._width = new_width
         self._empty_self_group()
         self._create_body()
@@ -257,20 +270,20 @@ def width(self, new_width):
         self.label = self.label
 
     @property
-    def height(self):
+    def height(self) -> int:
         """The height of the button"""
         return self._height
 
     @height.setter
-    def height(self, new_height):
+    def height(self, new_height: int) -> None:
         self._height = new_height
         self._empty_self_group()
         self._create_body()
         if self.body:
             self.append(self.body)
         self.label = self.label
 
-    def resize(self, new_width, new_height):
+    def resize(self, new_width: int, new_height: int) -> None:
         """Resize the button to the new width and height given
         :param new_width int the desired width
         :param new_height int the desired height

adafruit_button/button_base.py

@@ -24,7 +24,7 @@
 from displayio import Group
 import terminalio
 try:
-    from typing import Optional, Union, List, Tuple, Any
+    from typing import Optional, Union, Tuple, Any
     from fontio import FontProtocol
 except ImportError:
     pass
@@ -48,9 +48,10 @@ class ButtonBase(Group):
     :param int height: The height of the button in tiles.
     :param str name: A name, or miscellaneous string that is stored on the button.
     :param str label: The text that appears inside the button. Defaults to not displaying the label.
-    :param FontProtocol label_font: The button label font.
-    :param int label_color: The color of the button label text. Defaults to 0x0.
-    :param selected_label: The color of button label text when the button is selected.
+    :param FontProtocol label_font: The button label font. Defaults to terminalio.FONT
+    :param int|Tuple(int, int, int) label_color: The color of the button label text. Defaults to 0x0.
+    :param int|Tuple(int, int, int) selected_label: The color of button label text when the button is selected.
+    :param int label_scale: The scale factor used for the label. Defaults to 1.
     """
 
     def __init__(
@@ -127,7 +128,7 @@ def _subclass_selected_behavior(self, value: Optional[Any]) -> None:
 
     @property
     def selected(self) -> bool:
-        """Selected inverts the colors."""
+        """Returns whether the button is selected."""
         return self._selected
 
     @selected.setter
@@ -146,20 +147,21 @@ def selected(self, value: bool) -> None:
         self._subclass_selected_behavior(value)
 
     @property
-    def selected_label(self) -> int:
-        """The font color of the button when selected"""
+    def selected_label(self) -> Optional[Union[int, tuple[int, int, int]]]:
+        """The font color of the button when selected.
+        If no color is specified it defaults to the inverse of the label_color"""
         return self._selected_label
 
     @selected_label.setter
-    def selected_label(self, new_color: int) -> None:
+    def selected_label(self, new_color: Optional[Union[int, tuple[int, int, int]]]) -> None:
         self._selected_label = _check_color(new_color)
 
     @property
-    def label_color(self) -> int:
+    def label_color(self) -> Optional[Union[int, tuple[int, int, int]]]:
         """The font color of the button"""
         return self._label_color
 
     @label_color.setter
-    def label_color(self, new_color: int) -> None:
+    def label_color(self, new_color: Optional[Union[int, tuple[int, int, int]]]) -> None:
         self._label_color = _check_color(new_color)
         self._label.color = self._label_color