![]() |
CUGL 2.3
Cornell University Game Library
|
#include <CUKeyboard.h>
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) |
![]() | |
Uint32 | acquireKey () |
Uint32 | currentFocus () const |
virtual bool | requestFocus (Uint32 key) |
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 |
![]() | |
InputDevice () | |
virtual | ~InputDevice () |
bool | initWithName (const std::string name) |
virtual void | dispose () |
virtual void | clearState ()=0 |
virtual bool | updateState (const SDL_Event &event, const Timestamp &stamp)=0 |
virtual void | queryEvents (std::vector< Uint32 > &eventset)=0 |
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 |
![]() | |
std::string | _name |
Uint32 | _focus |
Uint32 | _nextKey |
Friends | |
class | Input |
Additional Inherited Members | |
![]() | |
static const Uint32 | RESERVED_KEY = UINT32_MAX |
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.
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)>
code | The code for this key |
stamp | The timestamp for this event |
focus | Whether the listener currently has focus |
|
inlineprotected |
Creates and initializes a new keyboard device.
WARNING: Never allocate a keyboard device directly. Always use the Input#activate()
method instead.
|
inlineprotectedvirtual |
Deletes this input device, disposing of all resources
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.
key | The identifier for the listener |
listener | The listener to add |
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.
key | The identifier for the listener |
listener | The listener to add |
|
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.
|
overrideprotectedvirtual |
Unintializes this device, returning it to its default state
An uninitialized device may not work without reinitialization.
Reimplemented from cugl::InputDevice.
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.
key | The identifier for the listener |
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.
key | The identifier for the listener |
|
inlineprotected |
Initializes this device, acquiring any necessary resources
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.
key | The identifier for the listener |
|
static |
Returns the category of the given key code
See KeyCategory
for information on categories.
code | The key code to check |
|
inline |
Returns the number of keys currently held down.
|
inline |
Returns true if the key is currently held down.
code | the keyboard key to test |
|
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.
code | the keyboard key to test |
|
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.
code | the keyboard key to test |
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.
|
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.
eventset | The set to store the event types. |
Implements cugl::InputDevice.
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.
key | The identifier for the listener |
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.
key | The identifier for the listener |
|
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.
key | The identifier for the focus object |
Reimplemented from cugl::InputDevice.
|
overrideprotectedvirtual |
Processes an SDL_Event
The dispatcher guarantees that an input device only receives events that it subscribes to.
event | The input event to process |
stamp | The event timestamp in CUGL time |
Implements cugl::InputDevice.
|
protected |
The keys pressed in the current animation frame
|
protected |
The set of listeners called whenever a key is pressed
|
protected |
The keys pressed in the previous animation frame
|
protected |
The set of listeners called whenever a key is released