Description

The EventButton class is for momentary inputs. The momentary switch (button) must be wired between the pin and GND.

EventButton is probably the easiest way to implement a button - a single function and four lines of code gives you information on all types of user inputs.

The following InputEventTypes are fired by EventButton:

InputEventType::ENABLED - fired when the input is enabled.
InputEventType::DISABLED - fired when the input is disabled.
InputEventType::IDLE - fired after no other event (except ENABLED & DISABLED) has been fired for a specified time. Each input can define its own idle timeout. Default is 10 seconds.
InputEventType::PRESSED - fired after (as) a button is pressed
InputEventType::RELEASED - fired after a button is released.
InputEventType::CLICKED - fired after RELEASED if not LONG_CLICKED and button is pressed and released once.
InputEventType::DOUBLE_CLICKED - fired after RELEASED if not LONG_CLICKED and button is pressed and released twice.
InputEventType::MULTI_CLICKED - fired after RELEASED if not LONG_CLICKED and button is pressed and released more than twice (no limit!). The method clickCount() returns the number of clicks.
InputEventType::LONG_PRESS - fired during a long press (hence change of tense). Will repeat by default but this can be turned off.
InputEventType::LONG_CLICKED - fired after a long press.

#include <EventButton.h>

Inheritance diagram for EventButton:

[legend]

Public Member Functions
Constructors
	EventButton (byte buttonPin, bool useDefaultDebouncer=true)
	Construct an EventButton with a GPIO pin. More...

	EventButton (PinAdapter *_pinAdapter, bool useDefaultDebouncer=true)
	Construct a new EventButton with a PinAdapter and optionally use the default debouncer. More...

	EventButton (PinAdapter _pinAdapter, DebounceAdapter debounceAdapter)
	Construct a new EventButton with a PinAdapter and a DebounceAdapter. More...

Common Methods
These methods are common to all InputEvent classes. Additional methods for input enable, timeout, event blocking and user ID/value are also inherited from the EventInputBase class.
void	begin ()
	Initialise the EventButton. More...

void	setCallback (CallbackFunction f)
	Set the Callback function. More...

template<typename T >
void	setCallback (T instance, void(T::method)(InputEventType, EventButton &))
	Set the Callback function to a class method. More...

void	unsetCallback () override
	Unset a previously set callback function or method. More...

void	update ()
	Update the state from the pin input. More...

Getting the State
These methods return the current state of the input (as set during the last update() )
uint8_t	clickCount ()
	The number of clicks that have been fired in the MULTI_CLICKED event. More...

uint8_t	longPressCount ()
	The number of times the long press has occurred during a button press. More...

bool	isPressed ()
	Returns true if button is currently pressed.

uint32_t	currentDuration ()
	Duration in milliseconds of the current state. More...

uint32_t	previousDuration ()
	Duration in milliseconds of the previous state. More...

Other Configuration Settings
void	enableLongPressRepeat (bool repeat=true)
	Choose whether to repeat the long press callback. (true by default) More...

void	setLongClickDuration (uint16_t longDurationMs=750)
	Set the number of milliseconds that define the first long click duration. More...

void	setLongPressInterval (uint16_t intervalMs=500)
	Set the number of milliseconds that define the subbsequent long click intervals. More...

void	setMultiClickInterval (uint16_t intervalMs=250)
	Set the multi click interval. More...

void	setDebouncer (DebounceAdapter *debounceAdapter)
	Set the debouncer. Note: When planning to use `setDebouncer()` you must ensure `useDefaultDebouncer` is set to `false` in the button or switch constructor. Previously set debouncers are not deleted. More...

bool	setDebounceInterval (uint16_t intervalMs=10)
	Set the DebounceAdapter debounce interval. Default is 10ms. More...

void	setPressedState (bool state=LOW)
	Set the pin state that represents 'pressed'. By default this is `LOW` (ie pulled down for pressed). More...

Public Member Functions inherited from EventInputBase
bool	isCallbackSet ()
	Returns true if the callback is set.

void	update ()
	Update the state of the input. More...

bool	isEnabled ()
	Returns true if input is enabled. More...

void	enable (bool e=true)
	Enable or disable an input. More...

void	setIdleTimeout (unsigned int timeoutMs=10000)
	Set the idle timeout in milliseconds (default 10000, 10 seconds) More...

unsigned long	msSinceLastEvent ()
	Returns the number of ms since any event was fired for this input.

bool	isIdle ()
	Return true if no activity for longer than setIdleTimeout - irrespective of whether the idle (or changed) callback has been fired. More...

void	resetIdleTimer ()
	Reset the idle timer. The IDLE event will fire setIdleTimeout ms after this is called. More...

void	blockEvent (InputEventType et)
	Stop an event from firing. More...

void	allowEvent (InputEventType et)
	Allow a a previously blocked event tto fire. More...

void	blockAllEvents ()
	Stop all events from firing - usually used in conjunction with allowEvent()

void	allowAllEvents ()
	Clear all blocked events.

bool	isEventAllowed (InputEventType et)
	Returns true if the event is not blocked.

void	setInputId (uint8_t id)
	Set the input ID (for use by user, not used internally). Not unique, default is 0.

uint8_t	getInputId ()
	Get the input ID (for use by user, not used internally). Not unique, default is 0.

void	setInputValue (uint8_t val)
	Set the input value (for use by user, not used internally). Not unique, default is 0.

uint8_t	getInputValue ()
	Get the input value (for use by user, not used internally). Not unique, default is 0.

Protected Types
typedef std::function< void(InputEventType et, EventButton &ie)>	CallbackFunction
	If `std::function` is supported, this creates the callback type.

typedef void(*	CallbackFunction) (InputEventType et, EventButton &)
	Used to create the callback type as pointer if `std::function` is not supported.

Protected Member Functions
void	invoke (InputEventType et) override
	Override of the `EventInputBase::invoke()` virtual method. More...

void	onDisabled () override
	Override base method to reset click and pressed counts. More...

void	changeState (bool newState)
	Change the button state and flag as changed. More...

bool	changedState ()
	Returns true if either pinAdapter, press() or release() changed the button state. More...

bool	changedPinState ()
	Returns true if pinAdapter read() has changed since last call. More...

bool	releasing ()
	Returns true if state has changed and previous state is pressedState. More...

bool	pressing ()
	Returns true if state has changed and previous state is not pressedState. More...

Protected Member Functions inherited from EventInputBase
bool	isInvokable (InputEventType et)

virtual void	invoke (InputEventType et)=0
	To be overriden by derived classes. More...

virtual void	onEnabled ()
	Can be ovrriden by derived classes but base method must be called. More...

virtual void	onDisabled ()
	Can be ovrriden by derived classes but base method must be called. More...

virtual void	onIdle ()
	Can be ovrriden by derived classes but base method must be called. More...

Protected Attributes
CallbackFunction	callbackFunction = nullptr
	The callback function member.

Protected Attributes inherited from EventInputBase
uint8_t	input_id = 0
	Input ID, not used internally.

uint8_t	input_value = 0
	Input value, not used internally.

bool	_enabled = true
	Input enabled flag.

bool	idleFlagged = true
	True if input is idle.

unsigned long	lastEventMs = millis()
	number of milliseconds since the last event

unsigned long	idleTimeout = 10000
	The idle timeout in milliseconds.

bool	callbackIsSet = false
	Required because in C/C++ callback has to be defined in derived classes... :-/.

Constructor & Destructor Documentation

◆ EventButton() [1/3]

EventButton::EventButton	(	byte	pin,
		bool	useDefaultDebouncer = `true`
	)

Construct an EventButton with a GPIO pin.

Parameters

buttonPin Any type of pin and optionally use the default debouncer (default true). By default button contact should pull down to to GND when pressed. This behaviour can be reversed with setPressedState()

GPLv2 Licence https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt

◆ EventButton() [2/3]

EventButton::EventButton	(	PinAdapter *	_pinAdapter,
		bool	useDefaultDebouncer = `true`
	)

Construct a new EventButton with a PinAdapter and optionally use the default debouncer.

Parameters

pinAdapter

◆ EventButton() [3/3]

EventButton::EventButton	(	PinAdapter *	_pinAdapter,
		DebounceAdapter *	debounceAdapter
	)

Construct a new EventButton with a PinAdapter and a DebounceAdapter.

Parameters

pinAdapter
debounceAdapter

Member Function Documentation

◆ begin()

void EventButton::begin ( )

virtual

Initialise the EventButton.

Must be called from within setup()

Implements EventInputBase.

◆ changedPinState()

bool EventButton::changedPinState ( )

protected

Returns true if pinAdapter read() has changed since last call.

Returns: true; false

◆ changedState()

bool EventButton::changedState ( )

protected

Returns true if either pinAdapter, press() or release() changed the button state.

Returns: true; false

◆ changeState()

void EventButton::changeState ( bool newState )

protected

Change the button state and flag as changed.

Parameters

newState

◆ clickCount()

uint8_t EventButton::clickCount ( )

inline

The number of clicks that have been fired in the MULTI_CLICKED event.

This is also set do CLICK and DOUBLE_CLICKED and is reset to zero after any CLICKED event is fired.

Returns: uint8_t Number of clicks

◆ currentDuration()

uint32_t EventButton::currentDuration ( )

Duration in milliseconds of the current state.

Returns: Current state duration in milliseconds

◆ enableLongPressRepeat()

void EventButton::enableLongPressRepeat ( bool repeat = true )

inline

Choose whether to repeat the long press callback. (true by default)

Parameters

repeat Pass true to repeat, false to not repeat.

◆ invoke()

void EventButton::invoke ( InputEventType et )

overrideprotectedvirtual

Override of the EventInputBase::invoke() virtual method.

Parameters

et	Enum of type `InputEventType`

Implements EventInputBase.

◆ longPressCount()

uint8_t EventButton::longPressCount ( )

inline

The number of times the long press has occurred during a button press.

This is incremented even if the setLongPressRepeat is false, so can be read in the LONC_CLICKED event. This is reset to zero after LONG_CLICKED is fired.

Returns: uint8_t A count of long press occurences

◆ onDisabled()

void EventButton::onDisabled ( )

overrideprotectedvirtual

Override base method to reset click and pressed counts.

Reimplemented from EventInputBase.

◆ pressing()

bool EventButton::pressing ( )

inlineprotected

Returns true if state has changed and previous state is not pressedState.

Returns: true; false

◆ previousDuration()

uint32_t EventButton::previousDuration ( )

inline

Duration in milliseconds of the previous state.

Returns: Previous state duration in milliseconds

◆ releasing()

bool EventButton::releasing ( )

inlineprotected

Returns true if state has changed and previous state is pressedState.

Returns: true; false

◆ setCallback() [1/2]

void EventButton::setCallback ( CallbackFunction f )

inline

Set the Callback function.

Parameters

f	A function of type `EventButton::CallbackFunction` type.

◆ setCallback() [2/2]

template<typename T >

void EventButton::setCallback	(	T *	instance,
		void(T::*)(InputEventType, EventButton &)	method
	)

inline

Set the Callback function to a class method.

Note: This method is only available if std:function is supported.

Parameters

instance	The instance of a class implementing a CallbackFunction method.
method	The class method of type `EventButton::CallbackFunction` type.

◆ setDebounceInterval()

bool EventButton::setDebounceInterval ( uint16_t intervalMs = 10 )

Set the DebounceAdapter debounce interval. Default is 10ms.

Returns: true If the debounce interval has been updated; false If the debouncer interval has not been updated (ie no debouncer set)

◆ setDebouncer()

void EventButton::setDebouncer ( DebounceAdapter * debounceAdapter )

Set the debouncer. Note: When planning to use setDebouncer() you must ensure useDefaultDebouncer is set to false in the button or switch constructor. Previously set debouncers are not deleted.

Parameters

debounceAdapter

◆ setLongClickDuration()

void EventButton::setLongClickDuration ( uint16_t longDurationMs = 750 )

inline

Set the number of milliseconds that define the first long click duration.

The LONG_PRESS event will fire after this duration, then repeat at the interval setLongPressInterval(ms) (default 500ms) if enableLongPressRepeat() is true. After the button is released, a LONG_CLICK event will fire.

Parameters

longDurationMs Default 750ms

◆ setLongPressInterval()

void EventButton::setLongPressInterval ( uint16_t intervalMs = 500 )

inline

Set the number of milliseconds that define the subbsequent long click intervals.

If enableLongPressRepeat() is true a LONG_PRESS event will fire every intervalMs after the first LONG_PRESS has fired.

Parameters

intervalMs The interval in milliseconds (default is 500ms).

◆ setMultiClickInterval()

void EventButton::setMultiClickInterval ( uint16_t intervalMs = 250 )

inline

Set the multi click interval.

Parameters

intervalMs The interval in milliseconds between double, triple or multi clicks

◆ setPressedState()

void EventButton::setPressedState ( bool state = LOW )

inline

Set the pin state that represents 'pressed'. By default this is LOW (ie pulled down for pressed).

If you set this value to HIGH, you must also pass INPUT_PULLDOWN to the GpioPinAdapter constructor.

If your board does not support INPUT_PULLDOWN, pass INPUT and use an external resistor.

Parameters

state Either LOW (default) or HIGH

◆ unsetCallback()

void EventButton::unsetCallback ( )

overridevirtual

Unset a previously set callback function or method.

Must be called before the set function or method is destoyed.

Reimplemented from EventInputBase.

◆ update()

void EventButton::update ( )

Update the state from the pin input.

Must be called from within loop()

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

src/EventButton.h
src/EventButton.cpp

Description

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ EventButton() [1/3]

◆ EventButton() [2/3]

◆ EventButton() [3/3]

Member Function Documentation

◆ begin()

◆ changedPinState()

◆ changedState()

◆ changeState()

◆ clickCount()

◆ currentDuration()

◆ enableLongPressRepeat()

◆ invoke()

◆ longPressCount()

◆ onDisabled()

◆ pressing()

◆ previousDuration()

◆ releasing()

◆ setCallback() [1/2]

◆ setCallback() [2/2]

◆ setDebounceInterval()

◆ setDebouncer()

◆ setLongClickDuration()

◆ setLongPressInterval()

◆ setMultiClickInterval()

◆ setPressedState()

◆ unsetCallback()

◆ update()