Intro to Checkboxes

Checkboxes are a widget that allows you to portray, and optionally modify, a boolean value. The widget is named "checkbox", but in reality visually it can be anything that toggles its state when clicked from one state to another. For example, it can be a toggle switch, an on/off button, etc.

Constructor

The constructor signature of UICheckbox is:

UICheckbox(_id, _x, _y, _text, _sprite_true, _sprite_false, _value=false, _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.
• text is a ScribbleDX string that represents the text that will be rendered next to the checkbox sprite.
• sprite_true is the sprite asset used to render the checkbox on its "on" or "true" state.
• sprite_false is the sprite asset used to render the checkbox on its "off" or "false" state.
• value is the starting value (true or false) for the checkbox.
• relative_to is the anchor point, as usual from the UI_RELATIVE_TO enum.

Configuring the appearance

There are three sprites you can configure: the "true", "false" and "base" sprites. This provides flexibility for depicting different kinds of checkboxes, for example:

• Set a separate sprite for the true and false states (with an optional "base" sprite). This is typically used for checkboxes that mimic toggles, levers, switches etc.
• Set a "base" sprite which functions as an "empty" sprite, and a true sprite. This is commonly used to display an empty square and then use the "true" sprite to display a checkmark, cross etc., akin to a paper checkbox

You can also play with the text itself - you can configure the text string and text format for "true" and "false" states.

Finally, you can configure the mouseover states as well.

Setting the value

Apart from setting the value of the checkbox to true/false using setValue, you can also toggle a checkbox on and off by using the toggle method.

Starting with gooey 2025.4, you can bind the value to a variable, as explained in the Binding and pre/post-render callbacks tutorial.

Examples

Let's set up a small Settings menu as an example. I used Crusenho's UI Essential pack for this one. Since the sprites are very small, I halved the GUI size with respect to the window size (which is 960x540 for all of the embedded examples):

var _w = display_get_gui_width();
var _h = display_get_gui_height();

display_set_gui_size(_w/2, _h/2);

After creating out panel, let's add checkboxes for four options on the settings menu: sounds, music, anti-alias and V-Sync. Let's set up the first two ones using different sprites. For the Sounds checkbox, let's use a "toggle" sprite (the asset pack includes two sprites, one for the "off" position, , and one for the "on" position, ), and for the Music one, let's just display the false state with a crossed box, , and the true state with a checkmark in the box, :

var _panel = new UIPanel("TestPanel", 0, 0, 200, 200, spr_Panel, UI_RELATIVE_TO.MIDDLE_CENTER);
_panel.setTitle("Options");

var _checkbox = new UICheckbox("Sounds_Checkbox", 30, 50, "Sounds", spr_Toggle_On, spr_Toggle_Off, self.sounds);
_panel.add(_checkbox);
var _checkbox = new UICheckbox("Music_Checkbox", 30, 85, "Music", spr_Check, spr_Cross, self.music);
_panel.add(_checkbox);

For the third checkbox I want to do something a bit different: keep the same sprite for true and false, and vary the text. Let's use the arrow sprite, , and then change the text string using setTextTrue and setTextFalse methods. I'm also using setTextOffset to slightly adjust the x position of the text, to better line it up with the rest:

var _checkbox = new UICheckbox("AA_Checkbox", 30, 120, "", spr_Arrow, spr_Arrow, self.aa);
_checkbox.setTextTrue("Anti-Alias [c_red][[on]").setTextFalse("Anti-Alias [c_lime][[off]");
_checkbox.setTextOffset({x: 7, y:0});
_panel.add(_checkbox);

Finally, the fourth checkbox will be a base square, , and then overlaid with a checkmark for the true state, :

var _checkbox = new UICheckbox("Vsync_Checkbox", 30, 155, "V-Sync", spr_Check_NoBox, undefined, self.vsync);
_checkbox.setSpriteBase(spr_Checkbox);
_panel.add(_checkbox);

The result looks like this (click the checkboxes, or the texts, to toggle them):