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

#include <CUKeyboard.h>

Inheritance diagram for cugl::Keyboard:
cugl::InputDevice

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< KeyCodekeySet () 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

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
codeThe code for this key
stampThe timestamp for this event
focusWhether 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
keyThe identifier for the listener
listenerThe 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
keyThe identifier for the listener
listenerThe 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
keyThe 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
keyThe 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
keyThe 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
codeThe 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
codethe 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
codethe 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
codethe 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
eventsetThe 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
keyThe 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
keyThe 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
keyThe 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
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.

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: