GUI Tutorial Series

[Abion47]

Hello, End of the World

Alright, now that we have ourselves a working terminal, it's time for us to make it actually do something.

Table of Contents
The Basics

• Lesson Zero - Setting Up Your Terminal
  
• Hello, End of the World - Labels and Label Data >You Are Here<
  
• 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
  
• 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)
  

Tutorial Requirements

For this tutorial, you will need the following:

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

Tutorial Source Files

Initial File
Completed File

The Tutorial Itself

Assuming our terminal is properly configured (which it should be if you just got here after completing the last tutorial), you won't need the Level Editor at all for this one. Go ahead and stow it to the side for now.

Alright, we've got ourselves a shiny new terminal, but what do we do with it? Well, as anyone who's ever taken a programming course before will know, the first thing to do is "Hello World". So what we want to do now is to make some text appear on our screen. There are a few ways to go about this, but the simplest way is to use a Label. To use a Label, we use the function ImGui_DoLabel, which comes from the helper file "helper_imgui.hps" (it should be included at the top of your script file by default, but sometimes it doesn't hurt to double-check).

Open up your script file (assuming it isn't open already), and scroll to the OnGui function of our terminal. Inside the curly braces, type the following code:

Code: (Select All)

ImGui_DoLabel("Hello, Apocalypse!");

What this code does is it tells the terminal's Immediate GUI handler (or ImGui for short) to render a Label with the text "Hello, Apocalypse!". A Label is the simplest form of writing text, as it just spits out whatever you want it to say, no questions asked.

And that's it! Save your script, then load your map into the game using the dev launcher. If all is well, you should see something similar to the following images.




Aw, isn't that just adorable? But hey, at least the terminal is showing something. That's a lot more than it was doing five minutes ago. Still, it would be a bit more impressive if we could get that text somewhere less... disappointing.

Let's go back to our script and make a quick adjustment. Change the previous line of code to say this:

Code: (Select All)

ImGui_DoLabel("Hello, Apocalypse!", cVector3f(220, 260, 0));

This should look mostly familiar, but now instead of giving our function one parameter, we've given it two. That second parameter, a cVector3f, tells ImGui to put our text at a particular position on the terminal screen, which in this case is at the point [460, 394], which for this terminal puts it to the left and a bit up from center of the screen. When we don't specify this position, ImGui defaults to putting our stuff at the point [0, 0], which is at the screen's very top-left.

Save your code, and reload your map in the game.



We are starting to get somewhere, but that text is still way too small. We're going to have to get that text to grow a little bigger somehow.

Let's revisit our code again. What we need is a way to change the size of our text. To do that, we're going to need to use a special type called cImGuiLabelData. We're also going to have to change up how we are drawing our Label a bit.

Code: (Select All)

cImGuiLabelData labelData;
labelData.mFont.mvSize = cVector2f(100, 100);

ImGui_DoLabelExt("Hello, Apocalypse!", labelData, cVector3f(220, 260, 0));

Well, that was a lot of new-ness real fast, wasn't it? Let's step through this code to see what each thing does.

First off is our new type, cImGuiLabelData, which we declare into the variable called "labelData". This type is what handles all the customizable properties we want to set with anything regarding a Label, including size, color, or even if we want to draw a background image behind the text.

The next line may look a bit confusing, but what's going on is that labelData has a field within it called mFont that holds all the properties regarding specifically the Label's text. In this case, we are assigning a new size to mFont's mvSize field, specifying that we want some font that is appreciably larger than what we had before.

Finally, we are using a different way to get ImGui to draw us a Label, called ImGui_DoLabelExt. What the "Ext" part of that means is that, instead of ImGui to refer to its default values to the Label properties, we want to supply our own values instead. We do this by passing in our labelData as the second parameter, shifting the position vector over a bit.

Now that we got this code in, let's see what we got.



Now that's what I'm talking about!

We've got our text doing what we want it to do now, which is provide us some information in a way that doesn't make us go prematurely blind from all the squinting we would have to do. In the next tutorial, we're going to ramp it up a bit, tackling a few other widget types to get our terminal looking real spiffy.