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`
	)

inlineexplicit

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`
	)

inlineexplicit

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AceButton() [1/2]

◆ AceButton() [2/2]

Member Function Documentation

◆ check()

◆ checkState()

◆ eventName()

◆ getLastButtonState()

◆ init() [1/2]

◆ init() [2/2]

◆ isPressedRaw()

◆ isReleased()

◆ setButtonConfig()

◆ setEventHandler()

Member Data Documentation

◆ kButtonStateUnknown

◆ kEventDoubleClicked

◆ kEventHeartBeat

◆ kEventLongReleased

◆ kEventRepeatPressed