Getting Started Creating User Interfaces

This article will help you get started creating interfaces in SplashKit. In this one we'll see how to create and use basic elements, like buttons and sliders. In later the next ones, we'll move on to advanced layouting, and finally we'll see how we can style the interface to match our project. Written by Sean Boettger on April 29 2024

In this article we’ll see how to create user interfaces in SplashKit. This’ll let you add buttons, sliders, text boxes, and other elements to your games/programs. This is a great way to add interactivity, and also to visualise your variables!

Part 1: Basic element creation

Let’s see how we can create a simple button. We’ll start in an empty project, and focus on just showing the button. Then we’ll make it interactive.

1. Let’s begin by setting up our main function and opening up a window for us to place our interface elements on. See Drawing using Procedures if you aren’t familiar with this part. In this example code, we’ve:

   1. opened up a window
   2. cleared the screen white
   3. refreshed the screen so we can see what’s on it
   4. and finally delayed for 5 seconds (so the program doesn’t end immediately)

   Make sure to have a look at the code, and see where we’ll put our interface code!

   C++

   #include "splashkit.h"
   
   int main()
   {
       // open a window and clear it to white
       open_window("My Interface!", 800, 600);
       clear_screen(COLOR_WHITE);
   
       // ...we'll put our interface code here!...
   
       // refresh the screen, then wait 5 seconds
       refresh_screen();
       delay(5000);
   
       // program ends, and the window closes
       return 0;
   }

2. Now let’s show a button! This can be done with the Button function, which takes some text to show on the button, and also a position and size so it knows where to show up.

   For example in C++, button("My Button!", rectangle_from(300, 260, 200, 24)); will show a button in the middle of the screen, with the label “My Button!“.

3. We also need to draw the interface - we can do this with Draw Interface

   Making those changes, we get the following inside main:

   C++

       // open a window and clear it to white
       open_window("My Interface!", 800, 600);
       clear_screen(COLOR_WHITE);
   
       // show button
       button("My Button!", rectangle_from(300, 260, 200, 24));
   
       // draw the interface!
       draw_interface();
   
       // refresh the screen, then wait 5 seconds
       refresh_screen();
       delay(5000);

   Which if you run, will show you this!

   

   But you’ll notice that you can’t click the button yet! Don’t worry, to get this working we just need to make sure we process the user’s events (like clicks and keyboard presses).

   To do this, we need to add a loop - this will make our code run over and over again (rather than just waiting 5 seconds then exiting like it does now). Then inside that loop we’ll check for user input!

   1. Start by deleting the Delay (delay(5000)) line, since this was just so the window didn’t vanish immediately.

   2. Then we can add a while loop, that loops as long as the user hasn’t tried to close the window (using Quit Requested). This loop will need to enclose basically everything, from clearing the screen, down to refreshing it. That way we can keep updating the screen and drawing our button to it over and over!

   3. Then well add a statement inside the while loop at the top, to check for user input using Process Events. You may have also noticed a warning in the terminal about this:

   WARNING -> Interface function called before 'process_events' - make sure to call this first!

   SplashKit will try to give helpful messages when things aren’t quite right, so make sure to pay attention to them!

   Putting this all together, we get this inside main:

   C++

       // open a window
       open_window("My Interface!", 800, 600);
   
       while (!quit_requested())
       {
           process_events();
   
           clear_screen(COLOR_WHITE);
   
           button("My Button!", rectangle_from(300, 260, 200, 24));
   
           draw_interface();
   
           refresh_screen();
       }
   
       // program ends, and the window closes
       return 0;

   And we can now click the button!

   You’ll notice something interesting here - we put the call to Button inside the loop! This is because SplashKit uses what’s called an ‘immediate mode’ UI paradigm.

   This means that when we make a Button, or any other element, it does its job of ‘checking if its clicked’ once, and then stops existing. This means we need to keep calling Button every iteration of our loop, just like we call Process Events every iteration.

   This makes it really easy to make dynamic user interfaces, since you can change them every iteration! This might be different to other UI frameworks you have used or will use, so just make sure to keep this in mind.

   SplashKit Interfaces

   SplashKit uses an immediate mode GUI paradigm. This makes it easy to create dynamic interfaces!

   When using it, keep in mind that every UI element is ephemeral, and the interface is reset after calls to Draw Interface and Process Events - so make sure you create all elements inside the main loop, and between those two functions.

Part 2: Responding to events

Alright, now we can hover over and click the button! But it doesn’t do anything yet - how do we check if it’s been pressed? All the UI elements in SplashKit return their results. For instance, Button returns a boolean - true if it has been clicked, and false if not!

Retrieving results

SplashKit element functions return changes to them. Buttons return if they’ve been clicked or not, number sliders return their current value, and so on.

Let’s try it out:

1. We can put the call to Button inside an if statement.
2. Then, in the if statement’s body let’s just make it print some text to the terminal, using Write Line

We should also give the button some more descriptive text inside it, like “Write To Terminal!”

C++

        if (button("Write To Terminal!", rectangle_from(300, 260, 200, 24)))
        {
            write_line("The button was clicked!");
        }

Note how rather than creating the button, and then checking if it’s been clicked seperately, we’ve used a single call to Button, that both shows the button and returns whether its been clicked.

Now when we click on the button, our text gets printed in the terminal! You can of course put whatever code you want - for instance, the button could start your game, add an item to your stock program, or pop up extra info.

Part 3: More elements

Now let’s try out some more interesting elements - let’s add a text box, so we can customize the message written to the terminal!

1. First let’s start by adding a variable to store the user’s text in - make sure to do this outside the main loop, or else the user’s text will be forgotten each iteration!

   C++

       open_window("My Interface!", 800, 600);
   
       string user_message = "Default message!";
   
       while (!quit_requested())
       {
           process_events();

2. Now let’s add the text box. We can use the Text Box function, which takes a string - the current text, and a position - where to draw it.

   It then returns the updated text - if the user hasn’t typed anything, this will be the same text that was passed in. But if the user has typed something, this will be our new text, and we can store it in the variable!

   For example, user_text = text_box(user_text, rectangle_from(0,0,200,24)); would show a text box at the top-right corner of the screen, with the text that’s in the variable user_text, and if the user has altered the text, it would return the new text and store it back into user_text.

   Finally, we can use this variable in our Write Line, to write the user’s text to the console.

   Remember - this all needs to go inside the main while loop. Otherwise the text box will only exist for a split second before vanishing - we need to keep it alive!

   C++

           user_message = text_box(user_message, rectangle_from(300, 220, 200, 24));
   
           if (button("Write To Terminal!", rectangle_from(300, 260, 200, 24)))
           {
               write_line(user_message);
           }

   See how user_message gets passed in to the Text Box, and then that value flows back out as the return, and gets assigned back to user_message. This is how all the other element functions, like Slider, and Number Box work too!

   Updating variables

   All interactive SplashKit elements have a parameter for the current value, and return the updated value. So usually you can follow a pattern like this

   my_variable = a_ui_element(my_variable, other options...)

   where the variable goes into the function, then gets assigned out the other end.

   And that’s it! In two lines of code we added our text box as well - this is what it will look like now:

Here’s the complete code up until this point:

C++

#include "splashkit.h"

int main()
{
    // open a window
    open_window("My Interface!", 800, 600);

    // define variables
    string user_message = "Default message!";

    // main loop
    while (!quit_requested())
    {
        // get user events
        process_events();

        // clear screen
        clear_screen(COLOR_WHITE);

        // interface!
        user_message = text_box(user_message, rectangle_from(300, 220, 200, 24));

        if (button("Write To Terminal!", rectangle_from(300, 260, 200, 24)))
        {
            write_line(user_message);
        }

        // finally draw interface, then refresh screen
        draw_interface();

        refresh_screen();
    }

    // program ends, and the window closes
    return 0;
}

Practice Activity

Let’s try adding one more element - this time we can try adding a slider! For fun, let’s try making the slider change the width of the elements themselves.

1. Just like before, we need to add a new variable outside the loop, to hold the current width. We can make it a float, call it width, and give it an initial value of 200.
2. Now we’ll need to make the slider inside the while loop! To do this we can use the function Slider, which takes the current value, then a minimum value, a maximum value, and finally the position. For example, slider(current_value, 0, 100, rectangle_from(300, 300, 200, 24)), will create a slider with the range 0 to 100, in the middle of the screen. It’ll show the value current_value, and return the final value (including if the user changed it).
3. To make the elements actually change width, we just need to update the calls to Rectangle From, changing the width to our variable width instead! You can also try centering the elements, by adjusting their x coordinate as well.

Here is one way to do write this, but don’t peek until you’ve tried it yourself!

C++

    // define variables
    string user_message = "Default message!";
    float width = 200;

    // main loop
    while (!quit_requested())
    {
        // get user events
        process_events();

        // clear screen
        clear_screen(COLOR_WHITE);

        // interface!
        user_message = text_box(user_message, rectangle_from(400 - width/2, 220, width, 24));

        if (button("Write To Terminal!", rectangle_from(400 - width/2, 260, width, 24)))
        {
            write_line(user_message);
        }

        width = slider(width, 10, 400, rectangle_from(300, 300, 200, 24));

        // finally draw interface, then refresh screen
        draw_interface();

        refresh_screen();
    }

Wrap up

If we put together all the code so far, we get this complete example here!

Hopefully now you understand how easy it is to make a dynamic interface in SplashKit!

C++

#include "splashkit.h"

int main()
{
    // open a window
    open_window("My Interface!", 800, 600);

    // define variables
    string user_message = "Default message!";
    float width = 200;

    // main loop
    while (!quit_requested())
    {
        // get user events
        process_events();

        // clear screen
        clear_screen(COLOR_WHITE);

        // interface!
        user_message = text_box(user_message, rectangle_from(400 - width/2, 220, width, 24));

        if (button("Write To Terminal!", rectangle_from(400 - width/2, 260, width, 24)))
        {
            write_line(user_message);
        }

        width = slider(width, 10, 400, rectangle_from(300, 300, 200, 24));

        // finally draw interface, then refresh screen
        draw_interface();

        refresh_screen();
    }

    // program ends, and the window closes
    return 0;
}