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

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...

bool	isPressedRaw () ACE_BUTTON_INLINE
	Read the button state directly using ButtonConfig and return true if the button is in the Pressed state. 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...

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

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

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 39 of file AceButton.cpp.

◆ AceButton() [2/2]

ace_button::AceButton::AceButton ( ButtonConfig * buttonConfig )

explicit

Constructor that accepts a ButtonConfig as a dependency.

Dependency injection using this constructor is now recommended over using the setButtonConfig() method because it makes the dependency more clear.

Definition at line 44 of file AceButton.cpp.

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 73 of file AceButton.cpp.

◆ getButtonConfig()

ButtonConfig* ace_button::AceButton::getButtonConfig ( )

inline

Get the ButtonConfig associated with this Button.

Definition at line 143 of file AceButton.h.

◆ getDefaultReleasedState()

uint8_t ace_button::AceButton::getDefaultReleasedState ( )

Get the initial released state of the button, HIGH or LOW.

Definition at line 67 of file AceButton.cpp.

◆ getId()

uint8_t ace_button::AceButton::getId ( )

inline

Get the custom identifier of the button.

Definition at line 174 of file AceButton.h.

◆ getLastButtonState()

uint8_t ace_button::AceButton::getLastButtonState ( )

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 192 of file AceButton.h.

◆ getPin()

uint8_t ace_button::AceButton::getPin ( )

inline

Get the button's pin number.

Definition at line 171 of file AceButton.h.

◆ init()

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 49 of file AceButton.cpp.

◆ isPressedRaw()

bool ace_button::AceButton::isPressedRaw ( )

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 231 of file AceButton.h.

◆ isReleased()

bool ace_button::AceButton::isReleased ( uint8_t buttonState )

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 220 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 152 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.

Definition at line 165 of file AceButton.h.

Member Data Documentation

◆ kButtonStateUnknown

const uint8_t ace_button::AceButton::kButtonStateUnknown = 2

static

Button state is unknown.

This is a third state (different from LOW or HIGH) used when the class is first initialized upon reboot.

Definition at line 90 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 70 of file AceButton.h.

◆ kEventPressed

const uint8_t ace_button::AceButton::kEventPressed = 0

static

Button was pressed.

Definition at line 55 of file AceButton.h.

◆ kEventReleased

const uint8_t ace_button::AceButton::kEventReleased = 1

static

Button was released.

Definition at line 58 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 84 of file AceButton.h.

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

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

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AceButton() [1/2]

◆ AceButton() [2/2]

Member Function Documentation

◆ check()

◆ getButtonConfig()

◆ getDefaultReleasedState()

◆ getId()

◆ getLastButtonState()

◆ getPin()

◆ init()

◆ isPressedRaw()

◆ isReleased()

◆ setButtonConfig()

◆ setEventHandler()

Member Data Documentation

◆ kButtonStateUnknown

◆ kEventDoubleClicked

◆ kEventPressed

◆ kEventReleased

◆ kEventRepeatPressed