 |
CUGL 2.1
Cornell University Game Library
|
|
CUGL 2.1
Cornell University Game Library
|
#include <CUTouchscreen.h>
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 |
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.
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)>
| event | The touch event for this press/release |
| focus | Whether the listener currently has focus |
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)>
| event | The touch event for this movement |
| previous | The previous position of the touch |
| focus | Whether the listener currently has focus |
|
inlineprotected |
Creates and initializes a new touch screen device.
WARNING: Never allocate a touch screen device directly. Always use the Input#activate() method instead.
|
inlineprotectedvirtual |
Deletes this input device, disposing of all resources
| 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.
| key | The identifier for the listener |
| listener | The listener to add |
| 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.
| key | The identifier for the listener |
| listener | The listener to add |
| 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.
| key | The identifier for the listener |
| listener | The listener to add |
|
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.
|
overrideprotectedvirtual |
Unintializes this device, returning it to its default state
An uninitialized device may not work without reinitialization.
Reimplemented from cugl::InputDevice.
| 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.
| key | The identifier for the listener |
| 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.
| key | The identifier for the listener |
| 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.
| key | The identifier for the listener |
|
inlineprotected |
Initializes this device, acquiring any necessary resources
| 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.
| key | The identifier for the listener |
|
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.
| eventset | The set to store the event types. |
Implements cugl::InputDevice.
| 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.
| key | The identifier for the listener |
| 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.
| key | The identifier for the listener |
| 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.
| key | The identifier for the listener |
|
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.
| key | The identifier for the focus object |
Reimplemented from cugl::InputDevice.
|
inline |
Returns the number of fingers currently held down.
|
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().
| touch | An identifier for a touch/finger |
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.
| touch | An identifier for a touch/finger |
Returns the position of the finger touch.
If touch is not a finger currently held down, this method will cause an error.
| touch | An identifier for a touch/finger |
|
inline |
Returns true if touch is a finger pressed this animation frame
| touch | An identifier for a touch/finger |
|
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().
| touch | An identifier for a touch/finger |
| const std::vector<TouchID> cugl::Touchscreen::touchSet | ( | ) | const |
Returns the set of identifiers for the fingers currently held down.
|
overrideprotectedvirtual |
Processes an SDL_Event
The dispatcher guarantees that an input device only receives events that it subscribes to.
| event | The input event to process |
| stamp | The event timestamp in CUGL time |
Implements cugl::InputDevice.
|
protected |
The set of listeners called whenever a touch begins
The touch position for the previous animation frame
|
protected |
The set of listeners called whenever a touch ends
|
protected |
The set of listeners called whenever a touch is moved
The touch position for the previous animation frame
1.8.16