AceButton 1.10.0 An adjustable, compact, event-driven button library for Arduino.

Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
ace_button::AceButton Class Reference

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...
| AceButton (ButtonConfig *buttonConfig, uint8_t pin=0, uint8_t defaultReleasedState=HIGH, uint8_t id=0)
| Constructor that accepts a ButtonConfig as a dependency. More...
void | init (uint8_t pin=0, uint8_t defaultReleasedState=HIGH, uint8_t id=0)
| Reset the button to the initial constructed state. More...
void | init (ButtonConfig *buttonConfig, uint8_t pin=0, uint8_t defaultReleasedState=HIGH, uint8_t id=0)
| Similar to init(uint8_t, uint8_t, uint8_t) but takes a (ButtonConfig*) as the first parameter. More...
ButtonConfig * | getButtonConfig () const
| Get the ButtonConfig associated with this Button.
void | setButtonConfig (ButtonConfig *buttonConfig)
| Set the ButtonConfig associated with this Button. More...
void | setEventHandler (ButtonConfig::EventHandler eventHandler)
| Convenience method to set the event handler. More...
uint8_t | getPin () const
| Get the button's pin number.
uint8_t | getId () const
| Get the custom identifier of the button.
uint8_t | getDefaultReleasedState () const
| Get the initial released state of the button, HIGH or LOW.
uint8_t | getLastButtonState () const
| Return the button state that was last valid. More...
void | check ()
| Check state of button and trigger event processing. More...
void | checkState (uint8_t buttonState)
| Version of check() used by EncodedButtonConfig. More...
bool | isReleased (uint8_t buttonState) const
| Returns true if the given buttonState represents a 'Released' state for the button. More...
bool | isPressedRaw () const
| Read the button state directly using ButtonConfig and return true if the button is in the Pressed state. More...

## Static Public Member Functions
static __FlashStringHelper * | eventName (uint8_t event)
| Return the human-readable name of the event. More...

## Static Public Attributes
static const uint8_t | kEventPressed = 0
| Button was pressed.
static const uint8_t | kEventReleased = 1
| Button was released.
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 | kEventLongReleased = 6
| Button was released after a long press. More...
static const uint8_t | kEventHeartBeat = 7
| An event that fires every time interval defined by `getHeartBeatInterval()`. More...
static const uint8_t | kButtonStateUnknown = 127
| Button state is unknown. More...

## Detailed Description

An Adjustable Compact Event-driven (ACE) Button library that debounces and dispatches button events to a user-defined event handler.

Supported events types are:

- kEventPressed
- kEventReleased
- kEventClicked
- kEventDoubleClicked
- kEventLongPressed
- kEventRepeatPressed
- kEventLongReleased
- kEventHeartBeat

The check() method should be called from the loop() at least 2-3 times during the debouncing time period. For 20 ms delay, the check() method should be called at a minimum of every 5 ms. The execution time of check() on a 16 MHz Arduino ATmega328P MCU seems to about about 12-14 microseconds.

Definition at line 54 of file AceButton.h.

## Constructor & Destructor Documentation

## ◆ AceButton() [1/2]

ace_button::AceButton::AceButton | ( | uint8_t | pin = `0`,
|  | uint8_t | defaultReleasedState = `HIGH`,
|  | uint8_t | id = `0`
| ) |  |
| inline 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.

Parameters

  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 resistor (either external or internal) and the button is connected to ground, this should be set to HIGH. When using an external pulldown resistor 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.

Definition at line 160 of file AceButton.h.

## ◆ AceButton() [2/2]

ace_button::AceButton::AceButton | ( | ButtonConfig * | buttonConfig,
|  | uint8_t | pin = `0`,
|  | uint8_t | defaultReleasedState = `HIGH`,
|  | uint8_t | id = `0`
| ) |  |
| inline explicit

Constructor that accepts a ButtonConfig as a dependency.

The pin, defaultReleasedState, and id parameters have default values, so do not need to be explicitly set. Dependency injection of ButtonConfig using this constructor is now recommended over using the setButtonConfig() method because it makes the dependency more clear. If this constructor is used to set the pin, defaultReleasedState, and id, then the init() method does not need to be called in the setup().

If you know at compile-time that you will use an alternate ButtonConfig (such as EncodedButtonConfig or LadderButtonConfig) instead of the default system ButtonConfig (getSystemButtonConfig()), then you can save about 30 bytes of flash and 26 bytes of RAM on an AVR processor by using this 4-parameter constructor and passing a `nullptr` for the `buttonConfig` in this constructor, instead of the using the 3-parameter `AceButton()` constructor. The 3-parameter constructor automatically creates and assigns the `buttonConfig` parameter to be the default system ButtonConfig, and the system ButtonConfig sticks around even if it is never used after the constructor. In retrospect, automatically creating a system ButtonConfig in an attempt to simplify the single-button use case was not the best idea, but it is too late to change that behavior without breaking backwards compatibility.

Definition at line 192 of file AceButton.h.

## Member Function Documentation

## ◆ check()

void ace_button::AceButton::check | ( |  | ) |

Check state of button and trigger event processing.

This method should be called from the loop() method in Arduino every 4-5 times during the getDebounceDelay() time (default 20 ms), so about every 5 ms. If this is called less often than that, the debouncing algorithm may not work correctly, which may cause other event detection algorithms to fail.

Definition at line 116 of file AceButton.cpp.

## ◆ checkState()

void ace_button::AceButton::checkState | ( | uint8_t | buttonState | ) |

Version of check() used by EncodedButtonConfig.

NOT for public consumption.

Definition at line 121 of file AceButton.cpp.

## ◆ eventName()

__FlashStringHelper * ace_button::AceButton::eventName | ( | uint8_t | event | ) |
| static

Return the human-readable name of the event.

This is intended to help debugging. If this function is not used, the underlying table of strings will not be compiled into the resulting binary.

Definition at line 79 of file AceButton.cpp.

## ◆ getLastButtonState()

uint8_t ace_button::AceButton::getLastButtonState | ( |  | ) | const
| 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.

Definition at line 292 of file AceButton.h.

## ◆ init() [1/2]

void ace_button::AceButton::init | ( | ButtonConfig * | buttonConfig,
|  | uint8_t | pin = `0`,
|  | uint8_t | defaultReleasedState = `HIGH`,
|  | uint8_t | id = `0`
| ) |  |

Similar to init(uint8_t, uint8_t, uint8_t) but takes a (ButtonConfig*) as the first parameter.

Sometimes it is more convenient to initialize the button in the global setup() function using this method instead of using the constructor.

Definition at line 96 of file AceButton.cpp.

## ◆ init() [2/2]

void ace_button::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.

Definition at line 88 of file AceButton.cpp.

## ◆ isPressedRaw()

bool ace_button::AceButton::isPressedRaw | ( |  | ) | const
| inline

Read the button state directly using ButtonConfig and return true if the button is in the Pressed state.

This method is intended to be used in the global setup() to determine if the button was pressed while the device was booted. This method does not use the check() method, does not perform any debouncing, and does not dispatch events to the EventHandler.

Definition at line 337 of file AceButton.h.

## ◆ isReleased()

bool ace_button::AceButton::isReleased | ( | uint8_t | buttonState | ) | const
| 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 resistor. 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 eventType already encodes this information. This method is provided just in case.

Definition at line 326 of file AceButton.h.

## ◆ setButtonConfig()

void ace_button::AceButton::setButtonConfig | ( | ButtonConfig * | buttonConfig | ) |
| inline

Set the ButtonConfig associated with this Button.

It is recommended that the AceButton(ButtonConfig*) constructor is used instead to make the dependency to ButtonConfig more explicit.

Definition at line 232 of file AceButton.h.

## ◆ setEventHandler()

void ace_button::AceButton::setEventHandler | ( | ButtonConfig::EventHandler | eventHandler | ) |
| 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.

Since v1.6, the event handler can be either a function pointer or an object pointer. The recommended way to set the event handler is to call the setEventHanlder() or the setIEventHandler() on the ButtonConfig object directly using one of the following:

ButtonConfig* config = button.getButtonConfig();
config->setEventHandler(eventHandler);

OR

ButtonConfig* config = button.getButtonConfig();
config->setIEventHandler(&eventHandler);

I decided against deprecating this method because it allows someone to write the simple HelloButton.ino program without having any knowledge of the ButtonConfig object.

Definition at line 266 of file AceButton.h.

## Member Data Documentation

## ◆ kButtonStateUnknown

const uint8_t ace_button::AceButton::kButtonStateUnknown = 127
| static

Button state is unknown.

This is a third state (different from LOW or HIGH) used when the class is first initialized upon reboot. No longer able to use '2' because the new PinStatus enum API contains 'CHANGE' which has a value of 2.

Definition at line 119 of file AceButton.h.

## ◆ kEventDoubleClicked

const uint8_t ace_button::AceButton::kEventDoubleClicked = 3
| static

Button was double-clicked.

(Two clicks within ButtonConfig::getDoubleClickDelay()).

Definition at line 74 of file AceButton.h.

## ◆ kEventHeartBeat

const uint8_t ace_button::AceButton::kEventHeartBeat = 7
| static

An event that fires every time interval defined by `getHeartBeatInterval()`.

This is intended to allow custom subclasses of `IEventHandler` to track the progression of time even when no other event is occurring with a button. For example, this allows the IEventHandler to store the timestamp of the last kEventReleased, then trigger a custom kCustomLongReleased event after (say) 30 seconds after the last kEventReleased. Without the heart beat event, the IEventHandler would not be able to fire off a custom event.

Definition at line 111 of file AceButton.h.

## ◆ kEventLongReleased

const uint8_t ace_button::AceButton::kEventLongReleased = 6
| static

Button was released after a long press.

This event becomes the replacement for kEventReleased if kFeatureSuppressAfterLongPress is enabled. The kFeatureSuppressAfterLongPress allows us to distinguish a simple Pressed from a LongPressed, by using the Released event as a replacement of Pressed. But the suppression prevents us from detecting a Released event from a LongPress (which is sometimes needed). This event can be used as a replacement.

Definition at line 99 of file AceButton.h.

## ◆ kEventRepeatPressed

const uint8_t ace_button::AceButton::kEventRepeatPressed = 5
| 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.

Definition at line 88 of file AceButton.h.

The documentation for this class was generated from the following files:

- /home/brian/src/AceButton/src/ace_button/AceButton.h
- /home/brian/src/AceButton/src/ace_button/AceButton.cpp