 |
CUGL 2.1
Cornell University Game Library
|
|
CUGL 2.1
Cornell University Game Library
|
#include <CUTextInput.h>
Public Types | |
| typedef std::function< void(const TextInputEvent &event, bool focus)> | InputListener |
| typedef std::function< void(const TextEditEvent &event, bool focus)> | EditListener |
Public Member Functions | |
| void | begin () |
| void | end () |
| bool | isActive () const |
| virtual bool | requestFocus (Uint32 key) override |
| bool | isListener (Uint32 key) const |
| const InputListener | getInputListener (Uint32 key) const |
| const EditListener | getEditListener (Uint32 key) const |
| bool | addInputListener (Uint32 key, InputListener listener) |
| bool | addEditListener (Uint32 key, EditListener listener) |
| bool | removeInputListener (Uint32 key) |
| bool | removeEditListener (Uint32 key) |
| virtual void | clearState () override |
| virtual bool | updateState (const SDL_Event &event, const Timestamp &stamp) override |
| virtual void | queryEvents (std::vector< Uint32 > &eventset) override |
 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 |
| Protected Member Functions inherited from cugl::InputDevice | |
| InputDevice () | |
| virtual | ~InputDevice () |
| bool | initWithName (const std::string name) |
Protected Attributes | |
| bool | _active |
| std::unordered_map< Uint32, InputListener > | _inputListeners |
| std::unordered_map< Uint32, EditListener > | _editListeners |
| 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 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 begin(). All input is sent via a TextInputEvent to the appropriate listeners as soon as the input resolves. Unlike SDL, we guarantee that input is sent one unicode character at a time, in the order that the unicode is processed.
Like SDL it is also possible to attach listeners to the editing process. Some characters may involve typing multiple keystrokes before the input resolves. This includes extended Latin characters like ü, or Chinese characters created by Pinyin - Simplified on macOS. This is in case you would like to give the user visual feedback on the intermediate editing process.
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 an editing 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.
While a TextInput is primarily designed to send Unicode characters, some characters are the result of multiple keystrokes. This includes extended Latin characters like ü, or characters created by Pinyin - Simplified on macOS. Editing listeners intercept these intermediate keystrokes before the input resolved as a unicode character.
Unlike text input, editing input 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 edit listeners will be invoked by the TextInput.
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 TextEditEvent& event, bool focus)>
| event | The input event for this append to the buffer |
| focus | Whether the listener currently has focus |
This type represents an input 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.
This listener is called whenever a unicode character resolves as input. 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 input listeners will be invoked by the TextInput.
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 |
|
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::addEditListener | ( | Uint32 | key, |
| EditListener | listener | ||
| ) |
Adds a text editing listener for the given object key
There can only be one edit 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 the text input has received keystrokes starting a unicode character, but the character has not yet resolved.
| key | The identifier for the edit listener |
| listener | The listener to add |
| bool cugl::TextInput::addInputListener | ( | Uint32 | key, |
| InputListener | listener | ||
| ) |
Adds a text input listener for the given object key
There can only be one input 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 input resolves to a unicode character.
| key | The identifier for the input 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 resolve (though the key strokes may still be detected by the device). Once the method is called, input will continue resolve until the method end() is called.
This device maintains no internal state. All input is communicated immediately to the listeners as soon as it resolves.
|
inlineoverridevirtual |
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.
| void cugl::TextInput::end | ( | ) |
Stop accepting text with this device
Once the method is called, no more input will resolve (though the key strokes may still be detected by the device).
| const EditListener cugl::TextInput::getEditListener | ( | Uint32 | key | ) | const |
Returns the text editing listener for the given object key
If there is no listener for the given key, it returns nullptr.
This listener is invoked when the text input has received keystrokes starting a unicode character, but the character has not yet resolved.
| key | The identifier for the listener |
| const InputListener cugl::TextInput::getInputListener | ( | 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.
This listener is invoked when input resolves to a unicode character.
| key | The identifier for the listener |
|
inlineprotected |
Initializes this device, acquiring any necessary resources
|
inline |
| bool cugl::TextInput::isListener | ( | Uint32 | key | ) | const |
Returns true if key represents a listener object
An object is a listener if it is a listener for either editing or input.
| key | The identifier for the listener |
|
overridevirtual |
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::removeEditListener | ( | Uint32 | key | ) |
Removes the text edit 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 the text input has received keystrokes starting a unicode character, but the character has not yet resolved.
| key | The identifier for the listener |
| bool cugl::TextInput::removeInputListener | ( | 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.
This listener is invoked when input resolves to a unicode character.
| 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.
|
overridevirtual |
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 |
Whether the input device is actively receiving text input
|
protected |
The set of edit listeners called for intermediate keystrokes
|
protected |
The set of input listeners called whenever we resolve a character
1.8.16