Confused on how to handle (or why) SDL_StartTextInput()?

SDL Development
1

With SDL 1.2, we did the normal(?) way of SDL_EnableUNICODE(1) and then for each character, we received via keyEvent->keysym.unicode, we would add it to our input buffer to make the unicode string.

With SDL 2.0, both those have been removed, and it mentions to use the new text input API.
However, I am not clear the exact reason to use said new text input API, instead of using the old method (which would require a workaround since those are gone).

Let’s say the t key is used for communications.
When we detect that the t key is pressed, we would then start SDL_StartTextInput(), and then in event loop, we would keep getting SDL_TEXTINPUT events as the user types, but since they could be also hitting other hotkeys (like Function keys or tab or…), wouldn’t all this be in the unicode string as well, so we would need a way to filter non ASCII (or non readable) keys from that right?
Then if they want to edit said chat string, (hit backspace or use arrow keys) then we get SDL_TextEditingEvent events on those, is any of that filtered out as well?
Then finally, when in SDL_StartTextInput() mode, we wait for them to hit the enter key, and then do SDL_StopTextInput(), which would give us the final unicode string correct?

This brings up SDL_SetTextInputRect(), just how does this play into things? It says: “Use this function to set the rectangle used to type Unicode text inputs.”, is this supposed to be the buffer limit of the text, so, if we wanted 80 chars max, we would set this to 80? Or is this for something else?

I just don’t see the need for this for games, the old way handled unicode input just fine, never had any bug reports, so, just why should we use the new way with all the extra processing required for the new logic & event loops? We still need to advance the cursor in the game for every character they type, so I guess I am just missing something with the new text API.

Maybe someone can help clear the fog about this?

2

The old way of handling Unicode didn’t work well with any input system
that allows entering multiple characters at the same time (Asian input
systems are extremely guilty of this, saying this as somebody who has
Japanese input support installed on his system).

And yeah, I also still have no idea how SDL_SetTextInputRect is
supposed to work. I only know it influences where the candidate list
appears on screen (the candidate list is a list that shows different
texts that you can enter with the specified input, e.g. different
kanji for the same word, etc.).

3

If you just want American and Western European language support on desktop
systems, you can ignore those functions. They’re for more advanced
international input with IMEs and mobile devices.

Cheers!On Tue, Aug 13, 2013 at 11:18 PM, Sparks wrote:

**
With SDL 1.2, we did the normal(?) way of SDL_EnableUNICODE(1) and then
for each character, we received via keyEvent->keysym.unicode, we would add
it to our input buffer to make the unicode string.

With SDL 2.0, both those have been removed, and it mentions to use the new
text input API.
However, I am not clear the exact reason to use said new text input API,
instead of using the old method (which would require a workaround since
those are gone).

Let’s say the t key is used for communications.
When we detect that the t key is pressed, we would then start
SDL_StartTextInput(), and then in event loop, we would keep getting
SDL_TEXTINPUT events as the user types, but since they could be also
hitting other hotkeys (like Function keys or tab or…), wouldn’t all this
be in the unicode string as well, so we would need a way to filter non
ASCII (or non readable) keys from that right?
Then if they want to edit said chat string, (hit backspace or use arrow
keys) then we get SDL_TextEditingEvent events on those, is any of that
filtered out as well?
Then finally, when in SDL_StartTextInput() mode, we wait for them to hit
the enter key, and then do SDL_StopTextInput(), which would give us the
final unicode string correct?

This brings up SDL_SetTextInputRect(), just how does this play into
things? It says: “Use this function to set the rectangle used to type
Unicode text inputs.”, is this supposed to be the buffer limit of the text,
so, if we wanted 80 chars max, we would set this to 80? Or is this for
something else?

I just don’t see the need for this for games, the old way handled unicode
input just fine, never had any bug reports, so, just why should we use the
new way with all the extra processing required for the new logic & event
loops? We still need to advance the cursor in the game for every character
they type, so I guess I am just missing something with the new text API.

Maybe someone can help clear the fog about this?

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

4

With SDL 1.2, we did the normal(?) way of SDL_EnableUNICODE(1) and then for each character, we received via keyEvent->keysym.unicode, we would add it to our input buffer to make the unicode string.

With SDL 2.0, both those have been removed, and it mentions to use the new text input API.
However, I am not clear the exact reason to use said new text input API, instead of using the old method (which would require a workaround since those are gone).

Let’s say the t key is used for communications.
When we detect that the t key is pressed, we would then start SDL_StartTextInput(), and then in event loop, we would keep getting SDL_TEXTINPUT events as the user types, but since they could be also hitting other hotkeys (like Function keys or tab or…), wouldn’t all this be in the unicode string as well, so we would need a way to filter non ASCII (or non readable) keys from that right?
Then if they want to edit said chat string, (hit backspace or use arrow keys) then we get SDL_TextEditingEvent events on those, is any of that filtered out as well?

In a typical GUI application, the OS will be responsible for telling
you the candidate text (via SDL_TEXTEDITING), you can choose how (and
where) to show it in your UI.

Let’s say with an input method I typed “abc” and got unicode character
"X", the SDL application will first receive three SDL_TEXTEDITING
events with ‘a’, ‘ab’ and ‘abc’, then finally receive SDL_TEXTINPUT
event with unicode character ‘X’.

During this text compositing process, user can press any arbitrary
keys such as Function, backspace, both the SDL application and OS
input method will receive it and decide whether to deal with these
keys or not. For instance when user press backspace, most input
methods will delete the last candidate character typed and SDL app
will receive a new SDL_TEXTEDITING event (let’s say user typed a, b,
backspace, c, then the application will receive 4 events containing
’a’, ‘ab’, ‘a’, ‘ac’ each).

Then finally, when in SDL_StartTextInput() mode, we wait for them to hit the enter key, and then do SDL_StopTextInput(), which would give us the final unicode string correct?

You can wait until the enter key or other events (ESC or mouse click?)
defined by your application.

This brings up SDL_SetTextInputRect(), just how does this play into things? It says: “Use this function to set the rectangle used to type Unicode text inputs.”, is this supposed to be the buffer limit of the text, so, if we wanted 80 chars max, we would set this to 80? Or is this for something else?

SDL_SetTextInputRect() gives the OS a hint for where to show the
candidate text list, since the OS doesn’t know where you want to draw
the text you received via SDL_TEXTEDITING event.

  • JiangOn Wed, Aug 14, 2013 at 8:18 AM, Sparks wrote:
5

2013/8/14, Jiang Jiang :

SDL_SetTextInputRect() gives the OS a hint for where to show the
candidate text list, since the OS doesn’t know where you want to draw
the text you received via SDL_TEXTEDITING event.

The documentation isn’t even remotely clear about this though. Exactly
which area one should be expected to cover with that rectangle? I.e.
which coordinates one should specify.

6

Sorry that hasn’t been very clear. I should probably clarify this and
write a dedicated post.

You can take a look at this little demo and play with it (with your
system IME on):

http://hg.libsdl.org/SDL/file/783d1cff9b20/test/testime.c

The rectangle is supposed to be the rectangle that covered the “marked
text” you received from SDL_TEXTEDITING.

Certain programs might choose to show a text field at the bottom of
the application, then the marked text will be drawn in this text field
at the bottom. But it’s really up to you to decide. (For instance
games like Quake can pull down a console screen for users to type
text, then the marked text will be drawn somewhere in this console
screen.)

  • JiangOn Wed, Aug 14, 2013 at 10:21 AM, Sik the hedgehog <sik.the.hedgehog at gmail.com> wrote:

2013/8/14, Jiang Jiang <@Jiang_Jiang>:

SDL_SetTextInputRect() gives the OS a hint for where to show the
candidate text list, since the OS doesn’t know where you want to draw
the text you received via SDL_TEXTEDITING event.

The documentation isn’t even remotely clear about this though. Exactly
which area one should be expected to cover with that rectangle? I.e.
which coordinates one should specify.

7

In a typical GUI application, the OS will be responsible for telling
you the candidate text (via SDL_TEXTEDITING), you can choose how (and
where) to show it in your UI.

[]

I found this explanation so good I added it to the Wiki
under SDL_TextInputEvent. Hope you don’t mind!
[With a credit]On 14/08/2013, at 6:14 PM, Jiang Jiang wrote:

–
john skaller
@john_skaller
http://felix-lang.org

8

Jiang Jiang wrote:

In a typical GUI application, the OS will be responsible for telling
you the candidate text (via SDL_TEXTEDITING), you can choose how (and
where) to show it in your UI.

Let’s say with an input method I typed “abc” and got unicode character
"X", the SDL application will first receive three SDL_TEXTEDITING
events with ‘a’, ‘ab’ and ‘abc’, then finally receive SDL_TEXTINPUT
event with unicode character ‘X’.

This seems wrong.
Starting SDL_StartTextInput(), what happens is:
“a” is enterned.
SDL_TEXTINPUT event fired, and we see "a"
NO SDL_TEXTEDITING event fired.
“b” is entered.
SDL_TEXTINPUT event fired, and we see "b"
NO SDL_TEXTEDITING event fired.
…same for "c"
Now, I enter in ""
SDL_TEXTEDITING event fired, but no text in event.edit.text

Code:

  •   edit	{type=770 timestamp=423318 windowID=1 ...}	SDL_TextEditingEvent
  type	770	unsigned int
  timestamp	423318	unsigned int
  windowID	1	unsigned int

  •   text	0x0037f794 ""	char[32]
  start	0	int
  length	0	int

SDL_TEXTINPUT fired, that does have the “abc” string.
That isn’t how Jiang described would happen.

During this text compositing process, user can press any arbitrary
keys such as Function, backspace, both the SDL application and OS
input method will receive it and decide whether to deal with these
keys or not. For instance when user press backspace, most input
methods will delete the last candidate character typed and SDL app
will receive a new SDL_TEXTEDITING event (let’s say user typed a, b,
backspace, c, then the application will receive 4 events containing
’a’, ‘ab’, ‘a’, ‘ac’ each).

Nope, it doesn’t do that.
“a"is entered fires SDL_TEXTINPUT event, string has"a”
“b” is entered fires SDL_TEXTINPUT event, string has "ab"
backspace is hit, fires SDL_TEXTEDITING event:

Code:

  •   edit	{type=770 timestamp=152924 windowID=1 ...}	SDL_TextEditingEvent
  type	770	unsigned int
  timestamp	152924	unsigned int
  windowID	1	unsigned int

  •   text	0x0038f84c ""	char[32]
  start	0	int
  length	0	int

string has “abc”

So, I am still confused on how all this is supposed to work.
SDL_TEXTEDITING doesn’t seem to be working at all as described here.

1 Like
9

Which OS and Input method are you using?On 27/02/15 19:37, Sparks wrote:

SDL_TEXTINPUT fired, that does have the “abc” string.
That isn’t how Jiang described would happen.

10

Alex Baines wrote:> On 27/02/15 19:37, Sparks wrote:

SDL_TEXTINPUT fired, that does have the “abc” string.
That isn’t how Jiang described would happen.

Which OS and Input method are you using?

Windows 7.
What do you mean what input method?
I just enable SDL_StartTextInput(), SDL_Init(SDL_INIT_VIDEO | SDL_INIT_TIMER)…then sit in a loop looking for events.

11

By input method I mean how you are entering the special character that
is causing the issue.

Since you’re using Windows 7 I probably can’t be of much help though,
I’m only familiar with SDL’s Linux text input code.On 27/02/15 20:32, Sparks wrote:

Windows 7.
What do you mean what input method?
I just enable SDL_StartTextInput(), SDL_Init(SDL_INIT_VIDEO | SDL_INIT_TIMER)…then sit in a loop looking for events.

12

Alex Baines wrote:> On 27/02/15 20:32, Sparks wrote:

Windows 7.
What do you mean what input method?
I just enable SDL_StartTextInput(), SDL_Init(SDL_INIT_VIDEO | SDL_INIT_TIMER)…then sit in a loop looking for events.

By input method I mean how you are entering the special character that
is causing the issue.

Since you’re using Windows 7 I probably can’t be of much help though,
I’m only familiar with SDL’s Linux text input code.

It isn’t just that 1 unicode character that is causing the issue, it is the whole description of the process that is flawed.
Getting SDL_TEXTINPUT instead of SDL_TEXTEDITING events, and then those SDL_TEXTEDITING being worthless (no text, start & length being 0).
I enter unicode via the alt-keypad method, but, I don’t think this matters much, since, this isn’t the main issue here.

13

It isn’t just that 1 unicode character that is causing the issue, it is the whole description of the process that is flawed.
Getting SDL_TEXTINPUT instead of SDL_TEXTEDITING events, and then those SDL_TEXTEDITING being worthless (no text, start & length being 0).
I enter unicode via the alt-keypad method, but, I don’t think this matters much, since, this isn’t the main issue here.

if you’re using an input method that composes multiple keystrokes into
characters - or does some operation to them before they are committed.

These are mostly used for input of Asian languages which have many more
characters than keyboard keys, and require pressing a key sequence to
enter a specific character.

If you’re not using anything like that, then you should get one
SDL_TEXTINPUT event per key, each of which should usually contain just a
single character. You have to stitch the characters together yourself.

I don’t know how the ALT+Code stuff is handled by SDL or if it uses
SDL_TEXTEDITING or not, and I don’t know why you’re getting a single
SDL_TEXTINPUT event with 4 characters in it.On 27/02/15 20:55, Sparks wrote:

From my understanding, you’ll only get meaningful SDL_TEXTEDITING events

14

Alex Baines wrote:> On 27/02/15 20:55, Sparks wrote:

It isn’t just that 1 unicode character that is causing the issue, it is the whole description of the process that is flawed.
Getting SDL_TEXTINPUT instead of SDL_TEXTEDITING events, and then those SDL_TEXTEDITING being worthless (no text, start & length being 0).
I enter unicode via the alt-keypad method, but, I don’t think this matters much, since, this isn’t the main issue here.

From my understanding, you’ll only get meaningful SDL_TEXTEDITING events
if you’re using an input method that composes multiple keystrokes into
characters - or does some operation to them before they are committed.

These are mostly used for input of Asian languages which have many more
characters than keyboard keys, and require pressing a key sequence to
enter a specific character.

If you’re not using anything like that, then you should get one
SDL_TEXTINPUT event per key, each of which should usually contain just a
single character. You have to stitch the characters together yourself.

OK, so, you agree that Jiang’s reply of getting SDL_TEXTEDITING events for everything is just wrong, and that is ONLY useful for certain languages in some undescribed way. Forum post: http://forums.libsdl.org/viewtopic.php?p=38620#38620

SDL_TEXTEDITING gets fired always on windows(?) even when SDL_StartTextInput() is not called (see forum post http://forums.libsdl.org/viewtopic.php?t=11060), and still doesn’t contain any useful information.

SDL_TEXTINPUT is the one one that should always fire when a person types any key, and should also contain utf8 encoded translation of that key if needed, but, it does not handle hitting backspace to delete the last character as was described in that post.

That means, that people handling SDL_TEXTINPUT must write their own routine, and check if it is a multibyte sequence or not if a user presses backspace, and want to delete the last character(s).

How is it possible to test exactly when SDL_TEXTEDITING contains actually useful information for something, since, AFAIK, SDL_TEXTINPUT will always contain the correct character be it “normal” or multibyte.

I have yet to see any full example of how SDL_TEXTEDITING can be used for anything.
The wiki page for this is https://wiki.libsdl.org/SDL_TextEditingEvent and it shows it is in dire need of more explanation when & how to handle this event.

15

OK, so, you agree that Jiang’s reply of getting SDL_TEXTEDITING events for everything is just wrong, and that is ONLY useful for certain languages in some undescribed way. Forum post: http://forums.libsdl.org/viewtopic.php?p=38620#38620

I think Jian’s post assumes that you are using an IME, but most people
aren’t, which is why it might be misleading.

SDL_TEXTEDITING gets fired always on windows(?) even when SDL_StartTextInput() is not called (see forum post http://forums.libsdl.org/viewtopic.php?t=11060), and still doesn’t contain any useful information.

I’m not sure why that would be the case. If the event has 0 length and
you’re not using IME stuff, then I think it can be safely ignored.

SDL_TEXTINPUT is the one one that should always fire when a person types any key, and should also contain utf8 encoded translation of that key if needed, but, it does not handle hitting backspace to delete the last character as was described in that post.
That means, that people handling SDL_TEXTINPUT must write their own routine, and check if it is a multibyte sequence or not if a user presses backspace, and want to delete the last character(s).

Yes, I’ve had to do exactly that in my applications.

How is it possible to test exactly when SDL_TEXTEDITING contains actually useful information for something, since, AFAIK, SDL_TEXTINPUT will always contain the correct character be it “normal” or multibyte.

In the Linux code, the length parameter of SDL_TEXTEDITING events can be
used to see if it contains text. If it’s non-zero then you can display
the text in some way which shows it’s in the process of being composed
(Most non-SDL programs seem to underline this kind of text.)

I have yet to see any full example of how SDL_TEXTEDITING can be used for anything.
The wiki page for this is https://wiki.libsdl.org/SDL_TextEditingEvent and it shows it is in dire need of more explanation when & how to handle this event.

Yes, the wiki page could definitely use some work. It does link to
https://wiki.libsdl.org/Tutorials/TextInput though, which has a
reasonable explanation of the system.

Basically, you should only need to look at SDL_TEXTEDITING events if you
want to render the currently-being-editing text used in IMEs.

There’s a hint “SDL_IME_INTERNAL_EDITING” also, which allows you to just
ignore the EDITING events entirely and let the OS do the rendering of
this type of text if an IME is in use (It will just give you a TEXTINPUT
when the user finishes composing). But I think it’s only implemented for
the Linux code.On 27/02/15 21:54, Sparks wrote:

16

I’m sorry that I can’ write English well, the sentences I write may be less polite and not clear? Sorry :frowning:

My case is the same as what Sparks said,I don’t think Jian’s post is right.
And there are some other issues:
Status Window , Composition Window and Candidates Window both disappear ,
I can’t use the IME at all.
However, I find that there is a possible way to solve it: (Thanks for ancientcc )
http://www.freeors.com/bbs/forum.php?mod=viewthread&tid=22189&extra=page%3D1%26filter%3Dtypeid%26typeid%3D40[/url]

there is the translation of the article above ^
(I am not sure it is a accurate translation. Sorry [Embarassed]

I can’t see the Status Window:
Fix: make WM_IME_NOTIFY return SDL_FALSE default
I can’t see the Composition Window:
Fix: make WM_IME_STARTCOMPOSITION return SDL_FALSEe
It only shows one char in the Composition Window:
Fix: make WM_IME_COMPOSITION return SDL_FALSE when GCS_COMPSTR
What’s more, in SDL 2.0.3,if IMN_CLOSECANDIDATE are not SDL_TURE , it is no way to type some chinese char by some IME. (for example,the character “?” can’t type by WBJJ inputting method)

I haven’t tried the fix above.