Description

The EventJoystick class contains two EventAnalog inputs configured as a joystick.

The following InputEventTypes are fired by EventJoystick:

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::CHANGED_X - fired on each change of increment on the X axis.
InputEventType::CHANGED_Y - fired on each change of increment on the Y axis.

#include <EventJoystick.h>

Inheritance diagram for EventJoystick:

Public Member Functions
Constructor
	EventJoystick (byte analogX, byte analogY, uint8_t adcBits=10)
	Construct anEventJoystick input. 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, EventJoystick &))
	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 both X and Y pin inputs. More...

Getting the State
These methods return the current state of the input (as set during the last update() The state of the EventAnalog for each axis can be obtained via the public members x and y.
bool	hasChanged ()
	Returns true of the position of either EventAnalog axis has changed since previous update() More...

bool	isEnabled ()
	Returns true if enabled (or if either of the EventAnalg axis are enabled)

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

Setting Required Increments
These methods are used to set the the number of increments to be 'sliced' for both axis
void	setNumIncrements (uint8_t numIncr=10)
	Split the analog range into this number of slices. The default is 10. More...

void	setNumNegativeIncrements (uint8_t numIncr=10)
	Normally increments are set with setNumIncrements() but you can also set the negative and positive sides of 'centre normal' individually. More...

void	setNumPositiveIncrements (uint8_t numIncr=10)
	Normally increments are set with setNumIncrements() but you can also set the negative and positive sides of 'centre normal' individually. More...

Setting Analog start value and centre & outer boundaries
These methods are used to set start value and centre & outer boundaries of the input.
void	setStartValues ()
	Will set the X and Y start values as the current position. More...

void	setCentreBoundary (uint16_t width=200)
	Used to create a central 'dead zone' on the joystick. More...

void	setOuterBoundary (uint16_t width=100)
	Used to allow maximum increments to be reached 'on the diagonal'. More...

Other Configuration Settings
void	setRateLimit (uint16_t ms)
	Limit the rate at which events are fired. More...

void	enableAutoCalibrate (bool allow=true)
	If enableAutoCalibrate is set to true (the default), will do auto calibration, setting the minValue and maxValue for both X and Y axis. 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.

Public Attributes
Axis Members
The underlying X and Y EventAnalog inputs are exposed to allow access to their state.
EventAnalog	x
	The EventAnalog for the X axis.

EventAnalog	y
	The EventAnalog for the Y axis.

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

typedef void(*	CallbackFunction) (InputEventType et, EventJoystick &)
	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	onEnabled () override
	Can be ovrriden by derived classes but base method must be called. More...

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

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

void	onInputCallback (InputEventType et, EventInputBase &ie)

void	onInputXCallback (InputEventType et, EventInputBase &ie)

void	onInputYCallback (InputEventType et, EventInputBase &ie)

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

◆ EventJoystick()

EventJoystick::EventJoystick	(	byte	analogX,
		byte	analogY,
		uint8_t	adcBits = `10`
	)

Construct anEventJoystick input.

The analogPinX and analogPinY parameters must be an analog pins. For ESP32 avoid using pins attached to ADC2 (GPIO 0, 2, 4, 12-15, 25-27) as these are shared by the WiFi module.

For most boards the default adcBits in this constructor will work fine but if your board has an ADC (analog to digital converter) resolution that is higher than the standard Arduino 10 bits, pass the resolution (in bits) of your board.

Parameters

analogX	must be an analog pin
analogY	must be an analog pin
adcBits	ADC width in bits. Default is 10.

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

Member Function Documentation

◆ begin()

void EventJoystick::begin ( )

virtual

Initialise the EventButton.

Must be called from within setup()

Implements EventInputBase.

◆ enableAutoCalibrate()

void EventJoystick::enableAutoCalibrate ( bool allow = true )

If enableAutoCalibrate is set to true (the default), will do auto calibration, setting the minValue and maxValue for both X and Y axis.

This will be done even when input is disabled (ie no callbacks fired)

◆ hasChanged()

bool EventJoystick::hasChanged ( )

Returns true of the position of either EventAnalog axis has changed since previous update()

Returns: true; false

◆ invoke()

void EventJoystick::invoke ( InputEventType et )

overrideprotectedvirtual

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

Parameters

et	Enum of type `InputEventType`

Implements EventInputBase.

◆ isIdle()

bool EventJoystick::isIdle ( )

Return true if no activity on both EventAnalog axis for longer than setIdleTimeout() - irrespective of whether the idle (or changed) callback has been fired.

Returns: true; false

◆ onDisabled()

void EventJoystick::onDisabled ( )

overrideprotectedvirtual

Can be ovrriden by derived classes but base method must be called.

Reimplemented from EventInputBase.

◆ onEnabled()

void EventJoystick::onEnabled ( )

overrideprotectedvirtual

Can be ovrriden by derived classes but base method must be called.

Reimplemented from EventInputBase.

◆ onIdle()

void EventJoystick::onIdle ( )

inlineoverrideprotectedvirtual

Can be ovrriden by derived classes but base method must be called.

Reimplemented from EventInputBase.

◆ onInputCallback()

void EventJoystick::onInputCallback	(	InputEventType	et,
		EventInputBase &	ie
	)

protected

Convert the EventAnalog callbacks to EventJoystic callbacks

◆ onInputXCallback()

void EventJoystick::onInputXCallback	(	InputEventType	et,
		EventInputBase &	ie
	)

protected

Convert the EventAnalog X CHANGED callbacks to CHANGED_X

◆ onInputYCallback()

void EventJoystick::onInputYCallback	(	InputEventType	et,
		EventInputBase &	ie
	)

protected

Convert the EventAnalog Y CHANGED callbacks to CHANGED_Y

◆ setCallback() [1/2]

void EventJoystick::setCallback ( CallbackFunction f )

inline

Set the Callback function.

Parameters

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

◆ setCallback() [2/2]

template<typename T >

void EventJoystick::setCallback	(	T *	instance,
		void(T::*)(InputEventType, EventJoystick &)	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 `EventJoystick::CallbackFunction` type.

◆ setCentreBoundary()

void EventJoystick::setCentreBoundary ( uint16_t width = 200 )

Used to create a central 'dead zone' on the joystick.

It is very difficult to press the joystick button without moving the joystick so with this we can create a central deadzone.

Parameters

width - the analog value

◆ setNumIncrements()

void EventJoystick::setNumIncrements ( uint8_t numIncr = 10 )

Split the analog range into this number of slices. The default is 10.

Note: This library is intended to reduce the usual 0-1024 range of analogRead() to a much smaller, more manageable number of 'slices'. Much higher numbers may produce variable results as a slice width is the ADC resolution (1024) divided by the number of increments.

An InputEventType::CHANGED_X or CHANGED_Y event will be fired each time the increment changes.

Parameters

numIncr The number of desired increments. Should not be more than 20% of the ADC max value.

◆ setNumNegativeIncrements()

void EventJoystick::setNumNegativeIncrements ( uint8_t numIncr = 10 )

Normally increments are set with setNumIncrements() but you can also set the negative and positive sides of 'centre normal' individually.

Parameters

numIncr The number of increments required on the negative side.

◆ setNumPositiveIncrements()

void EventJoystick::setNumPositiveIncrements ( uint8_t numIncr = 10 )

Normally increments are set with setNumIncrements() but you can also set the negative and positive sides of 'centre normal' individually.

Parameters

numIncr The number of increments required on the positive side.

◆ setOuterBoundary()

void EventJoystick::setOuterBoundary ( uint16_t width = 100 )

Used to allow maximum increments to be reached 'on the diagonal'.

Create an outer 'deadzone' where joysticks are notoriously inconsistent or cannot be reach on a diagonal.

Parameters

width - the analog value

◆ setRateLimit()

void EventJoystick::setRateLimit ( uint16_t ms )

Limit the rate at which events are fired.

When moving a joystich fast it can generate a lot of events, so you can rate limit.

Parameters

ms	Number of milliseconds between events

◆ setStartValues()

void EventJoystick::setStartValues ( )

Will set the X and Y start values as the current position.

This calls the the X & Y EventAnalog::setStartPosition() to set the joystick in its 'rest' position.

Called from begin().

◆ unsetCallback()

void EventJoystick::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 EventJoystick::update ( )

Update the state from both X and Y pin inputs.

Must be called from within loop()

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

src/EventJoystick.h
src/EventJoystick.cpp

Description

Public Member Functions

Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ EventJoystick()

Member Function Documentation

◆ begin()

◆ enableAutoCalibrate()

◆ hasChanged()

◆ invoke()

◆ isIdle()

◆ onDisabled()

◆ onEnabled()

◆ onIdle()

◆ onInputCallback()

◆ onInputXCallback()

◆ onInputYCallback()

◆ setCallback() [1/2]

◆ setCallback() [2/2]

◆ setCentreBoundary()

◆ setNumIncrements()

◆ setNumNegativeIncrements()

◆ setNumPositiveIncrements()

◆ setOuterBoundary()

◆ setRateLimit()

◆ setStartValues()

◆ unsetCallback()

◆ update()