GUI

Creations

Sorunome

5 years ago

This tutorial aims to explain how to use the GUI functions of the library. The following GUI functions exist:

Keyboard

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

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

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);



And that pretty much wraps up this GUI tutorial! If you have any questions and/or suggestions, please drop a comment below!

View full creation

ragnarok93

NEW 5 years ago

Love your tutorials <3. For sure i will use it later in my game ;).

Sutchig

NEW 5 years ago

Thanks for gb.gui.menu :) And for the usage

ddrmax

NEW 5 years ago

merci pour ce tutoriel, ça permettera de faciliter la creation du logiciel de configuration du wifi pour le NetLink quand on utilise un esp 8266 

jicehel

NEW 5 years ago

Great tuto, alot of things very useful that i didn't know. Many thanks

ripper121

NEW 5 years ago

Is it in the master from the Gamebuino Meta GIT or where do we get it?

Aurélien Rodot

5 years ago

Yes it's in the master, you can udpate your library through the arduino library manager :)

Aurélien Rodot

NEW 5 years ago

ripper121 ripper121

Yes it's in the master, you can udpate your library through the arduino library manager :)

Balea

NEW 5 years ago

Thanks for the tutorial! this will help a lot ^^

ripper121

NEW 5 years ago

"Bug"

When the text is to long and goes over the end of a Menu entry, it will be warpt a line down and then you can se behind the Menu entry some Text Artifacts.

jicehel

NEW 5 years ago

I have an error when i try it. I have upgaded my bibliotheque (my version is now: 1.1.0)

The eror is: exit status 1
'class Gamebuino_Meta::Gamebuino' has no member named 'gui'

I had ead that GUI was in version you can update in Arduino tools

=> I do an error in the method or have something to do ?

My code is :

// Le titre du menu
    const MultiLang title[] = {
    { LANG_EN, "Select game mode" },{ LANG_FR, "Choix du mode de jeu" },};

    // Les entrées du menu en anglais et en français
    const MultiLang entryOnePlayer[] = {
    { LANG_EN, "One player mode" },  { LANG_FR, "Mode un joueur" }, };
    const MultiLang entryMultiplayer[] = {
    { LANG_EN, "Two players mode" },  { LANG_FR, "Mode deux joueurs" },};
    const MultiLang entryFreePlay[] = {
    { LANG_EN, "Free play" },  { LANG_FR, "Jeu libre" },};

    // le tableau des entrées du menu
    const MultiLang* entries[] = {
    entryOnePlayer,
    entryMultiplayer,
    entryFreePlay,
    };

    // On peut appeler le menu
    uint8_t entry = gb.gui.menu(title, entries);
   
    // mode un joueur
    switch (entry) {
    1 : setEtat(ETAT_DEBUT_JEU);
        break
    2:  setEtat(ETAT_MENU_MULTIJOUEURS);
        break    
    3:  setEtat(ETAT_FREE_PLAY);
        gb.display.setCursor(2,2);
        gb.display.printf("Free play!");
        break
    }    
}


Sorunome

5 years ago

Hey, did you try to restart the arduino IDE after updating the library? Are you sure you don't have manually cloned the git repository at some point into the Arduino/libraries folder? Because if you did that older version would still be used.

Also, for longer code, you could try to use the multiline code block!

It's the one in the center

Nux

NEW 5 years ago

Well explain and this will be super usefull for my games :)

Sorunome

NEW 5 years ago

jicehel jicehel

Hey, did you try to restart the arduino IDE after updating the library? Are you sure you don't have manually cloned the git repository at some point into the Arduino/libraries folder? Because if you did that older version would still be used.

Also, for longer code, you could try to use the multiline code block!

It's the one in the center

jicehel

NEW 5 years ago

That right Sorunome. An zip vesion was in the directories but not visible in the version list on the Arduino GUI. GUI woks now so i'll be able to correct other errors  ;)  Thanks for your help.

chris-scientist

NEW 5 years ago

J'ai le même problème que jicehel, j'ai essayé des trucs mais rien n'a marché... J'ai pourtant importé le ZIP "Gamebuino_META-1.1.0.zip" mais j'ai un message de l'IDE qui indique "veuillez regarder le menu importer la bibliothèque" mais je ne trouve rien de correspondant...

Si quelqu'un peut me dire comment utiliser le nouveau gb.gui.menu en corrigeant le problème de bibliothèque.

Merci d'avance

jicehel

NEW 5 years ago

La bibliothèque est dans ton profil utilisateur si je me souviens bien


chris-scientist

5 years ago

Tu veux dire dans C:...\ArduinoData\staging\libraries ?

chris-scientist

NEW 5 years ago

jicehel jicehel

Tu veux dire dans C:...\ArduinoData\staging\libraries ?