#include <CUTextInput.h>

Inheritance diagram for cugl::TextInput:

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 (TextInputValidator validator)

const TextInputValidator	getValidator () const

bool	isListener (Uint32 key) const

const TextInputListener	getListener (Uint32 key) const

bool	addListener (Uint32 key, TextInputListener listener)

bool	removeListener (Uint32 key)

Public Member Functions inherited from cugl::InputDevice
Uint32	currentFocus () const

void	releaseFocus ()

Protected Member Functions
	TextInput ()

virtual	~TextInput ()

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

virtual bool	init ()

Protected Attributes
std::string	_buffer

bool	_active

bool	_updated

TextInputValidator	_validator

std::unordered_map< Uint32, TextInputListener >	_listeners

Protected Attributes inherited from cugl::InputDevice
Uint32	_focus

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

Constructor & Destructor Documentation

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.

virtual cugl::TextInput::~TextInput ( )

inlineprotectedvirtual

Deletes this input device, disposing of all resources

Member Function Documentation

bool cugl::TextInput::addListener	(	Uint32	key,
		TextInputListener	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.

Parameters

key	The identifier for the listener

Returns: true if the listener was succesfully added

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.

virtual void cugl::TextInput::clearState ( )

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.

bool cugl::TextInput::didUpdate ( ) const

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.

Returns: true if the buffer updated this animation frame

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.

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.

const std::string& cugl::TextInput::getBuffer ( ) const

inline

Returns the current input buffer of this text input device

This buffer is cleared whenever begin() is called.

Returns: the current input buffer of this text input device

const TextInputListener 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.

Parameters

key	The identifier for the listener

Returns: the text input listener for the given object key

const TextInputValidator cugl::TextInput::getValidator ( ) const

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.

Returns: the current validator for this input device.

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.

bool cugl::TextInput::isListener ( Uint32 key ) const

Returns true if key represents a listener object

Parameters

key	The identifier for the listener

Returns: true if key represents a listener object

virtual void cugl::TextInput::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

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.

Parameters

key	The identifier for the listener

Returns: true if the listener was succesfully removed

virtual bool cugl::TextInput::requestFocus ( Uint32 key )

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

Parameters

key	The identifier for the focus object

Returns: false if key does not refer to an active listener

Reimplemented from cugl::InputDevice.

void cugl::TextInput::setValidator ( TextInputValidator 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.

Parameters

validator The text validator for this input device

virtual bool cugl::TextInput::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

event	The input event to process
stamp	The event timestamp in CUGL time

Returns: false if the input indicates that the application should quit.

Implements cugl::InputDevice.

void cugl::TextInput::validate	(	const std::string &	value,
		const Timestamp &	stamp
	)

protected

Validates the value and appends it to the buffer if appropriate

This method calls on the active TextInputValidator to test the value before appending it. If there is no validator, the data is appended automatically.

Parameters

value The text to validate

Member Data Documentation

bool cugl::TextInput::_active

protected

Whether the input device is actively receiving text input

std::string cugl::TextInput::_buffer

protected

The input buffer for this device

std::unordered_map<Uint32, TextInputListener> cugl::TextInput::_listeners

protected

The set of listeners called whenever we append to the input buffer

bool cugl::TextInput::_updated

protected

Whether we have appended data to the buffer this animation frame

TextInputValidator cugl::TextInput::_validator

protected

The validator to check that text is acceptable before appending it

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

input/CUTextInput.h

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation