CUGL 2.3
Cornell University Game Library
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
cugl::TextInput Class Reference

#include <CUTextInput.h>

Inheritance diagram for cugl::TextInput:
cugl::InputDevice

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
 
virtual bool requestFocus (Uint32 key)
 
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)
 
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

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
 

Detailed Description

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.

Member Typedef Documentation

◆ EditListener

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)>
Parameters
eventThe input event for this append to the buffer
focusWhether the listener currently has focus

◆ InputListener

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)>
Parameters
eventThe input event for this append to the buffer
focusWhether the listener currently has focus

Constructor & Destructor Documentation

◆ TextInput()

cugl::TextInput::TextInput ( )
protected

Creates and initializes a new text input device.

WARNING: Never allocate a text input device directly. Always use the Input#activate() method instead.

◆ ~TextInput()

virtual cugl::TextInput::~TextInput ( )
inlineprotectedvirtual

Deletes this input device, disposing of all resources

Member Function Documentation

◆ addEditListener()

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.

Parameters
keyThe identifier for the edit listener
listenerThe listener to add
Returns
true if the listener was succesfully added

◆ addInputListener()

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.

Parameters
keyThe identifier for the input listener
listenerThe listener to add
Returns
true if the listener was succesfully added

◆ begin()

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.

◆ clearState()

virtual void cugl::TextInput::clearState ( )
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.

◆ dispose()

virtual void cugl::TextInput::dispose ( )
overrideprotectedvirtual

Unintializes this device, returning it to its default state

An uninitialized device may not work without reinitialization.

Reimplemented from cugl::InputDevice.

◆ end()

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

◆ getEditListener()

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.

Parameters
keyThe identifier for the listener
Returns
the text editing listener for the given object key

◆ getInputListener()

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.

Parameters
keyThe identifier for the listener
Returns
the text input listener for the given object key

◆ init()

bool cugl::TextInput::init ( )
inlineprotected

Initializes this device, acquiring any necessary resources

Returns
true if initialization was successful

◆ isActive()

bool cugl::TextInput::isActive ( ) const
inline

Returns true if this device is actively receiving input.

This method will return true after begin() is called, but before end() is called.

Returns
true if this device is actively receiving input.

◆ isListener()

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.

Parameters
keyThe identifier for the listener
Returns
true if key represents a listener object

◆ queryEvents()

virtual void cugl::TextInput::queryEvents ( std::vector< Uint32 > &  eventset)
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.

Parameters
eventsetThe set to store the event types.

Implements cugl::InputDevice.

◆ removeEditListener()

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.

Parameters
keyThe identifier for the listener
Returns
true if the listener was succesfully removed

◆ removeInputListener()

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.

Parameters
keyThe identifier for the listener
Returns
true if the listener was succesfully removed

◆ requestFocus()

virtual bool cugl::TextInput::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::TextInput::updateState ( const SDL_Event &  event,
const Timestamp stamp 
)
overridevirtual

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

◆ _active

bool cugl::TextInput::_active
protected

Whether the input device is actively receiving text input

◆ _editListeners

std::unordered_map<Uint32, EditListener> cugl::TextInput::_editListeners
protected

The set of edit listeners called for intermediate keystrokes

◆ _inputListeners

std::unordered_map<Uint32, InputListener> cugl::TextInput::_inputListeners
protected

The set of input listeners called whenever we resolve a character


The documentation for this class was generated from the following file: