CUGL 2.1
Cornell University Game Library
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
cugl::Touchscreen Class Reference

#include <CUTouchscreen.h>

Inheritance diagram for cugl::Touchscreen:
cugl::InputDevice

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< TouchIDtouchSet () 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

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
eventThe touch event for this press/release
focusWhether the listener currently has focus

◆ 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
eventThe touch event for this movement
previousThe previous position of the touch
focusWhether 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 begin listener for a given key (though you may share keys across other listener types). If a listener already exists 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
keyThe identifier for the listener
listenerThe 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 end listener for a given key (though you may share keys across other listener types). If a listener already exists 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
keyThe identifier for the listener
listenerThe 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 motion listener for a given key (though you may share keys across other listener types). If a listener already exists 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
keyThe identifier for the listener
listenerThe 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
keyThe 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
keyThe 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
keyThe 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
keyThe 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
eventsetThe 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
keyThe 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
keyThe 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
keyThe 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 an active listener can have focus. This method returns false if the key does not refer to an active listener (of any type). Note that keys may be shared across listeners of different types, but must be unique for each listener type.

Parameters
keyThe 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
touchAn 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
touchAn 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
touchAn 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
touchAn 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
touchAn 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
eventThe input event to process
stampThe 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: