Layouts in User Interfaces

This article will help you understand how to customize the layouts of your interfaces in SplashKit. Written by Sean Boettger on May 5 2024

In this article we’ll see how we can create layouts for our SplashKit interfaces! This will allow us to automatically position our UI elements in rows and columns, hide them under drop downs, and place them on draggable panels, which will help us create really detailed and dynamic interfaces.

The last few sections of this article will be closer to an API reference than the previous one - rather than complete examples, there will be mostly snippets of code you can try out to explore each concept!

Part 1: Creating panels

All the automatic layouting functionality in SplashKit starts by creating a container, and the most useful container is a ‘panel’. A panel is like a mini window inside your program, that can be dragged around and resized. We’ll be placing our elements inside these panels.

Here’s just a basic example from the previous tutorial that we can get started from:

SplashKit Interfaces

Remember that SplashKit uses an immediate mode GUI paradigm. This means we need to place all of our interface code inside the main while loop, between Process Events and Draw Interface!

C++

#include "splashkit.h"

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

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

        // clear screen
        clear_screen(COLOR_WHITE);

        // ...we'll put out interface code here...!

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

        refresh_screen();
    }

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

Let’s add a panel now! Adding a panel takes two lines of code:

1. First we begin the panel with Start Panel, which takes a name for the panel, and a rectangle for its initial position. For example start_panel("My panel", rectangle_from(50,50,200,100)) creates a panel with the title “My panel”, that appears close to the top-left corner (50,50), and a width and height of 200 by 100.

   After this we can place all the UI elements that should go on the panel, just like we were!

2. Then once we’re done, we need to end the panel with End Panel, where we just give it the same name (so for example end_panel("My panel")).

One really important thing to note here is that Start Panel returns whether the panel is visible or not, so we need to make sure to check this as well, and only create elements and end the panel if the panel is open, like so:

C++

// start the panel and check if it's open/visible
if (start_panel("My panel", rectangle_from(50,50,200,100)))
{
    // ...here we'll create all the UI elements, inside the braces { ... }

    // end the panel
    end_panel("My panel");
}

Just testing the code above will give us this! We can already drag around and resize the panel, so let’s start adding elements!

Creating layout elements

Most of the layout elements, like Panel, Popup, and Treenode work the same way.

1. We start them, and possibly check if they’re open or closed. We also give them a name. (e.g if (start_panel("myPanel", ...)), if (start_treenode("myTreenode", ...)))
2. We add our elements
3. Finally we end them, using the same name. (e.g end_panel("myPanel"), end_treenode("myTreenode"))

Part 2: Adding UI elements

Adding elements is very similar to what we were doing last tutorial - we just don’t need to specify the position anymore! For example previously we added a button with button("My Button!", rectangle_from(300, 260, 200, 24)) - now we can just use button("My Button!")!

This’ll give us a button like this:

Similarly, we can add a Text Box by declaring a string variable outside the main loop, and then calling my_string = text_box(my_string):

Here’s the full code recreating what we had last tutorial, while creating a panel and adding the elements inside it.

C++

#include "splashkit.h"

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

    // setup a variable to store the user's string - same as last tutorial
    string user_message = "Default message";

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

        // clear screen
        clear_screen(COLOR_WHITE);

        // here we start the panel
        if (start_panel("My panel", rectangle_from(50,50,200,100)))
        {
            // create the elements, just like last tutorial!
            if (button("Write To Terminal!"))
            {
                write_line(user_message);
            }

            user_message = text_box(user_message);

            // end the panel
            end_panel("My panel");
        }

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

        refresh_screen();
    }

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

Elements inside panels

To place elements inside panels, we just need to create them between the start and end calls.

Another useful thing you can do now is add labels to your elements. You can do this by passing an additional string to each element function at the start - as an example, text_box(my_string) can become text_box("Message", my_string), which will give us this:

SplashKit Interfaces

Here’s a quick rundown of common element functions:

Without Label	With Label
boolean button(text)	boolean button(“Label:”, text)
boolean checkbox(text, state)	boolean checkbox(“Label:”, text, state)
number slider(value, min, max)	number slider(“Label:”, value, min, max)
string text_box(text)	string text_box(“Label:”, text)

---

See the API for more functions!

Part 3: Layout elements (Reference)

Now that we can create panels and place UI elements on those panels, let’s see how we can use extra elements to help lay them out!

This section will focus on mainly demonstrating each concept. Make sure to try each of these snippets out - you can just copy paste them into anywhere between your start/end panel calls.

Some of the easiest ways to group our elements together, is to place them under headers and inside ‘insets’.

Headers

Headers are really easy to add - we can use the Header function, which takes a name for the heading, and returns if the header is open (like the panels!):

C++

if (header("Edit Message!"))
{
    user_message = text_box(user_message);
}

Note: headers do not need to be began/ended, so they’re nice and easy to use!

Insets

Insets let you group a bunch of elements inside a fixed-size region! They can be created using Start Inset, which takes a name, and a height. After creating your elements, you can then call End Inset with the same name to finish it.

Here’s a code example - an inset is started, and six buttons are created inside it. Finally, the inset is ended.

C++

paragraph("This text is outside the inset area!");
start_inset("Inset area", 60);
    if (button("Button 1!")) write_line("Button 1 clicked!");
    if (button("Button 2!")) write_line("Button 2 clicked!");
    if (button("Button 3!")) write_line("Button 3 clicked!");
    if (button("Button 4!")) write_line("Button 4 clicked!");
    if (button("Button 5!")) write_line("Button 5 clicked!");
    if (button("Button 6!")) write_line("Button 6 clicked!");
end_inset("Inset area");

Another powerful feature of insets, is that you can use them as a container directly on the main window too!

Tree nodes

Tree nodes allow you to organize your elements as a tree - like a file system! You can collapse and expand the nodes individually, so this is a great way to organize data.

Here’s a code example - various nested tree nodes are started and ended with, buttons placed in between - this creates a hierarchy.

C++

if (start_treenode("Some buttons!")){
    if (button("Button 1!")) write_line("Button 1 clicked!");
    if (button("Button 2!")) write_line("Button 2 clicked!");
    if (button("Button 3!")) write_line("Button 3 clicked!");
    end_treenode("Some buttons!");
}

if (start_treenode("Some more buttons!")){
    if (button("Button 4!")) write_line("Button 4 clicked!");
    if (button("Button 5!")) write_line("Button 5 clicked!");

    if (start_treenode("Buttons in buttons!!")){
        if (button("Button 6!")) write_line("Button 6 clicked!");

        end_treenode("Buttons in buttons!!");
    }

    end_treenode("Some more buttons!");
}

Part 4: Advanced layouts (Reference)

Rows/Columns

The elements placed in panels are automatically placed in rows - by default one element per row. We can create columns ourselves, allowing us to group our elements together on single rows!

To start, we need to call Start Custom Layout - this removes the default layouting. Now we can use the following functions to adjust how many elements we can place on the row:

SplashKit Interfaces

Here’s a rundown of common layout functions:

Name	Description
Split Into Columns(count)	Splits the current row into equal sized columns - this is how many elements you can place on the one row
Single Line Layout()	Just place all elements on a single row with their default size
Add Column(width)	Adds a single column of a specific width in pixels
Add Column Relative(width)	Adds a single column of a specific width relative to the total width (a value between 0 and 1)

---

You’ll usually want to use the first two, while the bottom two can be used for more custom layouts.

See the API for more functions!

Finally, to return to the default layout, just call Reset Layout.

Custom layouts

When creating custom layouts, you’ll usually want to:

1. Call Start Custom Layout to clear the default layout.
2. Setup the layout using various functions, like split_into_columns(count).
3. Add your elements.
4. Reset the layout to default with Reset Layout.

You can also adjust the height of a row, using Set Layout Height.

Here’s an example, where we create six buttons - three on each row, with the top row being taller.

C++

start_custom_layout();
split_into_columns(3);
    set_layout_height(64);
    if (button("Button 1!")) write_line("Button 1 clicked!");
    if (button("Button 2!")) write_line("Button 2 clicked!");
    if (button("Button 3!")) write_line("Button 3 clicked!");

    set_layout_height(0); // 0 resets to default
    if (button("Button 4!")) write_line("Button 4 clicked!");
    if (button("Button 5!")) write_line("Button 5 clicked!");
    if (button("Button 6!")) write_line("Button 6 clicked!");
reset_layout();

Entering Columns

A really powerful feature of columns, is that we can enter a column, and add elements to it directly without automatically moving to the next one. This allows us to create much more complex layouts.

To enter a column, simple use Enter Column - now elements will be placed inside the current column.

Once you’re done, you can leave it with Leave Column.

Here’s an example:

C++

start_custom_layout();
split_into_columns(2);
    enter_column();
        set_layout_height(64);
        if (button("Button 1!")) write_line("Button 1 clicked!");
        if (button("Button 2!")) write_line("Button 2 clicked!");
    leave_column();
    enter_column();
        set_layout_height(0); // 0 resets to default
        if (button("Button 4!")) write_line("Button 4 clicked!");
        if (button("Button 5!")) write_line("Button 5 clicked!");
        if (button("Button 6!")) write_line("Button 6 clicked!");
    leave_column();
reset_layout();

Take note how Button 1 and Button 2 are placed in the same column, rather than row now. This is really powerful - you can now split the column again, adjust heights, and so on, to lay things out exactly how you want.

Wrap up

Hopefully you now understand how to use SplashKit’s layouting functionality! This can be a little tricky to understand, so as always make sure to play around with the code and try things out!

Good luck using it in your projects! In the next tutorial, we’ll see how we can style interfaces, to make them match our projects.