GUI

Ce tutoriel cherche à expliquer comment utiliser les fonctions GUI (Graphical User Interface) de la bibliothèque:

• Clavier
• Menu
• Popup

Clavier

Le clavier d’origine permet aux utilisateurs d’entrer du texte avec une jolie interface graphique, comme par exemple pour enregistrer leur nom lors d'un nouveau score. Il s'utilise avec gb.gui.keyboard. Comme la page de référence le montre, cette fonction prend généralement deux paramètres : un pour le titre et un autre pour le texte par défaut / sortie du texte.

Donc, pour demander à un utilisateur son animal préféré, il suffit simplement de faire ça :

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

La réponse qu’ils entrent est dans la variable text. Comme nous avons défini text avec la valeur de Foxies au début, ce sera le texte par défaut. Si vous voulez un texte vide par défaut, il faut s’assurer que la première valeur de la chaine de caractères est '\0':

char text[12];
text[0] = '\0'; // Assurons nous d'avoir un texte par défaut vide
gb.gui.keyboard("Favorite Animal?", text);

Pourquoi ça? Parce que char text[12]; déclare sans initialiser. Donc, sans notre ligne text[0] = '\0', le texte resterait non-initialisé, ce qui revient à dire que c'est une chaine de caractères aléatoire.

Veuillez noter que si vous utilisez ça pour demander le nom du joueur pour une liste de score, il est très fortement recommandé d’utiliser gb.getDefaultName comme nom par défaut, comme ceci:

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

Disons maintenant que vous voulez ajouter de la localisation pour votre jeu, comme ça il pourra être joué dans plus d'un pays :D On peut évidement utiliser l'API de langage!

const MultiLang title[] = {
    { LANG_EN, "Favorite Animal?" },
    { LANG_FR, "Animal Préféré?" },
};
char text[12];
text[0] = '\0';
gb.gui.keyboard(title, text);

Eeeeeeeeeet, nous voilà prêt pour l'international. Bien évidement, si la taille de text ou title ne peuvent pas être auto-déterminé (par exemple dans le cas d'inclusion externes), vous pouvez simplement les ajouter manuellement:

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

Comme vous pouvez le voir, on donne d'abord la longueur de notre résultat en nombre de caractères, et après on précise le nombre d'entrées pour l'API de langage

Menu

Le menu fournit est facile d'utilisation. Vous créez des choix, puis vous faites des choses en fonction de chaque choix sélectionné. Il s'utilise avec gb.gui.menu. La référence explique les paramètres basiques: le titre à afficher et un tableau de toutes les entrées. Voici un exemple simple:

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

Ce menu simple vous demandera "Best food?" et a une quantité limité de réponses. La réponse sélectionné par l'utilisateur sera mise dans entry, avec 0 correspondant à "Pizza", 1 à "Spaghetti", etc.

Tout comme avec le clavier, l'API de localisation fonctionne ici. Cependant, il faut vérifier que la quantité de traduction est la même pour chaque option (et le titre):

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

// Toutes les options
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" },
};

// Le tableau d'options
const MultiLang* entries[] = {
    entryPizza,
    entrySpaghetti,
    entryNoodles,
    entryIceCream,
};

// Le menu multi-langue
uint8_t entry = gb.gui.menu(title, entries);

Comme vous pouvez le voir, c'est un peu plus compliqué de construire un tableau d'options. C'est dû au fait qu'une définition inline ne fonctionne pas ici.

Si le nombre d'options dans entries ne peut pas être auto-déterminé, vous pouvez entrer sa valeur par paramètre:

// Même titre et options qu'au dessus
uint8_t entry = gb.gui.menu(title, entries, 4, 2);

Ici, on entre d'abord le nombre d'options, puis le nombre de langages.

Popup

Le pop-up est moyen facile d’utiliser des pop-ups temporaires dans vos jeux. Les pop-ups restent à l'écran pendant une durée donnée. Comme dis dans la référence, il a deux paramètres simples: une chaine de caractères à afficher et un entier correspondant à la durée d’affichage. La durée d’affichage est en nombre d'images (25 images = 1 seconde par defaut). Les transitions sont exclues de cette durée:

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

Ce pop-up serait affiché 2 secondes (25*2 = 50).

Vous pouvez évidement utilisez l'API de langues pour les pop-ups

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

C'est assez simple. Et encore un fois, si le nombre de langues ne peut être auto-déterminé, il faut les passer par paramètre:

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

Et voilà, le tutoriel sur les fonction GUI est terminé! Si vous avez des questions/suggestions, n'hésitez pas à partager vos pensés avec un commentaire!