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

#include <CUMouse.h>

Inheritance diagram for cugl::Mouse:
cugl::InputDevice

Public Types

enum  PointerAwareness { PointerAwareness::BUTTON, PointerAwareness::DRAG, PointerAwareness::ALWAYS }
 
typedef std::function< void(const MouseEvent &event, Uint8 clicks, bool focus)> ButtonListener
 
typedef std::function< void(const MouseEvent &event, const Vec2 previous, bool focus)> MotionListener
 
typedef std::function< void(const MouseWheelEvent &event, bool focus)> WheelListener
 

Public Member Functions

PointerAwareness getPointerAwareness () const
 
void setPointerAwareness (PointerAwareness awareness)
 
ButtonState buttonDown () const
 
ButtonState buttonUp () const
 
ButtonState buttonPressed () const
 
ButtonState buttonReleased () const
 
Vec2 pointerPosition () const
 
Vec2 pointerOffset () const
 
Vec2 wheelDirection () const
 
virtual bool requestFocus (Uint32 key) override
 
bool isListener (Uint32 key) const
 
const ButtonListener getPressListener (Uint32 key) const
 
const ButtonListener getReleaseListener (Uint32 key) const
 
const MotionListener getDragListener (Uint32 key) const
 
const MotionListener getMotionListener (Uint32 key) const
 
const WheelListener getWheelListener (Uint32 key) const
 
bool addPressListener (Uint32 key, ButtonListener listener)
 
bool addReleaseListener (Uint32 key, ButtonListener listener)
 
bool addDragListener (Uint32 key, MotionListener listener)
 
bool addMotionListener (Uint32 key, MotionListener listener)
 
bool addWheelListener (Uint32 key, WheelListener listener)
 
bool removePressListener (Uint32 key)
 
bool removeReleaseListener (Uint32 key)
 
bool removeDragListener (Uint32 key)
 
bool removeMotionListener (Uint32 key)
 
bool removeWheelListener (Uint32 key)
 
- Public Member Functions inherited from cugl::InputDevice
Uint32 acquireKey ()
 
Uint32 currentFocus () const
 
void releaseFocus ()
 

Protected Member Functions

 Mouse ()
 
virtual ~Mouse ()
 
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

PointerAwareness _awareness
 
ButtonState _lastState
 
ButtonState _currState
 
Vec2 _lastPoint
 
Vec2 _currPoint
 
Vec2 _wheelOffset
 
std::unordered_map< Uint32, ButtonListener_pressListeners
 
std::unordered_map< Uint32, ButtonListener_releaseListeners
 
std::unordered_map< Uint32, MotionListener_moveListeners
 
std::unordered_map< Uint32, MotionListener_dragListeners
 
std::unordered_map< Uint32, WheelListener_wheelListeners
 
- 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 mouse.

This input device represents a standard mouse. Unlike the SDL api, it does not support touch events. If you want access to touch events, you should use the device Touchscreen instead.

As with most devices, we provide support for both listeners and polling the mouse. Polling the mouse will query the mouse state 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 mouse motion events, as SDL will occasionally record more than one of these a frame.

Listeners are also the preferred way to react to mouse wheel events. Mouse wheel events are relative and hard to accumulate in a polling framework.

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.

Motion listeners are not active by default. They must be activated by the method setPointerAwareness(PointerAwareness).

Member Typedef Documentation

◆ ButtonListener

This type represents a listener for button presses/releases in the Mouse 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 mouse 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. On the other hand, the listener will get a counter if the press/release is a sequence of rapid clicks. This is a way of detecting double or even triple clicks. The click counter will continue to increment as long as there is a click every .5 seconds.

While mouse 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 Mouse device.

The function type is equivalent to

 std::function<void(const MouseEvent& event, Uint8 clicks, bool focus)>
Parameters
eventThe mouse event for this press/release
clicksThe number of recent clicks, including this one
focusWhether the listener currently has focus

◆ MotionListener

This type represents a listener for movement in the Mouse 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 mouse movement, not button 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 mouse event, the listener will provide the previously registered mouse location. This will allow you to determin the relative mouse movement.

While mouse 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 Mouse device.

The function type is equivalent to

 std::function<void(const MouseEvent& event, const Vec2 previous, bool focus)>
Parameters
eventThe mouse event for this movement
previousThe previous position of the mouse
focusWhether the listener currently has focus

◆ WheelListener

This type represents a listener for the mouse wheel in the Mouse 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 the wheel mouse, not any other buttons or mouse movement. Listeners are guaranteed to be called at the start of an animation frame, before the method Application#update(float).

While mouse 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 Mouse device.

The function type is equivalent to

 std::function<void(const MouseWheelEvent& event, bool focus)>
Parameters
eventThe mouse event for this wheel motion
focusWhether the listener currently has focus

Member Enumeration Documentation

◆ PointerAwareness

This enum is used to represent how sensative this device is to movement.

Movement events can be extremely prolific, especially if they do not require a button press. This enum is used limit how often these events received. By default, a mouse position is only recorded on a mouse press or release.

Enumerator
BUTTON 

Mouse position is only recorded on a press or a release

DRAG 

Mouse position is only recorded while dragging

ALWAYS 

Mouse position is always recorded

Constructor & Destructor Documentation

◆ Mouse()

cugl::Mouse::Mouse ( )
inlineprotected

Creates and initializes a new mouse device.

The mouse device will ignore all movement events until the method setPointerAwareness(PointerAwareness) is called.

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

◆ ~Mouse()

virtual cugl::Mouse::~Mouse ( )
inlineprotectedvirtual

Deletes this input device, disposing of all resources

Member Function Documentation

◆ addDragListener()

bool cugl::Mouse::addDragListener ( Uint32  key,
MotionListener  listener 
)

Adds a mouse release listener for the given object key

There can only be one drag 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 mouse is moved while any button is held dowh. This method will fail and return false if the pointer awareness is not DRAG or ALWAYS.

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

◆ addMotionListener()

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

Adds a mouse 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 mouse is moved (with or without any button held down). This method will fail and return false if the pointer awareness is not ALWAYS.

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

◆ addPressListener()

bool cugl::Mouse::addPressListener ( Uint32  key,
ButtonListener  listener 
)

Adds a mouse press listener for the given object key

There can only be one press 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 mouse button is pressed.

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

◆ addReleaseListener()

bool cugl::Mouse::addReleaseListener ( Uint32  key,
ButtonListener  listener 
)

Adds a mouse release listener for the given object key

There can only be one release 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 mouse button is released.

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

◆ addWheelListener()

bool cugl::Mouse::addWheelListener ( Uint32  key,
WheelListener  listener 
)

Adds a mouse wheel listener for the given object key

There can only be one wheel 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 mouse wheel moves

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

◆ buttonDown()

ButtonState cugl::Mouse::buttonDown ( ) const
inline

Returns the collection of buttons currently held down

Returns
the collection of buttons currently held down

◆ buttonPressed()

ButtonState cugl::Mouse::buttonPressed ( ) const
inline

Returns the collection of buttons pressed this animation frame

Returns
the collection of buttons pressed this animation frame

◆ buttonReleased()

ButtonState cugl::Mouse::buttonReleased ( ) const
inline

Returns the collection of buttons released this animation frame

Returns
the collection of buttons released this animation frame

◆ buttonUp()

ButtonState cugl::Mouse::buttonUp ( ) const
inline

Returns the collection of buttons not currently held down

Returns
the collection of buttons not currently held down

◆ clearState()

virtual void cugl::Mouse::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::Mouse::dispose ( )
overrideprotectedvirtual

Unintializes this device, returning it to its default state

An uninitialized device may not work without reinitialization.

Reimplemented from cugl::InputDevice.

◆ getDragListener()

const MotionListener cugl::Mouse::getDragListener ( Uint32  key) const

Returns the mouse drag listener for the given object key

This listener is invoked when the mouse is moved while any button is held dowh.

If there is no listener for the given key, it returns nullptr. Just because there is a listener does not mean it is active. This listener is only active is the pointer awareness is DRAG or ALWAYS.

Parameters
keyThe identifier for the listener
Returns
the mouse drag listener for the given object key

◆ getMotionListener()

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

Returns the mouse motion listener for the given object key

This listener is invoked when the mouse is moved (with or without any button held down).

If there is no listener for the given key, it returns nullptr. Just because there is a listener does not mean it is active. This listener is only active is the pointer awareness is ALWAYS.

Parameters
keyThe identifier for the listener
Returns
the mouse motion listener for the given object key

◆ getPointerAwareness()

PointerAwareness cugl::Mouse::getPointerAwareness ( ) const
inline

Returns the current pointer awareness of this device

Movement events can be extremely prolific, especially if they do not require a button press. This enum is used limit how often these events received. By default, a mouse position is only recorded on a mouse press or release.

Returns
the current pointer awareness of this device

◆ getPressListener()

const ButtonListener cugl::Mouse::getPressListener ( Uint32  key) const

Returns the mouse press listener for the given object key

This listener is invoked when a mouse button is pressed.

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

Parameters
keyThe identifier for the listener
Returns
the mouse press listener for the given object key

◆ getReleaseListener()

const ButtonListener cugl::Mouse::getReleaseListener ( Uint32  key) const

Returns the mouse release listener for the given object key

This listener is invoked when a mouse button is released.

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

Parameters
keyThe identifier for the listener
Returns
the mouse release listener for the given object key

◆ getWheelListener()

const WheelListener cugl::Mouse::getWheelListener ( Uint32  key) const

Returns the mouse wheel listener for the given object key

This listener is invoked when the mouse wheel moves

Parameters
keyThe identifier for the listener
Returns
the mouse wheel listener for the given object key

◆ init()

bool cugl::Mouse::init ( )
inlineprotected

Initializes this device, acquiring any necessary resources

Returns
true if initialization was successful

◆ isListener()

bool cugl::Mouse::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 five actions: button press, button release, mouse drag, mouse motion, or wheel motion.

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

◆ pointerOffset()

Vec2 cugl::Mouse::pointerOffset ( ) const
inline

Returns the directional amount the mouse moved this animation frame

This will be (0,0) if the mouse did not move

Returns
the directional amount the mouse moved this animation frame

◆ pointerPosition()

Vec2 cugl::Mouse::pointerPosition ( ) const
inline

Returns the current position of the mouse this animation frame

Returns
the current position of the mouse this animation frame

◆ queryEvents()

virtual void cugl::Mouse::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.

◆ removeDragListener()

bool cugl::Mouse::removeDragListener ( Uint32  key)

Removes the mouse drag listener for the given object key

If there is no active listener for the given key, this method fails and returns false. This method will succeed if there is a drag listener for the given key, even if the pointer awareness if BUTTON.

This listener is invoked when the mouse is moved while any button is held dowh.

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

◆ removeMotionListener()

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

Removes the mouse motion listener for the given object key

If there is no active listener for the given key, this method fails and returns false. This method will succeed if there is a motion listener for the given key, even if the pointer awareness if BUTTON or DRAG.

This listener is invoked when the mouse is moved (with or without any button held down).

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

◆ removePressListener()

bool cugl::Mouse::removePressListener ( Uint32  key)

Removes the mouse press 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 mouse button is pressed.

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

◆ removeReleaseListener()

bool cugl::Mouse::removeReleaseListener ( Uint32  key)

Removes the mouse release 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 mouse button is released.

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

◆ removeWheelListener()

bool cugl::Mouse::removeWheelListener ( Uint32  key)

Removes the mouse wheel 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 mouse wheel moves

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

◆ requestFocus()

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

◆ setPointerAwareness()

void cugl::Mouse::setPointerAwareness ( PointerAwareness  awareness)
inline

Sets the current pointer awareness of this device

Movement events can be extremely prolific, especially if they do not require a button press. This enum is used limit how often these events received. By default, a mouse position is only recorded on a mouse press or release.

If this value is changed from a permission value (e.g. ALWAYS) to a more restrictive one (e.g. BUTTON), then any associated listeners will be deactivated. However, the listeners will not be deleted.

Parameters
awarenessThe pointer awareness for this device

◆ updateState()

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

◆ wheelDirection()

Vec2 cugl::Mouse::wheelDirection ( ) const
inline

Returns the amount the mouse wheel moved this animation frame.

This will be (0,0) if the mouse wheel did not move

Returns
the amount the mouse wheel moved this animation frame.

Member Data Documentation

◆ _awareness

PointerAwareness cugl::Mouse::_awareness
protected

The current awareness for pointer movement

◆ _currPoint

Vec2 cugl::Mouse::_currPoint
protected

The mouse position for the current animation frame

◆ _currState

ButtonState cugl::Mouse::_currState
protected

The mouse buttons held down the current animation frame

◆ _dragListeners

std::unordered_map<Uint32, MotionListener> cugl::Mouse::_dragListeners
protected

The set of listeners called whenever a mouse is dragged

◆ _lastPoint

Vec2 cugl::Mouse::_lastPoint
protected

The mouse position for the previous animation frame

◆ _lastState

ButtonState cugl::Mouse::_lastState
protected

The mouse buttons held down the previous animation frame

◆ _moveListeners

std::unordered_map<Uint32, MotionListener> cugl::Mouse::_moveListeners
protected

The set of listeners called whenever a mouse is moved

◆ _pressListeners

std::unordered_map<Uint32, ButtonListener> cugl::Mouse::_pressListeners
protected

The set of listeners called whenever a mouse is pressed

◆ _releaseListeners

std::unordered_map<Uint32, ButtonListener> cugl::Mouse::_releaseListeners
protected

The set of listeners called whenever a mouse is released

◆ _wheelListeners

std::unordered_map<Uint32, WheelListener> cugl::Mouse::_wheelListeners
protected

The set of listeners called whenever a mouse wheel is moved

◆ _wheelOffset

Vec2 cugl::Mouse::_wheelOffset
protected

The amount of wheel movement this animation frame


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