cugl::Keyboard Class Reference

#include <CUKeyboard.h>

Inheritance diagram for cugl::Keyboard:

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

Public Member Functions
bool	keyDown (KeyCode code) const
bool	keyPressed (KeyCode code) const
bool	keyReleased (KeyCode code)
unsigned int	keyCount () const
const std::vector< KeyCode >	keySet () const
virtual bool	requestFocus (Uint32 key) override
bool	isListener (Uint32 key) const
const Listener	getKeyDownListener (Uint32 key) const
const Listener	getKeyUpListener (Uint32 key) const
bool	addKeyDownListener (Uint32 key, Listener listener)
bool	addKeyUpListener (Uint32 key, Listener listener)
bool	removeKeyDownListener (Uint32 key)
bool	removeKeyUpListener (Uint32 key)
Public Member Functions inherited from cugl::InputDevice
Uint32	acquireKey ()
Uint32	currentFocus () const
void	releaseFocus ()

Static Public Member Functions
static KeyCategory	keyCategory (KeyCode code)

Protected Member Functions
	Keyboard ()
virtual	~Keyboard ()
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_set< KeyCode, KeyCodeHasher >	_previous
std::unordered_set< KeyCode, KeyCodeHasher >	_current
std::unordered_map< Uint32, Listener >	_downListeners
std::unordered_map< Uint32, Listener >	_upListeners
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 keyboard.

This device is used when you want low-level monitoring of the keys, like traditional WASD control. It is not appropriate for mobile devices, which must use virtual keyboards. If you want to get text from the user, you should not use this device. Use TextInput instead.

As with most devices, we provide support for both listeners and polling the keyboard. Polling the keyboard will query the key state at the start of the frame, but it may miss those case in which a user presses and releases a key in a single animation frame.

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.

Member Typedef Documentation

Listener

cugl::Keyboard::Listener

This type represents a listener for the Keyboard 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.

A Keyboard is designed to send input to a focused object (e.g. a text field or other UI widget). While only one listener can have focus at a time, all listeners will receive input from the Keyboard.

Listeners are guaranteed to be called at the start of an animation frame, before the method Application#update(float).

The function type is equivalent to

 std::function<void(const KeyEvent& event, bool focus)>

Parameters

code	The code for this key
stamp	The timestamp for this event
focus	Whether the listener currently has focus

Constructor & Destructor Documentation

Keyboard()

cugl::Keyboard::Keyboard ( )

inlineprotected

Creates and initializes a new keyboard device.

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

~Keyboard()

virtual cugl::Keyboard::~Keyboard ( )

inlineprotectedvirtual

Deletes this input device, disposing of all resources

Member Function Documentation

addKeyDownListener()

bool cugl::Keyboard::addKeyDownListener	(	Uint32	key,
		Listener	listener
	)

Adds a key down listener for the given object key

There can only be one key down 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 key is pressed.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns

true if the listener was succesfully added

addKeyUpListener()

bool cugl::Keyboard::addKeyUpListener	(	Uint32	key,
		Listener	listener
	)

Adds a key up listener for the given object key

There can only be one key up 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 key is released.

Parameters

key	The identifier for the listener
listener	The listener to add

Returns

true if the listener was succesfully added

clearState()

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

overrideprotectedvirtual

Unintializes this device, returning it to its default state

An uninitialized device may not work without reinitialization.

Reimplemented from cugl::InputDevice.

getKeyDownListener()

const Listener cugl::Keyboard::getKeyDownListener

(

Uint32

key

)

const

Returns the key down listener for the given object key

This listener is invoked when a key is pressed.

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

Parameters

key	The identifier for the listener

Returns

the key down listener for the given object key

getKeyUpListener()

const Listener cugl::Keyboard::getKeyUpListener

(

Uint32

key

)

const

Returns the key up listener for the given object key

This listener is invoked when a key is released.

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

Parameters

key	The identifier for the listener

Returns

the key up listener for the given object key

init()

bool cugl::Keyboard::init ( )

inlineprotected

Initializes this device, acquiring any necessary resources

Returns

true if initialization was successful

isListener()

bool cugl::Keyboard::isListener

(

Uint32

key

)

const

Returns true if key represents a listener object

An object is a listener if it is either a key down or a key up listener.

Parameters

key	The identifier for the listener

Returns

true if key represents a listener object

keyCategory()

static KeyCategory cugl::Keyboard::keyCategory ( KeyCode  code )

static

Returns the category of the given key code

See KeyCategory for information on categories.

Parameters

code	The key code to check

Returns

the category of the given key code

keyCount()

unsigned int cugl::Keyboard::keyCount ( ) const

inline

Returns the number of keys currently held down.

Returns

the number of keys currently held down.

keyDown()

bool cugl::Keyboard::keyDown ( KeyCode  code ) const

inline

Returns true if the key is currently held down.

Parameters

code	the keyboard key to test

Returns

true if the key is currently held down.

keyPressed()

bool cugl::Keyboard::keyPressed ( KeyCode  code ) const

inline

Returns true if the key was pressed this animation frame.

A key press occurs if the key is down this animation frame, but was not down the previous animation frame.

Parameters

code	the keyboard key to test

Returns

true if the key is currently held down.

keyReleased()

bool cugl::Keyboard::keyReleased ( KeyCode  code )

inline

Returns true if the key was released this animation frame.

A key release occurs if the key is up this animation frame, but was not up the previous animation frame.

Parameters

code	the keyboard key to test

Returns

true if the key is currently held down.

keySet()

const std::vector<KeyCode> cugl::Keyboard::keySet

(

)

const

Returns a list of the keys currently held down.

This list contains the codes for all of the keys currently held down. This list is a copy; modifying it has not effect on the poller.

Returns

a list of the keys currently held down.

queryEvents()

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

removeKeyDownListener()

bool cugl::Keyboard::removeKeyDownListener

(

Uint32

key

)

Removes the key down 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 key is pressed.

Parameters

key	The identifier for the listener

Returns

true if the listener was succesfully removed

removeKeyUpListener()

bool cugl::Keyboard::removeKeyUpListener

(

Uint32

key

)

Removes the key up 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 key is released.

Parameters

key	The identifier for the listener

Returns

true if the listener was succesfully removed

requestFocus()

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

key	The identifier for the focus object

Returns

false if key does not refer to an active listener

Reimplemented from cugl::InputDevice.

updateState()

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

Member Data Documentation

_current

std::unordered_set<KeyCode,KeyCodeHasher> cugl::Keyboard::_current

protected

The keys pressed in the current animation frame

_downListeners

std::unordered_map<Uint32, Listener> cugl::Keyboard::_downListeners

protected

The set of listeners called whenever a key is pressed

_previous

std::unordered_set<KeyCode,KeyCodeHasher> cugl::Keyboard::_previous

protected

The keys pressed in the previous animation frame

_upListeners

std::unordered_map<Uint32, Listener> cugl::Keyboard::_upListeners

protected

The set of listeners called whenever a key is released

---

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

• include/cugl/input/CUKeyboard.h