 |
CUGL 2.0
Cornell University Game Library
|
|
CUGL 2.0
Cornell University Game Library
|
#include <CUTextInput.h>
Public Types | |
| typedef std::function< void(const TextInputEvent &event, bool focus)> | Listener |
| typedef std::function< bool(const std::string &value)> | Validator |
Public Member Functions | |
| void | begin () |
| void | end () |
| bool | isActive () const |
| const std::string & | getBuffer () const |
| bool | didUpdate () const |
| virtual bool | requestFocus (Uint32 key) override |
| void | setValidator (Validator validator) |
| const Validator | getValidator () const |
| bool | isListener (Uint32 key) const |
| const Listener | getListener (Uint32 key) const |
| bool | addListener (Uint32 key, Listener listener) |
| bool | removeListener (Uint32 key) |
 Public Member Functions inherited from cugl::InputDevice | |
| Uint32 | acquireKey () |
| Uint32 | currentFocus () const |
| void | releaseFocus () |
Protected Member Functions | |
| TextInput () | |
| virtual | ~TextInput () |
| bool | init () |
| virtual void | dispose () override |
| void | validate (const std::string &value, const Timestamp &stamp) |
| 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::string | _buffer |
| bool | _active |
| bool | _updated |
| Validator | _validator |
| std::unordered_map< Uint32, Listener > | _listeners |
| 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 |
This class is a service that extracts UTF8 text from typing.
You never want to use a keyboard device to gather text. That is because complex unicode characters can correspond to several keystrokes. This device abstracts this process, to make it easier to gather text for password fields, text boxes, or the like.
This class is an object-oriented abstraction build on top of the SDL Text Input API. For a tutorial of this API see
https://wiki.libsdl.org/Tutorials/TextInput
While this class abstracts aways the SDL calls, the process remains the same. First you start a text input sequence with the method begin(). While the user types, it is stored into the buffer, which can be queried at any time. You can retrieve the buffer via polling, or via a listener that is called every time the input updates.
The buffer will continue to fill until either the method end() is called, At that point, no more text is received by this device. However, the buffer is still present and can be queried to get the final result. The buffer is not erased until the method begin() is called again.
Listeners are guaranteed to be called at the start of an animation frame, before the method Application#update(float) is called.
Unlike Keyboard, this class is fine to use with mobile devices. On many devices, calling the method begin() will create a virtual keyboard to input text.
This type represents a listener for the TextInput 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 TextInput 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 TextInput.
This listener is called whenever text is appends to the buffer. 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 TextInputEvent& event, bool focus)>
| event | The input event for this append to the buffer |
| focus | Whether the listener currently has focus |
This type represents a listener for validating text input. A validator checks whether intermediate input should be appended to the buffer. There may only be one validator at a time.
This function type is equivalent to
std::function<bool(const std::string& value)>
| value | The character or string to append to the buffer |
|
protected |
Creates and initializes a new text input device.
WARNING: Never allocate a text input device directly. Always use the Input#activate() method instead.
|
inlineprotectedvirtual |
Deletes this input device, disposing of all resources
| bool cugl::TextInput::addListener | ( | Uint32 | key, |
| Listener | listener | ||
| ) |
Adds a text input 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.
| key | The identifier for the listener |
| listener | The listener to add |
| void cugl::TextInput::begin | ( | ) |
Start accepting text with this device
Until this method is called, no input will ever be added to the buffer. Once the method is called, input will continue to be added to the buffer until the method end() is called.
Calling this method will clear any text that was previously in the buffer.
|
inlineoverrideprotectedvirtual |
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.
|
inline |
Returns true if the buffer updated this animation frame
This value resets every animation frame. It is useful if you are keeping track of input via polling instead of a listener.
|
overrideprotectedvirtual |
Unintializes this device, returning it to its default state
An uninitialized device may not work without reinitialization.
Reimplemented from cugl::InputDevice.
| void cugl::TextInput::end | ( | ) |
Stop accepting text with this device
Once the method is called, no more text will be added to the buffer. However, the buffer itself will remain so that the text can be read.
|
inline |
Returns the current input buffer of this text input device
This buffer is cleared whenever begin() is called.
| const Listener cugl::TextInput::getListener | ( | Uint32 | key | ) | const |
Returns the text input listener for the given object key
If there is no listener for the given key, it returns nullptr.
| key | The identifier for the listener |
|
inline |
Returns the current validator for this input device.
A validator checks whether intermediate input should be appended to the buffer. There may only be one validator at a time.
|
inlineprotected |
Initializes this device, acquiring any necessary resources
|
inline |
| bool cugl::TextInput::isListener | ( | Uint32 | key | ) | const |
Returns true if key represents a listener object
| key | The identifier for the listener |
|
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::TextInput::removeListener | ( | Uint32 | key | ) |
Removes the text input listener for the given object key
If there is no active listener for the given key, this method fails and returns false.
| key | The identifier for the listener |
|
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
| key | The identifier for the focus object |
Reimplemented from cugl::InputDevice.
| void cugl::TextInput::setValidator | ( | Validator | validator | ) |
Sets the current validator for this input device.
A validator checks whether intermediate input should be appended to the buffer. There may only be one validator at a time.
| validator | The text validator for this input device |
|
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 |
Validates the value and appends it to the buffer if appropriate
This method calls on the active Validator to test the value before appending it. If there is no validator, the data is appended automatically.
| value | The text to validate |
| stamp | The timestamp for validation |
|
protected |
Whether the input device is actively receiving text input
|
protected |
The input buffer for this device
|
protected |
The set of listeners called whenever we append to the input buffer
|
protected |
Whether we have appended data to the buffer this animation frame
|
protected |
The validator to check that text is acceptable before appending it
1.8.16