This article will help you understand how to customize the layouts of your interfaces in SplashKit.Written by Sean Boettger and others on October 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:
Let’s add a panel now! Adding a panel takes two lines of code:
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!
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 Panelreturns 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:
Just testing the code above will give us this! We can already drag around and resize the panel, so let’s start adding elements!
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.
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:
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!):
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.
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.
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:
Finally, to return to the default layout, just call Reset Layout.
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.
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.