GUI Tutorial Series

[Abion47]

A Regular Grab Bag

What we've seen so far is enough to make a good amount of types of terminals, but there may be occasions in which you want to provide the player a bit more control. Perhaps you want to create a puzzle entirely on a terminal? Or maybe you want to layout text with a bit more pizzazz? In either case or others, this tutorial will introduce you to four more controls: the CheckBox, the ToggleButton, the RepeatButton, and the Slider.

Table of Contents
The Basics

• Lesson Zero - Setting Up Your Terminal
  
• Hello, End of the World - Labels and Label Data
  
• Your Friendly Infomercial - TextFrames and Images
  
• Mind Your Language - Lang Files
  
• Who's Got The Button - Buttons and Interactivity
  

Getting More Advanced

• Get To The Back Of The Line - Background Graphics and Z-Order
  
• The Well Oiled Machine - ImGui State Variables
  
• A Regular Grab Bag - Scroll Bars, Check Boxes, and Alternate Button Types >You Are Here<
  
• She Goes In And Out, And In, And Out... - Interfacing With Other Entities
  
• Grouping and Layout (WIP)
  

Using SOMA's Built-In GUI Styles

• StationGui (WIP)
  
• UrbanGui (WIP)
  
• Playing Audio (WIP)
  

Going Beyond Terminals

• Setting Up a User Module (WIP)
  
• Basic Heads-Up Display (WIP)
  
• Target Info Module (WIP)
  
• Player HUD Menu System (WIP)
  

Tutorial Requirements

For this tutorial, you will need the following:

• A map with a prepared terminal, plus all the necessities. Enable the terminal for interaction.
  
• A script file with a prepared OnGui terminal callback function.
  

Tutorial Source Files

Completed File

The Tutorial Itself

Alright, we have four controls to go through, so we are going to just go ahead and dive in.

The first control I'm going to cover is the CheckBox. For those of you who may not know, a CheckBox is a graphical widget that is just a box with one of two states: checked and unchecked. Clicking on the box will make a check mark appear, and will change the state to checked. Likewise, clicking on the box again will remove the check mark and make the state unchanged. They are useful for cases when you want a value to be toggled between true and false, such as an option that controls whether lights are on or off.

Using a CheckBox widget in code is pretty similar to using a Button. First, though, we need to add a variable to store the state of the CheckBox. When we used a variable before with the Buttons, we just created a temporary variable to store whether the Button was pressed. That was sufficient for a Button, since all we needed to know was pressed on that particular run of the OnGui function. However, with a CheckBox, the value needs to be stored in a variable that doesn't get reset once the run is completed. There are a couple ways to do this, but since we just learned how to use ImGui state variables, why not go ahead and use that?

To start out, let's put an ImGui_IsFirstRun section into the OnGui function to initialize the variables we are going to use.

Code: (Select All)

if (ImGui_IsFirstRun())
{
    ImGui_SetStateBool("CheckBox_IsChecked", false);
}

Now that we have our variable initialized, let's move on to what the code for a CheckBox looks like:

Code: (Select All)

cImGuiCheckBoxData checkBoxData;
checkBoxData.mFont.mvSize = cVector2f(40,40);
checkBoxData.mColorBase = cColor_White;
checkBoxData.mFont.SetFile("sansation_large_bold.fnt");
checkBoxData.mvBoxSize = cVector2f(25,25);
checkBoxData.mGfxBox = cImGuiGfx("imgui_checkbox.tga");
checkBoxData.mvCheckOverlaySize = cVector2f(25,25);
checkBoxData.mGfxCheckOverlay = cImGuiGfx("imgui_checkbox_check.tga");

bool checkBoxResult = ImGui_DoCheckBoxExt(
    "check_box",
    "This is a CheckBox",
    ImGui_GetStateBool("CheckBox_IsChecked", false),
    checkBoxData,
    cVector3f(100, 40, 0),
    cVector2f(350, 95));

ImGui_SetStateBool("CheckBox_IsChecked", checkBoxResult);

Some of the options in the cImGuiCheckBoxData should look familiar from the cImGuiButtonData. The new ones are as follows:

• mvBoxSize - Sets the size of the box.
  
• mGfxBox - Sets the graphic that will represent the box. (The file used above is the default SOMA image for the box.)
  
• mvCheckOverlaySize - Sets the size of the check mark.
  
• mGfxCheckOverlay - Sets the graphic that will represent the check mark. (The file used above is the default SOMA image for the check mark.)
  

Next, we use the function ImGui_DoCheckBoxExt to actually create the CheckBox. The parameters should look familiar, as for the most part they are identical to most of the widget functions we have looked at so far. The only new parameter is where we have ImGui_GetStateBool retrieving the value of our state variable. This parameter is what tells ImGui what the actual current state of the CheckBox is in, so it can render or not render the check mark accordingly.

Like the Button function, this function returns a value that reflects whether the state was changed (from checked to unchecked or vice versa), so that is the value we will need to capture and store in order to remember that state outside of this OnGui run. All we do here is capture the value in a temporary variable and then store that value into our state variable.

Running this code will give you something looking like this:



Next up, we have the ToggleButton. Functionally, the ToggleButton is identical to the CheckBox in that rather than clicking it like a normal Button, it reverts between two states whenever it is clicked, in this case between "pressed" and "released". Because it works with states, we will need to create a state variable for it as well. Add the following line of code to the ImGui_IsFirstRun block:

Code: (Select All)

ImGui_SetStateBool("ToggleButton_IsChecked", false);

Next, let's take a look at the ToggleButton's code:

Code: (Select All)

cImGuiButtonData buttonData;
buttonData.mFont.mvSize = cVector2f(40,40);
buttonData.mColorBase = cColor(0.35, 0.35, 0.35);
buttonData.mbUseTriggeredColor = true;
buttonData.mColorTriggered = cColor(0.1, 0.1, 0.1);
buttonData.mFont.SetFile("sansation_large_bold.fnt");

bool toggleButtonResult = ImGui_DoToggleButtonExt(
    "toggle_button",
    "This is a ToggleButton",
    ImGui_GetStateBool("ToggleButton_IsChecked", false),
    buttonData,
    cVector3f(100, 240, 0),
    cVector2f(380, 95));
    
ImGui_SetStateBool("ToggleButton_IsChecked", toggleButtonResult);

As you can see, the ToggleButton uses the same cImGuiButtonData as regular buttons do, and the ImGui_DoToggleButtonExt function parameters are exactly the same as the function for the CheckBox. There isn't much of anything new to explain here, but I will say that when using ToggleButtons, using the TriggeredColor values in the Button data is a must, as otherwise there would be no visible difference between when the Button is pressed and when it is released.

Running this code turns out like this:



The second and last alternate Button type that we will be covering in this tutorial is the RepeatButton. The RepeatButton isn't actually all that different than a regular Button - it uses the same cImGuiButtonData, the appearance is the same, the parameters are the same, and it returns the same bool value that shows whether it had been clicked. The difference, however, is that where the normal Button will only return true on the particular OnGui run that it was clicked, the RepeatButton will return true for as long as the mouse Button is held down.

Normal Button Behavior:


Repeat Button Behavior:


For the sake of completion, here is the code for doing a RepeatButton:

Code: (Select All)

ImGui_DoRepeatButtonExt(
    "repeat_button",
    "This is a RepeatButton",
    buttonData,
    cVector3f(100, 440, 0),
    cVector2f(380, 95));

(We don't need to create new Button data for the RepeatButton, since we can use the same data that we used for the ToggleButton.)