Using SDL2-C# to Capture Text Input

A common feature of applications and video games is to allow the player to input text for various reasons. Maybe we want to allow the player to input their character’s name in an RPG, name a city in SimCity, or type a chat message to a friend in online. Using SDL2, we can take advantage of its built-in text processing system which abstracts much of the operating system event handles and character encoding mechanisms.

On consoles such as Xbox and Playstation, text input is rather simplistic and limited to visual keypads that you select via the controller. On a PC, we have the full range of widely varying keyboards from English and Spanish to Russian and Japanese. If we want our game or application to attract users on an international scale, it’s probably in your best interest to learn here and now how to use SDL2 to accomplish this goal.

At first glance, it probably seems simple to process text input. If the user presses the ‘A’ key on the keyboard, the OS will send an event that the keyboard was just pressed, the key was ‘A’, and no modifier keys were pressed (CAPS, SHIFT, CTRL, ALT, etc…). That’s it, right? Unfortunately, there are a ton of languages on this planet, and some of them have thousands of characters in them. People who type in those languages most certainly do not have thousand-letter keyboards or entire walls of their houses dedicated as a giant keyboard. This basically means that some characters will require multiple key presses just to process. Fortunately, SDL2 handles all of this for us and simply sends us a byte array with the results.

Among SDL2’s event processing, the structure we are interested in is SDL_TextInputEvent. This event is sent through the SDL2 event processing chain whenever text is input. I have personally seen this trigger from both physical keyboards and the Windows virtual on-screen keyboard. I am sure that there are other ways to trigger this event as well. Using this event, we can get the character information that was input by the user. Here are the fields of the C-style structure that we can use:

UInt32     type          The type of the event
UInt32     timestamp     The time that the event occurred
UInt32     windowID      The ID of the window that has focus, if any
char       text          The null-terminated, UTF-8 encoded input text

After determining that this is an SDL_TextInputEvent by checking the type field, we are most interested in the text field. That field is a pointer to a character array which is encoded using the UTF-8 scheme. In my most recent cases, I was using a C# wrapper around the SDL2 library named SDL2-CS. Because C# runs in a managed, garbage collected runtime, it’s a bit tricky to get the text input from C into C# through the .NET marshaller, but here’s how to do it.

// the character array from the C-struct is of length 32
// char types are 8-bit in C, but 16-bit in C#, so we use a byte (8-bit) here
byte[] rawBytes = new byte[SDL2.SDL.SDL_TEXTINPUTEVENT_TEXT_SIZE];

// we have a pointer to an unmanaged character array from the SDL2 lib (event.text.text),
// so we need to explicitly marshal into our byte array
unsafe { Marshal.Copy((IntPtr)event.text.text, rawBytes, 0, SDL2.SDL.SDL_TEXTINPUTEVENT_TEXT_SIZE); }

// the character array is null terminated, so we need to find that terminator
int indexOfNullTerminator = Array.IndexOf(rawBytes, (byte)0);

// finally, since the character array is UTF-8 encoded, get the UTF-8 string
string text = System.Text.Encoding.UTF8.GetString(rawBytes, 0, length);

The above code is only necessary because we are in a C# / .NET environment where we need to handle unmanaged to managed allocations with care. If you are sticking to C, then your job will be much easier in that you only need to receive the text input event and retrieve the associated encoded text.

A few closing notes:

  • The event SDL_KeyboardEvent is not useful for capturing text input, but is useful for capturing text editing input such as backspace and enter. This event will not encode the entered characters for you and will instead simply say, “such and such key was pressed or released.”
  • Further investigation is needed on how to interact with advanced text input such as from an Input Method Editor. A separate SDL_TextEditingEvent can be used to assist with this, but I have not had time to experiment yet.
  • The SDL2-CS library offers a comfortable path for Java/C# developers who want to slowly  be introduced to what SDL2 offers. Over time you can dip into source and pickup the C syntax of various things.
  • Check out my SharpDL library which you can create an XNA-like project from (with SDL2 underneath).