Tramway SDK 0.0.9
Github
Quick links
Home
Get Started
GUI
The GUI system provides GUI widgets.
Unlike inferior GUI systems, which use objects (Win32, etc.) or classes (Java Swing, etc.), this GUI system is immediate mode. Which means that instead of creating an object, you just call a function once per frame.
Key concepts
Widget
GUI element, i.e. buttons, text boxes, checkmarks, radio buttons, etc.
Frame
Frames are used to position widgets. They are arranged in a stack. When you push a frame, all of the consequent widgets will be drawn inside that frame. After you are done with a frame, you need to pop it from the frame stack.
Immediate mode
This basically means that you call function instead of creating objects to
manage GUI widgets. For example, the function for creating a button is
GUI::Button(). Calling this function will render a button on
the screen. This function returns the value true if it has been
clicked on.
Pushing frames
Frames can be created using absolute coordinates, or pushed relative to the
underlying frame. For example, pushing frame 100 pixels from
FRAME_TOP will create a frame with the topmost 100 pixel rows
from underlying frame. Switching it to FRAME_TOP_INV will skip
the topmost 100 pixel rows and select everything below it.
This is how we push the frames.
Very simple, very easy, very nice.
Fonts
Fonts are basically just sprites that have been registered
For each character that is rendered, its character code in the encoding is used as an index to select a frame from the spritesheet.
The fonts can be used to draw text. They are also used for widgets themselves.
If you want to use some pre-made widget and text fonts, then you can use the Menu extension. It contains some fonts that you can use.
Widgets
Glyph
Draws a single glyph from the font spritesheet.
Text
Draws some text.
Button
Draws a clickable button. The button function returns true if it has been clicked.
Radio button
Allows selection between several exclusive choices. The choices are represented by an index.
Checkbox
Allows a boolean yes/no type of selection.
Slider
Allows selecting a floating point value by dragging a slider.
Textbox
Allows text input.
Programming in C++
#include <framework/gui.h>
API documentation
page.
The GUI system needs the Render and the UI systems to be initialized before being initialized itself.
GUI::Init();
// main loop
while (true) {
// GUI widgets go here
GUI::Update();
}
Pushing frames is easy, but you need to remember to pop them afterwards.
GUI::PushFrameRelative(FRAME_LEFT, 150);
// GUI widgets go in here
GUI::PopFrame();
GUI::PushFrameRelative(FRAME_LEFT_INV, 150);
GUI::PushFrameRelative(FRAME_INSET, 10);
// GUI widgets go in here
GUI::PopFrame();
GUI::PopFrame();
Here's how to use the various widgets.
enum {
ICON_FROG,
ICON_TOILET
};
// registering a new font
Sprite* icon_sprite = Sprite::Find("font-icon");
font_t FONT_ICON = RegisterFont(icon_sprite);
// drawing a glyph from a font
GUI::Glyph(FONT_ICON, ICON_FROG);
// drawing some text
GUI::Text(FONT_BOLD, "Hello, world!", TEXT_LEFT);
// buttons
if (GUI::Button("Click here!")) {
printf("Button clicked!\n");
}
enum {
CHOICE_NONE,
CHOICE_A,
CHOICE_B
};
uint32_t selected = CHOICE_NONE;
// radio buttons
GUI::RadioButton(CHOICE_A, selected, "Choice A");
GUI::RadioButton(CHOICE_B, selected, "Choice B");
bool checked = false;
// checkbox
GUI::CheckBox(checked, "Check to select.");
float value = 0.0f;
// slider
GUI::Slider(value);
const size_t text_length = 100;
static char text[text_length] = "hello!";
// textbox
GUI::TextBox(text, text_length);
// new line
GUI::NewLine(LINE_NORMAL);
Scripting in Lua
Not yet implemented.
