#include <CUTouchscreen.h>

Inheritance diagram for cugl::Touchscreen:

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

typedef std::function< void(const TouchEvent &event, const Vec2 previous, bool focus)>	MotionListener

Public Member Functions
bool	touchDown (TouchID touch) const

bool	touchPressed (TouchID touch) const

bool	touchReleased (TouchID touch)

Vec2	touchPosition (TouchID touch) const

Vec2	touchOffset (TouchID touch) const

unsigned int	touchCount () const

const std::vector< TouchID >	touchSet () const

virtual bool	requestFocus (Uint32 key) override

bool	isListener (Uint32 key) const

const ContactListener	getBeginListener (Uint32 key) const

const ContactListener	getEndListener (Uint32 key) const

const MotionListener	getMotionListener (Uint32 key) const

bool	addBeginListener (Uint32 key, ContactListener listener)

bool	addEndListener (Uint32 key, ContactListener listener)

bool	addMotionListener (Uint32 key, MotionListener 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
	Touchscreen ()

virtual	~Touchscreen ()

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

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

virtual	~InputDevice ()

bool	initWithName (const std::string name)

Protected Attributes
std::unordered_map< TouchID, Vec2 >	_previous

std::unordered_map< TouchID, Vec2 >	_current

std::unordered_map< Uint32, ContactListener >	_beginListeners

std::unordered_map< Uint32, ContactListener >	_finishListeners

std::unordered_map< Uint32, MotionListener >	_moveListeners

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 representing the touch screen.

This input device represents a screen that supports multiple simultaneous touches. Why multitouch is possible, each touch is registered as a separate event. This is ideal when you wish to treat each finger as a separate mouse pointer. However, it can be tricky when you want to recognize complex actions like gestures. For gesture support, we recomment that you use the class (currently unimplemented) GestureInput.

Note that a device may support multitouch without actually having a touch screen. MacBooks or other devices with gesture-enabled trackpads are an example of there. This class is not safe for those devices as it will inappropriately attempt to convert the touch to a screen position.

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 mouse events in a single animation frame. This is a real concern for touch motion events, as SDL will occasionally record more than one of these a frame.

This device is much more suited for listeners than polling. Because touch ids are changing all the time, we purge any touch data once the finger is lifted. This means that there is no way to purge a finger's last position. In addition, listeners are the only way to determine pressure. There is no polling functionality for touch pressure.

Listeners are guaranteed to catch all presses and releases, 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.

Unlike Mouse, the motion listeners are active by default.

Member Typedef Documentation

◆ ContactListener

cugl::Touchscreen::ContactListener

This type represents a listener for a press/release in the Touchscreen 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.

This type of listener only responds to button presses and releases, not touch movement. Listeners are guaranteed to be called at the start of an animation frame, before the method Application#update(float).

The listener does not receive any information indicating whether the event is a press or a release. That is handled when the listener is registered.

While touch 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 Touchscreen device.

The function type is equivalent to

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

Parameters

event	The touch event for this press/release
focus	Whether the listener currently has focus

◆ MotionListener

cugl::Touchscreen::MotionListener

This type represents a listener for movement in the Touchscreen 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.

This type of listener only responds to touch movement, not presses or releases. Listeners are guaranteed to be called at the start of an animation frame, before the method Application#update(float).

In addition the the touch event, the listener will provide the previously registered touch location. This will allow you to determin the relative touch movement.

While touch 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 Touchscreen device.

The function type is equivalent to

 std::function<void(const TouchEvent& event, const Vec2 previous, bool focus)>

Parameters

event	The touch event for this movement
previous	The previous position of the touch
focus	Whether the listener currently has focus

Constructor & Destructor Documentation

◆ Touchscreen()

cugl::Touchscreen::Touchscreen ( )

inlineprotected

Creates and initializes a new touch screen device.

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

◆ ~Touchscreen()

virtual cugl::Touchscreen::~Touchscreen ( )

inlineprotectedvirtual

Deletes this input device, disposing of all resources

Member Function Documentation

◆ addBeginListener()

bool cugl::Touchscreen::addBeginListener	(	Uint32	key,
		ContactListener	listener
	)

Adds a touch 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 a finger is first pressed.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns: true if the listener was succesfully added

◆ addEndListener()

bool cugl::Touchscreen::addEndListener	(	Uint32	key,
		ContactListener	listener
	)

Adds a touch 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 a finger is finally released.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns: true if the listener was succesfully added

◆ addMotionListener()

bool cugl::Touchscreen::addMotionListener	(	Uint32	key,
		MotionListener	listener
	)

Adds a touch 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 touch is moved across the screen.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns: true if the listener was succesfully added

◆ clearState()

virtual void cugl::Touchscreen::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::Touchscreen::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 ContactListener cugl::Touchscreen::getBeginListener ( Uint32 key ) const

Returns the touch begin listener for the given object key

This listener is invoked when a finger is first pressed.

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

Parameters

key	The identifier for the listener

Returns: the touch begin listener for the given object key

◆ getEndListener()

const ContactListener cugl::Touchscreen::getEndListener ( Uint32 key ) const

Returns the touch end listener for the given object key

This listener is invoked when a finger is finally released.

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

Parameters

key	The identifier for the listener

Returns: the touch end listener for the given object key

◆ getMotionListener()

const MotionListener cugl::Touchscreen::getMotionListener ( Uint32 key ) const

Returns the touch motion listener for the given object key

This listener is invoked when the touch is moved across the screen.

Parameters

key	The identifier for the listener

Returns: the touch motion listener for the given object key

◆ init()

bool cugl::Touchscreen::init ( )

inlineprotected

Initializes this device, acquiring any necessary resources

Returns: true if initialization was successful

◆ isListener()

bool cugl::Touchscreen::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: touch begin, touch end, or touch motion.

Parameters

key	The identifier for the listener

Returns: true if key represents a listener object

◆ queryEvents()

virtual void cugl::Touchscreen::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::Touchscreen::removeBeginListener ( Uint32 key )

Removes the touch 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 a finger is first pressed.

Parameters

key	The identifier for the listener

Returns: true if the listener was succesfully removed

◆ removeEndListener()

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

Removes the touch 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 a finger is finally released.

Parameters

key	The identifier for the listener

Returns: true if the listener was succesfully removed

◆ removeMotionListener()

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

Removes the touch 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 touch is moved across the screen.

Parameters

key	The identifier for the listener

Returns: true if the listener was succesfully removed

◆ requestFocus()

virtual bool cugl::Touchscreen::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.

◆ touchCount()

unsigned int cugl::Touchscreen::touchCount ( ) const

inline

Returns the number of fingers currently held down.

Returns: the number of fingers currently held down.

◆ touchDown()

bool cugl::Touchscreen::touchDown ( TouchID touch ) const

inline

Returns true if touch is a finger currenly held down on the screen

If this value returns false, it is unsafe to call either of the methods touchPosition() or touchOffset().

Parameters

touch An identifier for a touch/finger

Returns: true if touch is a finger currenly held down on the screen

◆ touchOffset()

Vec2 cugl::Touchscreen::touchOffset ( TouchID touch ) const

Returns the difference between the current and previous position of touch.

If the finger was just pressed this frame, it will return the current position. If touch is not a finger currently held down, this method will cause an error.

Parameters

touch An identifier for a touch/finger

Returns: the difference between the current and previous position of touch.

◆ touchPosition()

Vec2 cugl::Touchscreen::touchPosition ( TouchID touch ) const

Returns the position of the finger touch.

If touch is not a finger currently held down, this method will cause an error.

Parameters

touch An identifier for a touch/finger

Returns: the position of the finger touch.

◆ touchPressed()

bool cugl::Touchscreen::touchPressed ( TouchID touch ) const

inline

Returns true if touch is a finger pressed this animation frame

Parameters

touch An identifier for a touch/finger

Returns: true if touch is a finger pressed this animation frame

◆ touchReleased()

bool cugl::Touchscreen::touchReleased ( TouchID touch )

inline

Returns true if touch is a finger released this animation frame

The identifer touch will not be in the set touchSet() and it will be unsafe to call either touchPosition() or touchOffset().

Parameters

touch An identifier for a touch/finger

Returns: true if touch is a finger released this animation frame

◆ touchSet()

const std::vector<TouchID> cugl::Touchscreen::touchSet ( ) const

Returns the set of identifiers for the fingers currently held down.

Returns: the set of identifiers for the fingers currently held down.

◆ updateState()

virtual bool cugl::Touchscreen::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

◆ _beginListeners

std::unordered_map<Uint32, ContactListener> cugl::Touchscreen::_beginListeners

protected

The set of listeners called whenever a touch begins

◆ _current

std::unordered_map<TouchID,Vec2> cugl::Touchscreen::_current

protected

The touch position for the previous animation frame

◆ _finishListeners

std::unordered_map<Uint32, ContactListener> cugl::Touchscreen::_finishListeners

protected

The set of listeners called whenever a touch ends

◆ _moveListeners

std::unordered_map<Uint32, MotionListener> cugl::Touchscreen::_moveListeners

protected

The set of listeners called whenever a touch is moved

◆ _previous

std::unordered_map<TouchID,Vec2> cugl::Touchscreen::_previous

protected

The touch position for the previous animation frame

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

include/cugl/input/CUTouchscreen.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ContactListener

◆ MotionListener

Constructor & Destructor Documentation

◆ Touchscreen()

◆ ~Touchscreen()

Member Function Documentation

◆ addBeginListener()

◆ addEndListener()

◆ addMotionListener()

◆ clearState()

◆ dispose()

◆ getBeginListener()

◆ getEndListener()

◆ getMotionListener()

◆ init()

◆ isListener()

◆ queryEvents()

◆ removeBeginListener()

◆ removeEndListener()

◆ removeMotionListener()

◆ requestFocus()

◆ touchCount()

◆ touchDown()

◆ touchOffset()

◆ touchPosition()

◆ touchPressed()

◆ touchReleased()

◆ touchSet()

◆ updateState()

Member Data Documentation

◆ _beginListeners

◆ _current

◆ _finishListeners

◆ _moveListeners

◆ _previous