#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 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 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 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 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 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.

◆ 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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Listener

Constructor & Destructor Documentation

◆ Keyboard()

◆ ~Keyboard()

Member Function Documentation

◆ addKeyDownListener()

◆ addKeyUpListener()

◆ clearState()

◆ dispose()

◆ getKeyDownListener()

◆ getKeyUpListener()

◆ init()

◆ isListener()

◆ keyCategory()

◆ keyCount()

◆ keyDown()

◆ keyPressed()

◆ keyReleased()

◆ keySet()

◆ queryEvents()

◆ removeKeyDownListener()

◆ removeKeyUpListener()

◆ requestFocus()

◆ updateState()

Member Data Documentation

◆ _current

◆ _downListeners

◆ _previous

◆ _upListeners