#include <CUPanInput.h>

Inheritance diagram for cugl::PanInput:

Public Types
typedef std::function< void(const PanEvent &event, bool focus)>	Listener

Public Member Functions
bool	isTouchScreen () const

void	setTouchScreen (bool flag)

float	getThreshold () const

void	setThreshold (float threshold)

bool	isFingerSensitive () const

void	setFingerSensitive (bool flag)

bool	isActive () const

const Vec2	getDelta () const

const Vec2	getPan () const

const Vec2	getPosition () const

int	getFingers () const

virtual bool	requestFocus (Uint32 key) override

bool	isListener (Uint32 key) const

const Listener	getBeginListener (Uint32 key) const

const Listener	getEndListener (Uint32 key) const

const Listener	getMotionListener (Uint32 key) const

bool	addBeginListener (Uint32 key, Listener listener)

bool	addEndListener (Uint32 key, Listener listener)

bool	addMotionListener (Uint32 key, Listener listener)

bool	removeBeginListener (Uint32 key)

bool	removeEndListener (Uint32 key)

bool	removeMotionListener (Uint32 key)

Public Member Functions inherited from cugl::InputDevice
Uint32	acquireKey ()

Uint32	currentFocus () const

void	releaseFocus ()

Protected Member Functions
	PanInput ()

virtual	~PanInput ()

bool	init ()

virtual void	dispose () override

virtual void	clearState () override

virtual bool	updateState (const SDL_Event &event, const Timestamp &stamp) override

virtual void	queryEvents (std::vector< Uint32 > &eventset) override

Vec2	getScaledPosition (float x, float y)

Protected Member Functions inherited from cugl::InputDevice
	InputDevice ()

virtual	~InputDevice ()

bool	initWithName (const std::string name)

Protected Attributes
bool	_screen

bool	_active

bool	_fingery

float	_threshold

float	_spread

PanEvent	_event

std::unordered_map< Uint32, Listener >	_beginListeners

std::unordered_map< Uint32, Listener >	_finishListeners

std::unordered_map< Uint32, Listener >	_motionListeners

Protected Attributes inherited from cugl::InputDevice
std::string	_name

Uint32	_focus

Uint32	_nextKey

Friends
class	Input

Additional Inherited Members
Static Public Attributes inherited from cugl::InputDevice
static const Uint32	RESERVED_KEY = UINT32_MAX

Detailed Description

This class is an input device recognizing pan events.

A pan is a gesture where two or more fingers are moved together across the touch device. If the pan is done very quickly, it is often called a swipe. Most UX designers assign different meanings to pans, depending on the number of fingers involved. For example, on Apple devices, two fingers is used to scroll while three moves to a new page.

This input device is a touch device that supports multitouch gestures. This is often the screen itself, but this is not always guaranteed. For example, the trackpad on MacBooks support pans. For that reason, we cannot guarantee that the touches scale with the display. Instead, all gesture information is normalized, with the top left corner of the touch device being (0,0) and the lower right being (1,1).

If you know that the touch device is the screen, and would like to measure the pan in screen coordinates, you should set the screen attribute to true with setTouchScreen. In this case, the pan distance will be scaled to the display. In those cases where the device is known to be the screen (Android, iOS devices), this value starts out as true.

SDL treats pinches, rotations, and pans as all the same gesture. The only way to distinguish them is with the treshold factor. This tells the system to ignore small gestures. In addition, by default, changing the number of fingers restarts the pan. You can disable this feature if you wish.

As with most devices, we provide support for both listeners and polling the mouse. Polling the device will query the touch screen at the start of the frame, but it may miss those case in there are multiple pinch changes in a single animation frame.

Listeners are guaranteed to catch all changes in the pinch size, as long as they are detected by the OS. However, listeners are not called as soon as the event happens. Instead, the events are queued and processed at the start of the animation frame, before the method Application#update(float) is called.

Member Typedef Documentation

◆ Listener

cugl::PanInput::Listener

This type represents a listener for a pan in the PanInput class.

In CUGL, listeners are implemented as a set of callback functions, not as objects. This allows each listener to implement as much or as little functionality as it wants. A listener is identified by a key which should be a globally unique unsigned int.

While pan listeners do not traditionally require focus like a keyboard does, we have included that functionality. While only one listener can have focus at a time, all listeners will receive input from the PanInput device.

The function type is equivalent to

 std::function<void(const PanEvent& event, bool focus)>

Parameters

event	The touch event for this pan event
focus	Whether the listener currently has focus

Constructor & Destructor Documentation

◆ PanInput()

cugl::PanInput::PanInput ( )

protected

Creates and initializes a new pan input device.

WARNING: Never allocate a pan input device directly. Always use the Input#activate() method instead.

◆ ~PanInput()

virtual cugl::PanInput::~PanInput ( )

inlineprotectedvirtual

Deletes this input device, disposing of all resources

Member Function Documentation

◆ addBeginListener()

bool cugl::PanInput::addBeginListener	(	Uint32	key,
		Listener	listener
	)

Adds a pan begin listener for the given object key

There can only be one listener for a given key. If there is already a listener for the key, the method will fail and return false. You must remove a listener before adding a new one for the same key.

This listener is invoked when pan crosses the distance threshold.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns: true if the listener was succesfully added

◆ addEndListener()

bool cugl::PanInput::addEndListener	(	Uint32	key,
		Listener	listener
	)

Adds a pan end listener for the given object key

There can only be one listener for a given key. If there is already a listener for the key, the method will fail and return false. You must remove a listener before adding a new one for the same key.

This listener is invoked when all (but one) fingers in an active pan are released.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns: true if the listener was succesfully added

◆ addMotionListener()

bool cugl::PanInput::addMotionListener	(	Uint32	key,
		Listener	listener
	)

Adds a pan motion listener for the given object key

There can only be one listener for a given key. If there is already a listener for the key, the method will fail and return false. You must remove a listener before adding a new one for the same key.

This listener is invoked when the pan position changes.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns: true if the listener was succesfully added

◆ clearState()

virtual void cugl::PanInput::clearState ( )

overrideprotectedvirtual

Clears the state of this input device, readying it for the next frame.

Many devices keep track of what happened "this" frame. This method is necessary to advance the frame.

Implements cugl::InputDevice.

◆ dispose()

virtual void cugl::PanInput::dispose ( )

overrideprotectedvirtual

Unintializes this device, returning it to its default state

An uninitialized device may not work without reinitialization.

Reimplemented from cugl::InputDevice.

◆ getBeginListener()

const Listener cugl::PanInput::getBeginListener ( Uint32 key ) const

Returns the pan begin listener for the given object key

This listener is invoked when pan crosses the distance threshold.

If there is no listener for the given key, it returns nullptr.

Parameters

key	The identifier for the listener

Returns: the pan begin listener for the given object key

◆ getDelta()

const Vec2 cugl::PanInput::getDelta ( ) const

inline

Returns the change in the pan position since the last animation frame.

Returns: the change in the pan position since the last animation frame.

◆ getEndListener()

const Listener cugl::PanInput::getEndListener ( Uint32 key ) const

Returns the pan end listener for the given object key

This listener is invoked when all (but one) fingers in an active pan are released.

If there is no listener for the given key, it returns nullptr.

Parameters

key	The identifier for the listener

Returns: the pan end listener for the given object key

◆ getFingers()

int cugl::PanInput::getFingers ( ) const

inline

Returns the number of fingers involved in the pan gesture.

This value may change over the course of the pan gesture. However, there are always guaranteed to be at least two fingers.

Returns: the number of fingers involved in the pan gesture.

◆ getMotionListener()

const Listener cugl::PanInput::getMotionListener ( Uint32 key ) const

Returns the pan motion listener for the given object key

This listener is invoked when the pan position changes.

Parameters

key	The identifier for the listener

Returns: the pan motion listener for the given object key

◆ getPan()

const Vec2 cugl::PanInput::getPan ( ) const

inline

Returns the cumulative pan vector since the gesture began.

Returns: the cumulative pan vector since the gesture began.

◆ getPosition()

const Vec2 cugl::PanInput::getPosition ( ) const

inline

Returns the current normalized center of the pan.

Returns: the current normalized center of the pan.

◆ getScaledPosition()

Vec2 cugl::PanInput::getScaledPosition	(	float	x,
		float	y
	)

protected

Returns the scale/unscaled touch position.

The value returned depends on the value of attribute _screen. If this attribute is false, the position is normalized to the unit square.
Otherwise it is scaled to the touch screen.

Returns: the scale/unscaled touch position.

◆ getThreshold()

float cugl::PanInput::getThreshold ( ) const

inline

Returns the distance threshold for pan events.

SDL treats pinches, rotations, and pans as all the same gesture. The only way to distinguish them is with the treshold factor. A pan that covers less distance than the threshold will not be recorded. This tells the system to ignore small gestures.

The correct value for this threshold depends on the attribute touch screen attribute. If this device is a touch screen, it will be measured in points. Otherwise, it is measured as if the touch device where a unit square.

Returns: the distance threshold for pan events.

◆ init()

bool cugl::PanInput::init ( )

inlineprotected

Initializes this device, acquiring any necessary resources

Returns: true if initialization was successful

◆ isActive()

bool cugl::PanInput::isActive ( ) const

inline

Returns true if the device is in the middle of an active pan.

If the device is not an in active pan, all other polling methods will return the default value.

Returns: true if the device is in the middle of an active pan.

◆ isFingerSensitive()

bool cugl::PanInput::isFingerSensitive ( ) const

inline

Returns true if changing the number of fingers interrupts the pan

This only affects the listener interface. When using the polling interface, it is up to the application to determine when a pan starts and stops.

Returns: true if changing the number of fingers interrupts the pan

◆ isListener()

bool cugl::PanInput::isListener ( Uint32 key ) const

Returns true if key represents a listener object

An object is a listener if it is a listener for any of the three actions: pan begin, pan end, or pan change.

Parameters

key	The identifier for the listener

Returns: true if key represents a listener object

◆ isTouchScreen()

bool cugl::PanInput::isTouchScreen ( ) const

inline

Returns true if this device is a touch screen.

This device is not guaranteed to be a touch screen. For example, the trackpad on MacBooks support pans. We do try to make our best guess about whether or not a device is a touch screen, but on some devices this may need to be set manually.

If this value is true, all pan information will scale with the display. Otherwise, the pinch will be normalized to a unit square, where the top left corner of the touch device is (0,0) and the lower right is (1,1). You may want to set this value to false for true cross-platform gesture support.

Returns: true if this device is a touch screen.

◆ queryEvents()

virtual void cugl::PanInput::queryEvents ( std::vector< Uint32 > & eventset )

overrideprotectedvirtual

Determine the SDL events of relevance and store there types in eventset.

An SDL_EventType is really Uint32. This method stores the SDL event types for this input device into the vector eventset, appending them to the end. The Input dispatcher then uses this information to set up subscriptions.

Parameters

eventset The set to store the event types.

Implements cugl::InputDevice.

◆ removeBeginListener()

bool cugl::PanInput::removeBeginListener ( Uint32 key )

Removes the pan begin listener for the given object key

If there is no active listener for the given key, this method fails and returns false.

This listener is invoked when pan crosses the distance threshold.

Parameters

key	The identifier for the listener

Returns: true if the listener was succesfully removed

◆ removeEndListener()

bool cugl::PanInput::removeEndListener ( Uint32 key )

Removes the pan end listener for the given object key

If there is no active listener for the given key, this method fails and returns false.

This listener is invoked when all (but one) fingers in an active pan are released.

Parameters

key	The identifier for the listener

Returns: true if the listener was succesfully removed

◆ removeMotionListener()

bool cugl::PanInput::removeMotionListener ( Uint32 key )

Removes the pan motion listener for the given object key

If there is no active listener for the given key, this method fails and returns false.

This listener is invoked when the pan position changes.

Parameters

key	The identifier for the listener

Returns: true if the listener was succesfully removed

◆ requestFocus()

virtual bool cugl::PanInput::requestFocus ( Uint32 key )

overridevirtual

Requests focus for the given identifier

Only a listener can have focus. This method returns false if key does not refer to an active listener

Parameters

key	The identifier for the focus object

Returns: false if key does not refer to an active listener

Reimplemented from cugl::InputDevice.

◆ setFingerSensitive()

void cugl::PanInput::setFingerSensitive ( bool flag )

inline

Sets whether changing the number of fingers interrupts the pan

This only affects the listener interface. When using the polling interface, it is up to the application to determine when a pan starts and stops.

Parameters

flag	Whether changing the number of fingers interrupts the pan

◆ setThreshold()

void cugl::PanInput::setThreshold ( float threshold )

Sets the distance threshold for pan events.

SDL treats pinches, rotations, and pans as all the same gesture. The only way to distinguish them is with the treshold factor. A pan that covers less distance than the threshold will not be recorded. This tells the system to ignore small gestures.

The correct value for this threshold depends on the attribute touch screen attribute. If this device is a touch screen, it will be measured in points. Otherwise, it is measured as if the touch device where a unit square.

Parameters

threshold The distance threshold for pan events.

◆ setTouchScreen()

void cugl::PanInput::setTouchScreen ( bool flag )

Sets whether this device is a touch screen.

This device is not guaranteed to be a touch screen. For example, the trackpad on MacBooks support pans. We do try to make our best guess about whether or not a device is a touch screen, but on some devices this may need to be set manually.

If this value is true, all pan information will scale with the display. Otherwise, the pinch will be normalized to a unit square, where the top left corner of the touch device is (0,0) and the lower right is (1,1). You may want to set this value to false for true cross-platform gesture support.

Parameters

flag	Whether this device is a touch screen.

◆ updateState()

virtual bool cugl::PanInput::updateState	(	const SDL_Event &	event,
		const Timestamp &	stamp
	)

overrideprotectedvirtual

Processes an SDL_Event

The dispatcher guarantees that an input device only receives events that it subscribes to.

Parameters

event	The input event to process
stamp	The event timestamp in CUGL time

Returns: false if the input indicates that the application should quit.

Implements cugl::InputDevice.

Member Data Documentation

◆ _active

bool cugl::PanInput::_active

protected

Whether or not there is an active pan being processed

◆ _beginListeners

std::unordered_map<Uint32, Listener> cugl::PanInput::_beginListeners

protected

The set of listeners called whenever a pinch begins

◆ _event

PanEvent cugl::PanInput::_event

protected

The pan event data (stored whether or not there is an event)

◆ _fingery

bool cugl::PanInput::_fingery

protected

Whether or not the pan is sensitive to the number of fingers

◆ _finishListeners

std::unordered_map<Uint32, Listener> cugl::PanInput::_finishListeners

protected

The set of listeners called whenever a pinch ends

◆ _motionListeners

std::unordered_map<Uint32, Listener> cugl::PanInput::_motionListeners

protected

The set of listeners called whenever a pinch is moved

◆ _screen

bool cugl::PanInput::_screen

protected

Whether or not this input device is a touch screen

◆ _spread

float cugl::PanInput::_spread

protected

The spread threshold for aborting a pan event

◆ _threshold

float cugl::PanInput::_threshold

protected

The distance threshold for generating a pan event

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

include/cugl/input/gestures/CUPanInput.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Listener

Constructor & Destructor Documentation

◆ PanInput()

◆ ~PanInput()

Member Function Documentation

◆ addBeginListener()

◆ addEndListener()

◆ addMotionListener()

◆ clearState()

◆ dispose()

◆ getBeginListener()

◆ getDelta()

◆ getEndListener()

◆ getFingers()

◆ getMotionListener()

◆ getPan()

◆ getPosition()

◆ getScaledPosition()

◆ getThreshold()

◆ init()

◆ isActive()

◆ isFingerSensitive()

◆ isListener()

◆ isTouchScreen()

◆ queryEvents()

◆ removeBeginListener()

◆ removeEndListener()

◆ removeMotionListener()

◆ requestFocus()

◆ setFingerSensitive()

◆ setThreshold()

◆ setTouchScreen()

◆ updateState()

Member Data Documentation

◆ _active

◆ _beginListeners

◆ _event

◆ _fingery

◆ _finishListeners

◆ _motionListeners

◆ _screen

◆ _spread

◆ _threshold