Skip to content

Intro to textboxes

Textboxes are gooey's implementation of a simple text box to input text. This can be useful to get player input for a character name, or username and password, a specific value for a setting, etc.

Textboxes and gooey 2025.4

Textboxes were a bit revamped in gooey 2025.4. Some methods might not be available prior to that release.

Constructor

The constructor for textboxes is UITextBox and its signature is the following:

UITextBox(_id, _x, _y, _width, _height, _sprite, _max_chars=999999999, _relative_to=UI_DEFAULT_ANCHOR_POINT)
  • id is the string ID.
  • x and y are the offsets with respect to the anchor point. Note that, as directed in the Fundamentals page, your sprites should have its origin point set to top left, to allow for correct positioning in gooey.
  • width and height are the desired width and height of the textbox. Starting from gooey 2025.4, the behavior of height will change based on whether the "adjust height" property is set.
  • sprite is the sprite used to render the textbox.
  • max_chars is an optional value where we can set a limit on the number of characters allowed.
  • relative_to is the anchor point, as usual from the UI_RELATIVE_TO enum.

Features

The current implementation supports basic writing, character class restrictions (i.e. only numbers allowed), maximum character limitations and basic cursor control.

Features not supported

The following features are currently not supported:

  • Text selection
  • Copy/paste
  • Multiple lines

Height consideration

You can choose whether to "force" a height (on by default), like the one specified in the constructor, or you can tell gooey to automatically adjust the textbox size by using setAdjustHeight.

Additionally, you can turn on text wrapping by using setMultiline.

Allowing characters

You can configure which character classes to allow for the text input:

Character class Description Method
Uppercase letters A-Z setAllowUppercaseLetters
Lowercase letters a-z setAllowLowercaseLetters
Numbers 0-9 setAllowDigits
Spaces ΝΆ setAllowSpaces
Symbols everything else setAllowSymbols

Additionally, you can select exactly which symbols are allowed by using setSymbolsAllowed.

Setting a mask

If your field will be a password field, you might want to mask the characters input. You can do this by enabling setMaskText. Additionally you can choose the masking character (by default, *) with setMaskChar.

Adding a placeholder text

You can add a placeholder text (that will not be a part of the value) by using setPlaceholderText.

Example

Let's create a simple form where a user must choose a username, a password and type a small bio about theirselves. Let's use a Grid to help us layout the text and the textboxes.

1
2
3
4
var _panel = new UIPanel("TestPanel", 0, 0, 600, 300, yellow_panel, UI_RELATIVE_TO.MIDDLE_CENTER);
var _grid = new UIGrid("Grid", 3, 2);
_grid.setMargins(20).setSpacingHorizontal(20);
_panel.add(_grid);

We will limit it to 15 characters and we will allow only digits, letters and underscores. As every character is enabled by default, we just disable what we don't want:

5
6
7
var _txtbox = new UITextBox("Username_TextBox", 0, 0, 150, 100, grey_button05, 15, UI_RELATIVE_TO.MIDDLE_CENTER);
_txtbox.setTextFormat("[c_black]").setAdjustHeight(true).setSymbolsAllowed("_").setAllowSpaces(false).setInheritWidth(true);
_grid.addToCell(_txtbox, 0, 1);

The password one will have its masking set to true, and will allow all characters (20 at the most):

 9
10
11
var _txtbox = new UITextBox("Password_TextBox", 0, 0, 150, 100, grey_button05, 20, UI_RELATIVE_TO.MIDDLE_CENTER);
_txtbox.setTextFormat("[c_black]").setAdjustHeight(true).setMaskText(true).setInheritWidth(true);
_grid.addToCell(_txtbox, 1, 1);

Finally, for the bio one, we want to wrap text and have no limit on the text length, and we will add a placeholder text to inform the user what we expect:

12
13
14
var _txtbox = new UITextBox("Bio_TextBox", 0, 0, 150, 80, grey_button05, -1, UI_RELATIVE_TO.MIDDLE_CENTER);
_txtbox.setTextFormat("[c_black]").setMultiline(true).setPlaceholderText("Tell us about yourself!").setInheritWidth(true);
_grid.addToCell(_txtbox, 2, 1);

The resulting interactive example (after adding text labels to each field, at their left) looks like this:

GameMaker bug

As of the time of this writing, there is a bug in GameMaker's handling of keyboard_string in GX.Games, resulting in incorrect behavior of UITextBox. Follow on the issue status here.