cugl::Mouse Class Reference

#include <CUMouse.h>

Inheritance diagram for cugl::Mouse:

Public Types
enum	PointerAwareness { PointerAwareness::BUTTON, PointerAwareness::DRAG, PointerAwareness::ALWAYS }

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 MouseButtonListener	getPressListener (Uint32 key) const
const MouseButtonListener	getReleaseListener (Uint32 key) const
const MouseMotionListener	getDragListener (Uint32 key) const
const MouseMotionListener	getMotionListener (Uint32 key) const
const MouseWheelListener	getWheelListener (Uint32 key) const
bool	addPressListener (Uint32 key, MouseButtonListener listener)
bool	addReleaseListener (Uint32 key, MouseButtonListener listener)
bool	addDragListener (Uint32 key, MouseMotionListener listener)
bool	addMotionListener (Uint32 key, MouseMotionListener listener)
bool	addWheelListener (Uint32 key, MouseWheelListener 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	currentFocus () const
void	releaseFocus ()

Protected Member Functions
	Mouse ()
virtual	~Mouse ()
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 ()
virtual bool	init ()

Protected Attributes
PointerAwareness	_awareness
ButtonState	_lastState
ButtonState	_currState
Vec2	_lastPoint
Vec2	_currPoint
Vec2	_wheelOffset
std::unordered_map< Uint32, MouseButtonListener >	_pressListeners
std::unordered_map< Uint32, MouseButtonListener >	_releaseListeners
std::unordered_map< Uint32, MouseMotionListener >	_moveListeners
std::unordered_map< Uint32, MouseMotionListener >	_dragListeners
std::unordered_map< Uint32, MouseWheelListener >	_wheelListeners
Protected Attributes inherited from cugl::InputDevice
Uint32	_focus

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 Enumeration Documentation

enum cugl::Mouse::PointerAwareness

strong

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

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.

virtual cugl::Mouse::~Mouse ( )

inlineprotectedvirtual

Deletes this input device, disposing of all resources

Member Function Documentation

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

Adds a mouse release 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 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

key	The identifier for the listener
listener	The listener to add

Returns

true if the listener was succesfully added

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

Adds a mouse 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 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

key	The identifier for the listener
listener	The listener to add

Returns

true if the listener was succesfully added

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

Adds a mouse press 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 mouse button is pressed.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns

true if the listener was succesfully added

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

Adds a mouse release 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 mouse button is released.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns

true if the listener was succesfully added

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

Adds a mouse wheel 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 mouse wheel moves

Parameters

key	The identifier for the listener
listener	The listener to add

Returns

true if the listener was succesfully added

ButtonState cugl::Mouse::buttonDown ( ) const

inline

Returns the collection of buttons currently held down

Returns

the collection of buttons currently held down

ButtonState cugl::Mouse::buttonPressed ( ) const

inline

Returns the collection of buttons pressed this animation frame

Returns

the collection of buttons pressed this animation frame

ButtonState cugl::Mouse::buttonReleased ( ) const

inline

Returns the collection of buttons released this animation frame

Returns

the collection of buttons released this animation frame

ButtonState cugl::Mouse::buttonUp ( ) const

inline

Returns the collection of buttons not currently held down

Returns

the collection of buttons not currently held down

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.

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.

const MouseMotionListener 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

key	The identifier for the listener

Returns

the mouse drag listener for the given object key

const MouseMotionListener 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

key	The identifier for the listener

Returns

the mouse motion listener for the given object key

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

const MouseButtonListener 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

key	The identifier for the listener

Returns

the mouse press listener for the given object key

const MouseButtonListener 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

key	The identifier for the listener

Returns

the mouse release listener for the given object key

const MouseWheelListener 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

key	The identifier for the listener

Returns

the mouse wheel listener for the given object key

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

key	The identifier for the listener

Returns

true if key represents a listener object

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

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

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

eventset

The set to store the event types.

Implements cugl::InputDevice.

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

key	The identifier for the listener

Returns

true if the listener was succesfully removed

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

key	The identifier for the listener

Returns

true if the listener was succesfully removed

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

key	The identifier for the listener

Returns

true if the listener was succesfully removed

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

key	The identifier for the listener

Returns

true if the listener was succesfully removed

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

key	The identifier for the listener

Returns

true if the listener was succesfully removed

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

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

awareness

The pointer awareness for this device

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

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.

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

PointerAwareness cugl::Mouse::_awareness

protected

The current awareness for pointer movement

Vec2 cugl::Mouse::_currPoint

protected

The mouse position for the current animation frame

ButtonState cugl::Mouse::_currState

protected

The mouse buttons held down the current animation frame

std::unordered_map<Uint32, MouseMotionListener> cugl::Mouse::_dragListeners

protected

The set of listeners called whenever a mouse is dragged

Vec2 cugl::Mouse::_lastPoint

protected

The mouse position for the previous animation frame

ButtonState cugl::Mouse::_lastState

protected

The mouse buttons held down the previous animation frame

std::unordered_map<Uint32, MouseMotionListener> cugl::Mouse::_moveListeners

protected

The set of listeners called whenever a mouse is moved

std::unordered_map<Uint32, MouseButtonListener> cugl::Mouse::_pressListeners

protected

The set of listeners called whenever a mouse is pressed

std::unordered_map<Uint32, MouseButtonListener> cugl::Mouse::_releaseListeners

protected

The set of listeners called whenever a mouse is released

std::unordered_map<Uint32, MouseWheelListener> cugl::Mouse::_wheelListeners

protected

The set of listeners called whenever a mouse wheel is moved

Vec2 cugl::Mouse::_wheelOffset

protected

The amount of wheel movement this animation frame

---

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

• input/CUMouse.h