TextInputSession Class Reference

RAII handle representing a text input field that currently wants to receive typed characters. More...

#include <jngl/TextInputSession.hpp>

Public Member Functions
	TextInputSession (TextInputType type=TextInputType::Text)
	TextInputSession (const TextInputSession &)=delete
TextInputSession &	operator= (const TextInputSession &)=delete
	TextInputSession (TextInputSession &&) noexcept
TextInputSession &	operator= (TextInputSession &&) noexcept
std::string	take ()
	Returns the UTF-8 characters typed since the last call to take() and clears them.
void	setInputArea (Rect area, double cursor=0)
	Tells the OS/IME where on screen this field is, in JNGL Screen coordinates (i.e.

Friends
void	internal::feedTextInput (const std::string &)
void	internal::reapplyTextInputSession ()
void	internal::reapplyTextInputArea ()
void	internal::ensureLegacyTextInputStarted ()

Detailed Description

RAII handle representing a text input field that currently wants to receive typed characters.

Text input is a mode with a lifetime: while at least one TextInputSession is alive, the OS/IME is told to deliver typed characters (and, on Android and iOS, the on-screen keyboard is shown). Construct one when a field gains focus and destroy it (e.g. by resetting an std::optional<TextInputSession>) when it loses focus again.

Multiple instances can be alive at once, for example when a dialog with its own text field opens on top of a form. The most recently constructed instance is the one that receives typed characters; when it is destroyed, the instance that was active before it (if any) resumes receiving characters. This also covers focus moving directly from one field to another: it doesn't matter whether the newly focused field constructs its session before or after the previously focused field destroys its own.

Example:

class TextField {
public:
    void setFocus(bool focus) {
        if (focus) {
            session.emplace();
        } else {
            session.reset();
        }
    }
 
    void step() {
        if (session) {
            text += session->take();
        }
    }
 
private:
    std::string text;
    std::optional<jngl::TextInputSession> session;
};

Definition at line 71 of file TextInputSession.hpp.

Member Function Documentation

take()

std::string take

(

)

Returns the UTF-8 characters typed since the last call to take() and clears them.

Unlike the deprecated jngl::getTextInput(), characters accumulate across frames, so a frame in which take() isn't called (e.g. because a modal dialog is open, or the scene is paused) doesn't lose keystrokes. The internal buffer is capped, so an instance that's constructed but never read from can't grow unbounded.

setInputArea()

void setInputArea	(	Rect	area,
		double	cursor = 0 )

Tells the OS/IME where on screen this field is, in JNGL Screen coordinates (i.e.

(0, 0) is the center of the screen, same as jngl::getMousePos())

This is used to position the IME candidate window (e.g. for CJK input) directly below the field instead of e.g. the top left corner of the window. cursor is the horizontal offset of the caret within area, in the same coordinate system, and defaults to the start of the field.

Only has an effect while this is the active (i.e. most recently constructed, not yet destroyed) TextInputSession.

---

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

• jngl/TextInputSession.hpp