CUGL 2.3
Cornell University Game Library
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
cugl::SpinGesture Class Reference

#include <CUSpinGesture.h>

Inheritance diagram for cugl::SpinGesture:
cugl::InputDevice

Public Types

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

Public Member Functions

bool isTouchScreen () const
 
void setTouchScreen (bool flag)
 
float getMinimumRadius () const
 
void setMinimumRadius (float radius)
 
float getStability () const
 
void setStability (float stability)
 
bool isActive () const
 
float getDelta () const
 
float getRotation () const
 
const Vec2 getPosition () 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 getChangeListener (Uint32 key) const
 
bool addBeginListener (Uint32 key, Listener listener)
 
bool addEndListener (Uint32 key, Listener listener)
 
bool addChangeListener (Uint32 key, Listener listener)
 
bool removeBeginListener (Uint32 key)
 
bool removeEndListener (Uint32 key)
 
bool removeChangeListener (Uint32 key)
 
- Public Member Functions inherited from cugl::InputDevice
Uint32 acquireKey ()
 
Uint32 currentFocus () const
 
virtual bool requestFocus (Uint32 key)
 
void releaseFocus ()
 

Protected Member Functions

 SpinGesture ()
 
virtual ~SpinGesture ()
 
bool init ()
 
virtual void dispose () override
 
virtual void clearState () override
 
virtual bool updateState (const SDL_Event &event, const Timestamp &stamp) override
 
Vec2 getScaledPosition (float x, float y) const
 
virtual void queryEvents (std::vector< Uint32 > &eventset) override
 
- Protected Member Functions inherited from cugl::InputDevice
 InputDevice ()
 
virtual ~InputDevice ()
 
bool initWithName (const std::string name)
 
virtual void dispose ()
 
virtual void clearState ()=0
 
virtual bool updateState (const SDL_Event &event, const Timestamp &stamp)=0
 
virtual void queryEvents (std::vector< Uint32 > &eventset)=0
 

Protected Attributes

bool _screen
 
bool _active
 
float _radius
 
float _stability
 
SpinEvent _event
 
std::unordered_map< Sint64, Vec2_fingers
 
size_t _updated
 
std::unordered_map< Uint32, Listener_beginListeners
 
std::unordered_map< Uint32, Listener_finishListeners
 
std::unordered_map< Uint32, Listener_changeListeners
 
- 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 spin events.

A spin (or rotation) is a gesture where two or more fingers are rotated about a single point on the device. Rotations and pinches often start with the same initial gesture; the only difference is how the gesture changes over time. For clarity, we have separated these two gestures.

While some platforms allow spins with more than two fingers, currently CUGL is limited to two-finger spins. Multi-finger spins are a candidate for a future CUGL release.

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 pinches. 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 rotational anchor in screen coordinates, you should set the screen attribute to true with setTouchScreen. In this case, the rotation position will be scaled to its poisition on the screen. In those cases where the device is known to be the screen (Android, iOS devices), this value starts out as true.

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 angle changes in a single animation frame.

Listeners are guaranteed to catch all changes in the rotation angle, 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

This type represents a listener for a rotation in the SpinGesture 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 rotation 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 RotationInput device.

The function type is equivalent to

 std::function<void(const RotationInput& event, bool focus)>
Parameters
eventThe touch event for this pinch/zoom
focusWhether the listener currently has focus

Constructor & Destructor Documentation

◆ SpinGesture()

cugl::SpinGesture::SpinGesture ( )
protected

Creates and initializes a new rotation input device.

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

◆ ~SpinGesture()

virtual cugl::SpinGesture::~SpinGesture ( )
inlineprotectedvirtual

Deletes this input device, disposing of all resources

Member Function Documentation

◆ addBeginListener()

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

Adds a rotational 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 the rotation crosses the angular threshold.

Parameters
keyThe identifier for the listener
listenerThe listener to add
Returns
true if the listener was succesfully added

◆ addChangeListener()

bool cugl::SpinGesture::addChangeListener ( Uint32  key,
Listener  listener 
)

Adds a rotational change 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 rotation angle changes.

Parameters
keyThe identifier for the listener
listenerThe listener to add
Returns
true if the listener was succesfully added

◆ addEndListener()

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

Adds a rotational 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 pinch are released.

Parameters
keyThe identifier for the listener
listenerThe listener to add
Returns
true if the listener was succesfully added

◆ clearState()

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

Returns the rotational begin listener for the given object key

This listener is invoked when the rotation crosses the angular threshold.

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

Parameters
keyThe identifier for the listener
Returns
the rotational begin listener for the given object key

◆ getChangeListener()

const Listener cugl::SpinGesture::getChangeListener ( Uint32  key) const

Returns the rotational change listener for the given object key

This listener is invoked when the rotation angle changes.

Parameters
keyThe identifier for the listener
Returns
the rotational change listener for the given object key

◆ getDelta()

float cugl::SpinGesture::getDelta ( ) const
inline

Returns the change in the rotation angle since the last animation frame.

This value is positive if the rotation is counter-clockwise, and negative if it is clockwise. All values are in radians.

Returns
the change in the rotation angle since the last animation frame.

◆ getEndListener()

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

Returns the rotational end listener for the given object key

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

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

Parameters
keyThe identifier for the listener
Returns
the rotational end listener for the given object key

◆ getMinimumRadius()

float cugl::SpinGesture::getMinimumRadius ( ) const
inline

Returns the minimum radius for a spin event.

All spins have an additional rquirement that all the fingers must be separated by a minimum distance. This is a natural requirement for spins, and it greatly reduces the possibility of accidental spins.

If this device is a touch screen, this value should be measured in pixels. Otherwise, this value should be set assuming a unit square, where the top left corner of the touch device is (0,0) and the lower right is (1,1). By default this value is 10% of the length of the diagonal of the touch device.

Returns
the minimum radius for a spin event.

◆ getPosition()

const Vec2 cugl::SpinGesture::getPosition ( ) const
inline

Returns the normalized center of the spin.

This value is defined at the start of the spin gesture and remains unchanged.

Returns
the normalized center of the spin.

◆ getRotation()

float cugl::SpinGesture::getRotation ( ) const

Returns the cumulative angular change since the gesture began.

This value is positive if the rotation is counter-clockwise, and negative if it is clockwise. All values are in radians.

Returns
the cumulative pinch distance since the gesture began.

◆ getScaledPosition()

Vec2 cugl::SpinGesture::getScaledPosition ( float  x,
float  y 
) const
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.

◆ getStability()

float cugl::SpinGesture::getStability ( ) const
inline

Returns the movement stability of a spin event.

A spin will be canceled if it encounters two much "lateral" movement. Here lateral that the centroid of the spin changes significantly from the initial centroid.

If this device is a touch screen, this value should be measured in pixels. Otherwise, this value should be set assuming a unit square, where the top left corner of the touch device is (0,0) and the lower right is (1,1). By default this value is 10% of the length of the diagonal of the touch device.

Returns
the movement stability of a spin event.

◆ init()

bool cugl::SpinGesture::init ( )
inlineprotected

Initializes this device, acquiring any necessary resources

Returns
true if initialization was successful

◆ isActive()

bool cugl::SpinGesture::isActive ( ) const
inline

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

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

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

◆ isListener()

bool cugl::SpinGesture::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: rotation begin, rotation end, or rotation change.

Parameters
keyThe identifier for the listener
Returns
true if key represents a listener object

◆ isTouchScreen()

bool cugl::SpinGesture::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 rotations. 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 rotation information will scale with the display. Otherwise, the rotation angle 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::SpinGesture::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::SpinGesture::removeBeginListener ( Uint32  key)

Removes the rotational 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 the rotation crosses the angular threshold.

Parameters
keyThe identifier for the listener
Returns
true if the listener was succesfully removed

◆ removeChangeListener()

bool cugl::SpinGesture::removeChangeListener ( Uint32  key)

Removes the rotational change 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 rotation angle changes.

Parameters
keyThe identifier for the listener
Returns
true if the listener was succesfully removed

◆ removeEndListener()

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

Removes the rotational 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 rotation are released.

Parameters
keyThe identifier for the listener
Returns
true if the listener was succesfully removed

◆ requestFocus()

virtual bool cugl::SpinGesture::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
keyThe identifier for the focus object
Returns
false if key does not refer to an active listener

Reimplemented from cugl::InputDevice.

◆ setMinimumRadius()

void cugl::SpinGesture::setMinimumRadius ( float  radius)

Sets the minimum radius for a spin event.

All spins have an additional rquirement that all the fingers must be separated by a minimum distance. This is a natural requirement for spins, and it greatly reduces the possibility of accidental spins.

If this device is a touch screen, this value should be measured in pixels. Otherwise, this value should be set assuming a unit square, where the top left corner of the touch device is (0,0) and the lower right is (1,1). By default this value is 10% of the length of the diagonal of the touch device.

Parameters
radiusThe minimum radius for a spin event.

◆ setStability()

void cugl::SpinGesture::setStability ( float  stability)

Sets the movement stability of a spin event.

A spin will be canceled if it encounters two much "lateral" movement. Here lateral that the centroid of the spin changes significantly from the initial centroid.

If this device is a touch screen, this value should be measured in pixels. Otherwise, this value should be set assuming a unit square, where the top left corner of the touch device is (0,0) and the lower right is (1,1). By default this value is 10% of the length of the diagonal of the touch device.

Parameters
stabilityThe movement stability of a spin event.

◆ setTouchScreen()

void cugl::SpinGesture::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 rotations. 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 rotation information will scale with the display. Otherwise, the rotation angle 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
flagWhether this device is a touch screen.

◆ updateState()

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

◆ _active

bool cugl::SpinGesture::_active
protected

Whether or not there is an active rotation being processed

◆ _beginListeners

std::unordered_map<Uint32, Listener> cugl::SpinGesture::_beginListeners
protected

The set of listeners called whenever a pinch begins

◆ _changeListeners

std::unordered_map<Uint32, Listener> cugl::SpinGesture::_changeListeners
protected

The set of listeners called whenever a pinch is moved

◆ _event

SpinEvent cugl::SpinGesture::_event
protected

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

◆ _fingers

std::unordered_map<Sint64, Vec2> cugl::SpinGesture::_fingers
protected

The current finger positions

◆ _finishListeners

std::unordered_map<Uint32, Listener> cugl::SpinGesture::_finishListeners
protected

The set of listeners called whenever a pinch ends

◆ _radius

float cugl::SpinGesture::_radius
protected

The minimum radius for generating a spin event

◆ _screen

bool cugl::SpinGesture::_screen
protected

Whether or not this input device is a touch screen

◆ _stability

float cugl::SpinGesture::_stability
protected

The movement stability for canceling a spin event

◆ _updated

size_t cugl::SpinGesture::_updated
protected

The number of fingers updated this pass


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