Developer Guide - Creating a Simple GUI
Creating a GUI is divided into four stages - initialising the Woopsi object, creating screens, creating windows, and creating gadgets.
Creating a Woopsi Object
Creating a GUI with Woopsi is simple. To begin, we need to initialise the Woopsi singleton object. In the "main.cpp" file, in the "main()" function, add the following:
// Create woopsi
woopsiApplication = new Woopsi();
The "woopsiApplication" singleton object we have created gives us our entry point into the GUI.
Creating a Screen
Next we need to add a new screen so that we have a workspace for the interface. To do this, we use this code:
// Create screen
AmigaScreen* screen = new AmigaScreen("My Screen");
woopsiApplication->addGadget(screen);
This achieves two things. We've created a new screen and given it the name "My Screen" (this appears in the screen's title bar). We've also added it to the Woopsi singleton as a child gadget.
Creating a Window
Now that we've got a screen, we need to add windows to it. Windows are added to screens in the same way:
// Create window
AmigaWindow* window = new AmigaWindow(20, 20, 100, 100, "My Window", GADGET_DRAGGABLE);
screen->addGadget(window);
The are two differences here. Firstly, we are creating an AmigaWindow object instead of an AmigaScreen object. Secondly, we are adding the window to the screen instead of the woopsiApplication singleton. This makes the window a child of the screen.
The parameters for the AmigaWindow constructor are as follows:
x | The x co-ordinate of the top-left corner of the window, relative to the screen that contains it |
y | The y co-ordinate of the top-right corner of the window, relative to the screen that contains it |
width | The width of the window |
height | The height of the window |
title | The name of the window to be displayed in its title bar |
flags |
Note that although the x and y co-ordinates are entered as a signed short, these values should always be positive. They are signed only to retain consistency with PALib's Stlyus struct.
Creating a Gadget
You can probably see a pattern emerging. Each new item we create is added to the previous item. What we are doing is building a hierarchy of GUI objects - windows belong to screens, which in turn belong to Woopsi.
All gadgets follow the same pattern. There are several classes of gadget that can be added to windows, and each offers different functionality. Each gadget represents a different kind of UI component. Other classes of gadget that are available include:
- Textbox - a box that will display a single line of text
- Button - a clickable box that displays a single line of text and that will fire an event when clicked
- ScrollingTextBox - a gadget that displays multiple lines of text (as many as the DS' memory will allow) that can be scrolled using the stylus; it also features a vertical scrollbar
- SuperBitmap - provides a canvas on which we can draw using a set of drawing functions; the canvas can be larger than the window, and can be scrolled with the stylus
If we want to add a button to our window, we would use this code:
// Create button
Button* button = new Button(5, 5, 60, 60, "Hello World!");
window->addGadget(button);
Summary
In just a few lines of code, we've created a Woopsi instance, added a screen to it, created a window and defined a clickable button. Extracting all of the code from the above into an easily-viewable format gives us this:
// Create woopsi
woopsiApplication = new Woopsi();
// Create screen
AmigaScreen* screen = new AmigaScreen("My Screen");
woopsiApplication->addGadget(screen);
// Create window
AmigaWindow* window = new AmigaWindow(20, 20, 100, 100, "My Window", GADGET_DRAGGABLE);
screen->addGadget(window);
// Create button
Button* button = new Button(5, 5, 60, 60, "Hello World!");
window->addGadget(button);