GUI functions

Keyboard

The keyboard provides a nice, graphical keyboard so that the user can enter some text, e.g. their name for a highscore. You use it with gb.gui.keyboard. As the reference page shows, it mainly takes two parameters: one for the title, and one for the output&default text.

So, to ask the user for their favourite animal, you can simply do this:

char text[12] = "Foxies";
gb.gui.keyboard("Favorite Animal?", text);

The answer they entered is then in the text variable. As we set text from the beginning to "Foxies" that will be the default text. If we want a blank default text, we need to make sure that the first entry of the string is '\0' like so:

char text[12];
text[0] = '\0'; // make sure we have a blank default text
gb.gui.keyboard("Favorite Animal?", text);

Why is that? Because char text[12]; does not initialize text, thus, elsewise, it'd be left uninitialized, meaning its contents are basically random.

Please note that, if you are using this to ask for the players name, e.g. for a highscore list, it is highly recommended to use gb.getDefaultName as the default setting, like so:

char playerName[13];
gb.getDefaultName(playerName);
gb.gui.keyboard("New Highscore!", playerName);

Now, let's say we want to localize our title text, so that our game isn't available in English. We can just use the normal language API as expected!

const MultiLang title[] = {
	{ LANG_EN, "Favorite Animal?" },
	{ LANG_DE, "Lieblingstier?" },
};
char text[12];
text[0] = '\0';
gb.gui.keyboard(title, text);

Aaaaaand, we are good to go. OFC if the length of text or title can't be automatically determined (e.g. due to the variables being in external includes), you can specify them manually:

const MultiLang title[] = {
	{ LANG_EN, "Favorite Animal?" },
	{ LANG_DE, "Lieblingstier?" },
};
char text[12];
text[0] = '\0';
gb.gui.keyboard(title, text, 11, 2);

As you can see, first we specify the length of our result string in characters and after that we specify the number of language entries.

Menu

The menu provides an easy-to-use menu where you can pick the options and then do stuff based on which option was picked. You use it with gb.gui.menu. The reference explains the basic parameters: one title to display and then an array of all the entries. Here is a simple example:

const char* entries[] = {
	"Pizza",
	"Spaghetti",
	"Noodles",
	"Ice Cream",
};
uint8_t entry = gb.gui.menu("Best food?", entries);

This simple menu will ask you what "Best food?" is, with a selected amount of options. The result will be in entry, 0 being in this case "Pizza", 1 being "Spaghetti" etc.

Just as with the keyboard, you can also use the localization API here. However, you need to make sure that the number of language entries is the same for everything:

// the title
const MultiLang title[] = {
	{ LANG_EN, "Best food?" },
	{ LANG_DE, "Lieblingsessen?" },
};

// all the entries
const MultiLang entryPizza[] = {
	{ LANG_EN, "Pizza" },
	{ LANG_DE, "Pizza" },
};
const MultiLang entrySpaghetti[] = {
	{ LANG_EN, "Spaghetti" },
	{ LANG_DE, "Spaghetti" },
};
const MultiLang entryNoodles[] = {
	{ LANG_EN, "Noodles" },
	{ LANG_DE, "Nudeln" },
};
const MultiLang entryIceCream[] = {
	{ LANG_EN, "Ice Cream" },
	{ LANG_DE, "Eis" },
};

// the entry array
const MultiLang* entries[] = {
	entryPizza,
	entrySpaghetti,
	entryNoodles,
	entryIceCream,
};

// finally call the menu
uint8_t entry = gb.gui.menu(title, entries);

As you can see, it is a bit more complex here to build up the entries array. This is because a simple inline-definition doesn't work.

If the number of entries or the number of languages can't be automatically determined, you can set them yourself:

// same title and entries definitions as above

uint8_t entry = gb.gui.menu(title, entries, 4, 2);

As you can see, first we set how many entries we have, and then how many languages.

Popup

The popup is an easy-to-use in-game popup that is showed temporarily for a given duration. As the reference explains, it basically only has two parameters: one string to display and one number for how long to display it. The duration number hereby is the number of frames that the popup will be fully displayed. This excludes fading in and out:

gb.gui.popup("Hello World", 50);

At 25FPS (which is default), this popup would fully display for 2 seconds (25*2 = 50).

You can also use localized text for the popup:

const MultiLang popupText[] = {
	{ LANG_EN, "Hello World" },
	{ LANG_DE, "Hallo Welt" },
};
gb.gui.popup(popupText, 50);

Pretty straight forward. If the number of available languages can't be autodeterimined, just specify it manually:

const MultiLang popupText[] = {
	{ LANG_EN, "Hello World" },
	{ LANG_DE, "Hallo Welt" },
};
gb.gui.popup(popupText, 50, 2);