SDL2 and the text input mysteries

As far as I know, the SDL_TextInputEvent event is emitted when the user types a character and this character is delivered in a buffer in the event structure, in UTF-8 form. Why is this buffer 32 bytes long if it does not provide the entire text entered, but only one UTF-8 character? I tried to force SDL to emit an event with more characters, but the event always delivers only one character.

The second issue is that the documentation states that this event can contain a piece of text, in which case SDL will provide several events so that all the text is transferred. If each emitted event delivers only one character, how can the text not fit in the 32-byte buffer of the event structure? I can’t understand it.

Third, there are also SDL_TextEditingEvent events (and SDL_TextEditingExtEvent) that additionally provide the cursor position. No matter what I press on the keyboard, SDL never provides me with this event. I tried typing, pressing the arrow keys separately and in combination with the Ctrl and Shift keys, but I never received this event on the application side. So under what circumstances is this event emitted?

Just in case, I’m testing these events under Windows 10 and text input is active by default, so I’m receiving SDL_TextInputEvent events without any problems. I’m asking because I’d like to know how it all works. What I only need is to provide UTF-8 characters, because I will program the caret and selection myself (SDL doesn’t have to do it for me).

I haven’t dealt with emojis, but apparently they can get very long, here’s a quote from the source code:

 /* `text` is limited to SDL_TEXTINPUTEVENT_TEXT_SIZE bytes. If the incoming
 * string is larger than this, SDL will split it and send it in pieces, across
 * multiple events. The string is in UTF-8 format, and if split, SDL
 * guarantees that it will not split in the middle of a UTF-8 sequence, so any
 * event will only contain complete codepoints. However, if there are several
 * codepoints that go together into a single glyph (like an emoji "thumbs up"
 * followed by a skin color), they may be split between events.

Is it that normal typing of normal characters in any language produces one event per one UTF-8 character, and only in the case of stupid emotes, the text delivered in the event can be longer than one character, or even longer than the buffer?

I think that is a pretty fair summary.
The main goal would be to make text input work internationally.
Chinese or Japanese symbols may take multiple keystrokes to chain a single character together, so the textedit event will only fire when the entire sequence has been sent.

1 Like

That’s why I would like to use it so that I don’t have to implement the translation of keystokes into UTF-8 characters myself, but simply receive these characters. This is very convenient. So the issue of character capture is clear.

Now I would like to know under what circumstances SDL_TextEditingEvent events are emitted and how SDL handles cursor (or caret). So far I haven’t managed to generate a single such event.

I don’t have experience in using this, but the intermediary program is called an Input Method Editor (IME)

I think the TextEditing event is for your program to have a chance to show what keys have been added as the user builds their desired letter.
At least this seems to be the case on Linux.
Does anybody know if the TextEditing event fires for anything outside of usage with an IME?
(I do get the TextEditing event to fire when I gain or lose clicked focus of the window. I think this may be the result of my onscreen keyboard being activated?)

1 Like

Some platforms can send more text than 1 character when receiving input for some actions like pasting text, so internal function used to implement the keyboard SDL_SendKeyboardText accepts an unlimited number of characters. It also creates the SDL_TEXTINPUT event.

1 Like

Ok, more or less I understand this. But what about SDL_TextEditingEvent events?

These events only exist on a few platforms, it is triggered when part of the text is replaced by another text, e.g. when you select a text and type/paste another - the selected text will be replaced by a new one.

1 Like

It sounds like it applies to mobile platforms, and I’m not interested in those. :wink:

Ok, thank you very much guys for explanations. If anyone would like to add anything else to this topic, I’d love to hear about it. For now, I think I know everything I need to implement text input on desktop platforms. Again, thanks for help!

If fact SDL_TextEditingEvent can be sent by Linux, Windows and Cocoa (iOS/Mac?). But I really can’t see the point for it there :grin: . I guess to get it to work on the desktop, you’d need some sophisticated setup like ibus on Linux and IME on Windows.