AceButton
1.0.0
An Adjustable Compact Event-driven (ACE) button library for Arduino.
|
An Adjustable Compact Event-driven (ACE) Button library that debounces and dispatches button events to a user-defined event handler. More...
#include <AceButton.h>
Public Member Functions | |
AceButton (uint8_t pin=0, uint8_t defaultReleasedState=HIGH, uint8_t id=0) | |
Constructor defines parameters of the button that changes from button to button. More... | |
void | init (uint8_t pin=0, uint8_t defaultReleasedState=HIGH, uint8_t id=0) |
Reset the button to the initial constructed state. More... | |
ButtonConfig * | getButtonConfig () ACE_BUTTON_INLINE |
Get the ButtonConfig associated with this Button. More... | |
void | setButtonConfig (ButtonConfig *buttonConfig) ACE_BUTTON_INLINE |
Set the ButtonConfig associated with this Button. More... | |
void | setEventHandler (ButtonConfig::EventHandler eventHandler) ACE_BUTTON_INLINE |
Convenience method to set the event handler. More... | |
uint8_t | getPin () ACE_BUTTON_INLINE |
Get the button's pin number. More... | |
uint8_t | getId () ACE_BUTTON_INLINE |
Get the custom identifier of the button. More... | |
uint8_t | getDefaultReleasedState () |
Get the initial released state of the button, HIGH or LOW. More... | |
uint8_t | getLastButtonState () ACE_BUTTON_INLINE |
Return the button state that was last valid. More... | |
void | check () |
Check state of button and trigger event processing. More... | |
bool | isReleased (uint8_t buttonState) ACE_BUTTON_INLINE |
Returns true if the given buttonState represents a 'Released' state for the button. More... | |
Static Public Attributes | |
static const uint8_t | kEventPressed = 0 |
Button was pressed. More... | |
static const uint8_t | kEventReleased = 1 |
Button was released. More... | |
static const uint8_t | kEventClicked = 2 |
Button was clicked (Pressed and Released within ButtonConfig::getClickDelay()). | |
static const uint8_t | kEventDoubleClicked = 3 |
Button was double-clicked. More... | |
static const uint8_t | kEventLongPressed = 4 |
Button was held down for longer than ButtonConfig::getLongPressDelay()). | |
static const uint8_t | kEventRepeatPressed = 5 |
Button was held down and auto generated multiple presses. More... | |
static const uint8_t | kButtonStateUnknown = 2 |
Button state is unknown. More... | |
An Adjustable Compact Event-driven (ACE) Button library that debounces and dispatches button events to a user-defined event handler.
Supported events types are:
The check() method should be called from the loop() at least 2-3 times during the debouncing time period. For 50 ms delay, the check() method should be called at a minimum of every 15-20 ms. The execution time of check() on a 16 MHz Arduino ATmega328P MCU seems to about about 15 microseconds.
|
explicit |
Constructor defines parameters of the button that changes from button to button.
These parameters don't change during the runtime of the program. Another way to initialize the object is to create an instance using an empty constructor, then use the init() method to initialize the object with these parameters.
Using the constructor often reads better for simple situations where only a single button is used, and it doesn't need to be configured significantly. Using the init() method can make the code be more readable when multiple buttons are used, and they need to be significantly customized. The init() method allows the button configuration code to appear in close proximity to the pinMode() methods which sets up the hardware pins.
pin | The pin number of the button. Default 0. Normally the pin number should be given at construction time. However, the pin number the pin number can be omitted so that the pin number can be assigned at setup() time using the setPin() method. |
defaultReleasedState | The pin state when the button is in the initial released position. Default HIGH. When using a pullup resister (either external or internal) and the button is connected to ground, this should be set to HIGH. When using an external pulldown resister and the button is connected to Vcc (5V or 3.3V), this should be set to LOW. The defaultReleasedState can be assigned using the constructor or the init() method. |
id | This is an optional user-defined identifier for the button. For example, this could be an index into an array of data that is associated with the button. |
void AceButton::check | ( | ) |
Check state of button and trigger event processing.
This method should be called from the loop() method in Arduino every 2-3 times during the getDebounceDelay() time (default 50 ms), so about every 10-20 ms.
The class will still work if called less of than that because the debouncing algorithm may not work correctly.
|
inline |
Get the ButtonConfig associated with this Button.
uint8_t AceButton::getDefaultReleasedState | ( | ) |
Get the initial released state of the button, HIGH or LOW.
|
inline |
Get the custom identifier of the button.
|
inline |
Return the button state that was last valid.
This is a tri-state function. It may return HIGH, LOW or kButtonStateUnknown to indicate that the last state is not known. This method is not for public consumption, it is exposed only for testing purposes. Consider it to be a private method. Use the buttonState parameter provided to the EventHandler.
In a more general multi-threaded environment (which the Arduino is not, fortunately or unfortunately), the getLastButtonState() may have changed from the value of buttonState provided to the event handler. In other words, there is a race-condition.
|
inline |
Get the button's pin number.
void AceButton::init | ( | uint8_t | pin = 0 , |
uint8_t | defaultReleasedState = HIGH , |
||
uint8_t | id = 0 |
||
) |
Reset the button to the initial constructed state.
In particular, getLastButtonState() returns kButtonStateUnknown. The parameters are identical as the parameters in the AceButton() constructor.
|
inline |
Returns true if the given buttonState represents a 'Released' state for the button.
Returns false if the buttonState is 'Pressed' or kButtonStateUnknown.
The HIGH or LOW logical value of buttonState represents different a button position depending on whether the button is wired with a pull-up or a pull-down resister. This method translates the logical level to the physical position which allows the client code to be independent of the physical wiring.
Normally, the eventType given to the EventHandler should be sufficient because the value of the evenType already encodes this information. This method is provided just in case.
|
inline |
Set the ButtonConfig associated with this Button.
|
inline |
Convenience method to set the event handler.
Event handlers are stored in the ButtonConfig object, not in the AceButton object, to save memory. (Multiple buttons are likely to share the same event handler.) So this method is just a pass-through to ButtonConfig::setEventHandler(). If you are using multiple ButtonConfig objects, you should call the ButtonConfig::setEventHandler() method on those objects directly, instead of using this method.
|
static |
Button state is unknown.
This is a third state (different from LOW or HIGH) used when the class is first initialized upon reboot.
|
static |
Button was double-clicked.
(Two clicks within ButtonConfig::getDoubleClickDelay()).
|
static |
Button was pressed.
|
static |
Button was released.
|
static |
Button was held down and auto generated multiple presses.
The first event is triggered after ButtonConfig::getRepeatPressDelay(), then the event fires repeatedly every ButtonConfig::getRepeatPressInterval() until the button is released.