Skip to content

Commit

Permalink
Updated the documentation to version 3.0.0
Browse files Browse the repository at this point in the history 
Resolves #12
  • Loading branch information
@EGJ-Moorington
EGJ-Moorington committed Sep 2, 2024
1 parent 873814a commit 6729582
Showing 1 changed file with 69 additions and 32 deletions.
101 changes: 69 additions & 32 deletions button_handler.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,22 +73,22 @@ def __init__(
) -> None:
"""
:param bool enable_multi_press: Sets :attr:`.enable_multi_press`
(whether to track multi presses).
(whether to track multi-presses).
:param float multi_press_interval: Sets :attr:`.multi_press_interval`
(the time frame within which two presses should occur to count as a multi press).
(the time frame within which two presses should occur to count as a multi-press).
:param float long_press_threshold: Sets :attr:`.long_press_threshold`
(the minimum length of a press to count as a long press).
:param int max_multi_press: Sets :attr:`.max_multi_press`
(the maximum amount of presses a multi press can have).
(the maximum amount of presses a multi-press can have).
.. attribute:: enable_multi_press
:type: bool
:value: enable_multi_press = True
Whether to account for the possibility of another short press
following a short press and counting as a multi press.
following a short press and counting as a multi-press.
If set to false, :meth:`ButtonHandler.update`
returns ``SHORT_PRESS`` immediately after a short press.
returns a short press :class:`ButtonInput` object immediately after a short press.
.. attribute:: long_press_threshold
:type: float
Expand All @@ -101,16 +101,16 @@ def __init__(
:type: int
:value: max_multi_press = 2
The maximum amount of button presses that a multi press can be.
:meth:`ButtonHandler.update` returns the appropiate ``_MULTI_PRESS`` immediaetly after
the button has been pressed this many times.
The maximum amount of button presses that a multi-press can be.
:meth:`ButtonHandler.update` returns the appropiate multi-press :class:`ButtonInput`
object immediaetly after the button has been pressed this many times.
.. attribute:: multi_press_interval
:type: float
:value: multi_press_interval = 175
The time frame from a button release within which
another release should occur to count as a multi press.
another release should occur to count as a multi-press.
"""
self.enable_multi_press = enable_multi_press
self.long_press_threshold = long_press_threshold
Expand All @@ -137,8 +137,9 @@ def __init__(
:value: config.enable_multi_press = True
Whether to account for the possibility of another short press
following a short press and counting that as a multi press. If set to false,
:meth:`ButtonHandler.update` returns ``SHORT_PRESS`` immediately after a short press.
following a short press and counting that as a multi-press. If set to false,
:meth:`ButtonHandler.update` returns a short press :class:`ButtonInput`
object immediately after a short press.
.. attribute:: long_press_threshold
:type: float
Expand All @@ -151,16 +152,16 @@ def __init__(
:type: int
:value: config.max_multi_press = 2
The maximum amount of button presses that a multi press can be.
:meth:`ButtonHandler.update` returns the appropiate ``_MULTI_PRESS`` immediaetly after
the button has been pressed this many times.
The maximum amount of button presses that a multi-press can be.
:meth:`ButtonHandler.update` returns the appropiate multi-press :class:`ButtonInput`
object immediaetly after the button has been pressed this many times.
.. attribute:: multi_press_interval
:type: float
:value: config.multi_press_interval = 175
The time frame from a button release within which
another release should occur to count as a multi press.
another release should occur to count as a multi-press.
.. caution:: Attributes with a *leading underscore (_)* are meant for **internal use only**,
and accessing them may cause **unexpected behaviour**. Please consider accessing
Expand Down Expand Up @@ -192,15 +193,15 @@ def __init__(
:value: None
The time (in miliseconds, tracked by :meth:`supervisor.ticks_ms`) that has passed since
the start of the previous press of a multi press. It is set to :type:`None`
the start of the previous press of a multi-press. It is set to :type:`None`
after the time specified by :attr:`.multi_press_interval` has passed.
.. attribute:: _press_count
:type: int
:value: 0
The amount of times the button has been pressed since the last
multi press ended. It is set to 0 if the time set
multi-press ended. It is set to 0 if the time set
by :attr:`.multi_press_interval` passes after a short press.
.. attribute:: _press_start_time
Expand Down Expand Up @@ -257,12 +258,12 @@ def _check_multi_press_timeout(self, current_time: int) -> Union[int, None]:
.. caution:: Methods with a *leading underscore (_)* are meant for **internal use only**,
and calling them may cause **unexpected behaviour**. Please refrain from using them.
Check whether a multi press has ended.
If it has, return the amount of times the button was pressed in that multi press.
Check whether a multi-press has ended.
If it has, return the amount of times the button was pressed in that multi-press.
:param int current_time: The current time, provided by :meth:`supervisor.ticks_ms`.
:return: The amount of times the button was pressed in a multi press,
if a multi press has ended.
:return: The amount of times the button was pressed in a multi-press,
if a multi-press has ended.
:rtype: int or None
"""
if (
Expand Down Expand Up @@ -303,8 +304,8 @@ class ButtonInput:

SHORT_PRESS = 1
DOUBLE_PRESS = 2
LONG_PRESS = "L"
HOLD = "H"
LONG_PRESS = "L"

def __init__(
self,
Expand All @@ -322,7 +323,13 @@ def __init__(
:param int timestamp: Sets :attr:`timestamp` (the time at which the input was performed).
.. type:: InputAction
:canonical: Literal["SHORT_PRESS", "LONG_PRESS", "HOLD", "DOUBLE_PRESS"] | str
:canonical: int | str
Represents the action the :class:`ButtonInput` object represents.
Using a constant defined by :class:`ButtonInput` when available is recommended.
To represent a multi-press, use the number of presses in that multi-press.
Available constants are :const:`SHORT_PRESS`, :const:`DOUBLE_PRESS`,
:const:`HOLD` and :const:`LONG_PRESS`.
.. attribute:: button_number
:type: int
Expand All @@ -344,6 +351,37 @@ def __init__(
The timestamp (in milliseconds, provided by :meth:`supervisor.ticks_ms`)
at which the input was performed.
.. warning:: Variables written in *upper case with underscores* are constants and
should not be modified. Doing so may cause **unexpected behaviour**.
.. data:: SHORT_PRESS
:type: int
:value: 1
Represents a short press to pass as an argument to
parameter `action` in :class:`ButtonInput`.
.. data:: DOUBLE_PRESS
:type: int
:value: 2
Represents a double press to pass as an argument to
parameter `action` in :class:`ButtonInput`.
.. data:: HOLD
:type: str
:value: "H"
Represents a hold action to pass as an argument to
parameter `action` in :class:`ButtonInput`.
.. data:: LONG_PRESS
:type: str
:value: "L"
Represents a long press to pass as an argument to
parameter `action` in :class:`ButtonInput`.
.. caution:: Attributes with a *leading underscore (_)* are meant for
**internal use only**, and accessing them may cause **unexpected behaviour**.
Please consider accessing a *property* (if available) instead.
Expand All @@ -366,10 +404,9 @@ def action(self):
:type: InputAction
:param InputAction action: The action associated with the input.
:raise ValueError: if action is not a valid action. Valid actions are ``LONG_PRESS``,
``HOLD``, ``SHORT_PRESS`` (exactly the same as ``1_MULTI_PRESS``),
``DOUBLE_PRESS`` (exactly the same as ``2_MULTI_PRESS``) and
``x_MULTI_PRESS`` where x is an :type:`int` bigger than 0.
:raise ValueError: if *action* is not a valid action. Valid actions are
:const:`SHORT_PRESS`, :const:`DOUBLE_PRESS`, :const:`HOLD`, :const:`LONG_PRESS`
and any :type:`int` bigger than 0.
"""
return self._action
Expand Down Expand Up @@ -444,15 +481,15 @@ def __init__(
:param keypad.EventQueue event_queue: Sets :attr:`_event_queue`
(the :class:`keypad.EventQueue` object the handler should read events from).
:param set[ButtonInput] callable_inputs: Sets :attr:`callable_inputs`
(the :class:`ButtonInitConfig` objects used to define the callback functions).
(the :class:`ButtonInput` objects used to define the callback functions).
:param int button_amount: The amount of buttons scanned by the :mod:`keypad` scanner
that created the event_queue parameter's argument :class:`keypad.EventQueue` object.
that created the *event_queue* parameter's argument :class:`keypad.EventQueue` object.
:param dict[int, ButtonInitConfig] config: A dictionary containing
:class:`ButtonInitConfig` objects used to initialise :class:`Button` objects.
The dictionary's keys should be the index numbers of the target buttons.
For each button that doesn't have a :class:`ButtonInitConfig` attached to it, an object
containing the default values is created.
:raise ValueError: if *button_amount* is smaller than 1, or if it is not an :type:`int`..
:raise ValueError: if *button_amount* is smaller than 1, or if it is not an :type:`int`.
.. attribute:: callable_inputs
:type: set[ButtonInput]
Expand Down Expand Up @@ -505,7 +542,7 @@ def buttons(self) -> list[Button]:

def update(self) -> set[ButtonInput]:
"""
Check if any button ended a multi press since the last time this method was called,
Check if any button ended a multi-press since the last time this method was called,
process the next :class:`keypad.Event` in :attr:`_event_queue`, call all the relevant
callback functions and return a set of the detected :class:`ButtonInput`\\ s.
Expand Down Expand Up @@ -551,7 +588,7 @@ def _handle_buttons(self) -> set[ButtonInput]:
and calling them may cause **unexpected behaviour**. Please refrain from using them.
Check if any button began being held down since the last time this mehod was called
and if any multi press ended, and return every detected :class:`ButtonInput`.
and if any multi-press ended, and return every detected :class:`ButtonInput`.
:return: A set containing every detected :class:`ButtonInput`.
:rtype: set[ButtonInput]
Expand Down

0 comments on commit 6729582

Please sign in to comment.