Using The Virtual Keyboard

In this tech blog we're going to give you an overview of a new and much requested feature that's been added to GameMaker Studio 2 - the ability to open the OS virtual keyboard on touchscreen devices. This feature is available for Android (including Amazon Fire, FireTV, and AndroidTV), iOS, and UWP targets, and permits you to call up (or hide) the virtual keyboard on each platform, using it to get text input from the user for your games, much like you would from a physical keyboard.

THE NEW FUNCTIONS AND ACTIONS

Accessing the new virtual keyboard features is done using either Drag and Drop™ or GML, and before showing you how to use the different functions and actions, we'll give you a quick overview of what they are. In GML we have the following functions:

keyboard_virtual_show(keyboard_type, return_key_type, autocapitalization_type, predictive_text_enabled);
keyboard_virtual_hide();
keyboard_virtual_height();
keyboard_virtual_status();

And for those DnD™ users we have these actions (from the Mouse and Keyboard section):

 - Show Virtual Keyboard

 - Hide Virtual Keyboard

 - Get Virtual Keyboard Height

 - If Virtual Keyboard Is Showing

Now you know what the new functions and actions are, let's look at using them in a project. There are many, many ways that the virtual keyboard can be used in your games, but in general the setup and use will be the same

• You call up the keyboard
• You get some user input
• You hide the keyboard again

So, let's go ahead and show you how to do just that!

BRINGING UP THE VIRTUAL KEYBOARD

For the sake of this tech blog, we're just going to go through the minimum steps required to have an instance get some input from the virtual keyboard. So, you'll need a new project open, and in that you'll need a room that is 480x800 in size (or whatever is appropriate for the target that you want to test on). You'll then need to create a new object, and call it something like objKVControl. In the Create Event of this object we want to initialise a variable to hold the string input, and we'll set the GUI size to the same size as the display (this is just to make drawing stuff simpler later):

kv_input_string = ""
display_set_gui_size(display_get_width(), display_get_height());

or this if you use DnD™:

Next we want to add a Global Tap event from the Gesture Events category:

In this event we want to toggle between showing and hiding the virtual keyboard on the device. For that we'll use the following GML:

if keyboard_virtual_status() == false
    {
    keyboard_string = "";
    keyboard_virtual_show(kbv_type_default, kbv_returnkey_default, kbv_autocapitalize_none, false);
    }
else
    {
    keyboard_virtual_hide();
    }

Alternatively in DnD™ you'd have something like this:

In this example, we first reset the built-in keyboard_string variable, as that'll be what we use to get the keyboard input, and then we bring up the virtual keyboard. We've simply used the default values for the virtual keyboard in the example, but you can set different keyboards to be used (EG: show only a numberpad instead of a full key-set) as well as the Return Key style and auto-capitalisation rules to follow. Note that not all of the options possible will be available across all devices, so you should take care to test them thoroughly on each platform that you want to publish to. For full details, please see the manual for each of the functions/actions.

If you want, you can run your project now on your test device and you should see that tapping the screen will bring up or hide the virtual keyboard.

SYSTEM ASYNC EVENT

Calling either the show or hide functions/actions will also trigger a System Asynchronous Event which will tell you the status of the keyboard. This event will populate the async_load DS map with the following key/value pairs:

• "event_type" - this will be "virtual keyboard status" when triggered by virtual keyboard actions.

• "screen_height" - the height of the virtual keyboard (in pixels). This will be 0 if the keyboard is invisible.

• "keyboard_status" - the current status of the keyboard, returned as one of the following strings:

  • "hiding"
  • "hidden"
  • "showing"
  • "visible"

Using the async event is not necessary when using the virtual keyboard and is provided more as an alternative or as an additional help when using the functions/actions.

GETTING INPUT

Once the virtual keyboard has been brought up it will accept input like a regular physical keyboard and GameMaker Studio 2 will process it as such. This means that you can use the regular keyboard functions/actions to check for input, and it also means that the different keyboard events will be triggered from the Virtual Keyboard. In this example, we'll simply get the input from the keyboard and store it in the variable we defined at the start of this article. We'll then display this on the screen.

To get the input from the virtual keyboard we need to add a Step Event with the following code:

if keyboard_virtual_status()
    {
    kv_input_string = keyboard_string;
    }

Or this DnD™:

Finally we'll add in a Draw GUI event where we'll draw the keyboard input to the screen. In this event we'll have the following GML:

draw_set_halign(fa_center);
var _height = keyboard_virtual_height();
var _dw = display_get_width();
var _dh = display_get_height();
draw_text(_dw / 2, _dh - _height - 32, "Input" + kv_input_string);

And the DnD™ would be:

SUMMARY

If you run the project now on your test device, you should see that tapping the screen alternates between showing and hiding the OS virtual keyboard and if you type on the keyboard then the "input" text should also be populated with the characters you have pressed... Which brings us to the end of this tech blog! As you have seen, setting up the OS virtual keyboard is easy, and once you have it open then dealing with input is almost exactly the same as using a regular keyboard on a Windows PC or Mac. However, it's worth noting that each platform has it's own caveats, so please check the manual before going any further, as all the differences between targets are listed there.