Circle OS tutorial: Menu

In this tutorial, we are going to learn how one can use menu GUI element available in the circle OS. For this tutorial,we are going to implement a simple game, wherein you are presented a random math question and the list of options(you guessed it right, the list of options are actually implemented using the menus) one among them is the right answer. Once an option is selected, you are notified whether the choice was right or wrong. As was the case with the previous tutorial, I am going to explain about the game logic and then move on to circle OS menu usage details.

Game Logic:

The game logic is fairly simple, two random numbers are generated and one among 3 arithmetic operations, +/-/* is performed and the result is stored. A menu item is created and populated with 3 random numbers along with correct answer. When user makes a selection, in menu selection call back, the correctness of the choice is checked and appropriate messages is displayed.

The implementation:

The function that does most of the heavy lifting is the one that goes by the name “Wild_Math_Question_Appears” . In this function, first two random number are generated (both between 0-10) and then one more random number is generated (between 0-3) to determine what math operation we need to use. The selected math operation (one among +,- or *) is performed on the random numbers and the result is stored. Then 3 other random numbers are generated to populate the menu along with right choice. Before we see how it's done, let's have a look at “tMenu” structure which we are going to use in creating the menu item.

The very first element indicates whether or not you want to display the title for the menu. If set to 1, the title as supplied in the next argument “Title” is displayed or else no title is displayed. The next item is the number of menu items you want display and yes there is a limit as to how many items you can have in a menu, it is 8 as defined using #define MENU_MAXITEM. The next couple of arguments are for setting the position for the menu to be displayed. We are not going to change this arguments and let the circle OS handle the positioning (which would be the about at center of the LCD display). After that we have the “SelectedItem” which instructs the Circle OS to highlight a particular menu item when the menu is drawn. For example, we set this argument to zero, the first menu is highlighted on the other hand if this argument is 1, the second option is highlighted and so on.

Now we come to the important structure member which is “Items” and it is of type “tMenuItem”. Here we define what would be the name of the menu choice, its callback handling and so on.

The first argument is the label that you want to be displayed as a part of the menu choice item. In our case, these are going to char arrays that we populate dynamically. The next menu item is “Fct_Init” which is a function pointer which should point to a function that will initialize stuff for the selected menu item. If this function returns “MENU_CONTINUE_COMMAND” then the function as pointed by “Fct_Manage” is called. This function is like the action part of the menu item. In out application, we are not going to use this function since we only need to check if the selected choice is correct or not. The last option lets the Circle OS to clean up the menu or not.

Now we will go back to the game implementation details. Only “Application_Ini” is implemented. In this function, the current menu is cleared and then “Wild_Math_Question_Appears()” is called which will create a random math question and populate the fields in “Options_Menu” that corresponds to 4 choices that user can choose from and is the menu is set using the “MENU_Set()” function.

Next, we have a look at the “Options_menu” variable which is our main application menu.

/** The “options for the answer'” menu */

tMenu Options_Menu =

{

     1, /* Display the title */

     "Choices", /* Title of the menu */

      6, /* Number of items in the menu list */

      0, 0, 0, 0, 0, 0, /* Let us not bother ourselves with these options */

     { //menu label init manage remove=1

     { menuOptions[0], Option1_Ini, 0, 1 },

     { menuOptions[1], Option2_Ini, 0, 1 },

     { menuOptions[2], Option3_Ini, 0, 1 },

     { menuOptions[3], Option4_Ini, 0, 1 },

     { "Replay", Replay_Ini, 0, 1 },

     { "Quit", Quit_Ini, 0, 0 },

}

};

While rest of the things in “tMenu”are clear in the above explanation, one thing remains which is “menuOptions” which is a two dimensional array.

/** The options string array, the labels on the menu items */

char menuOptions[3][4];

These buffers are are updated by the “Wild_Math_Question_Appears()” to reflect the options available to the user to select from. The Fct_Init (Option1_Ini, Option2_Ini....) call backs, will validate the answer and prints the result of the game and sets a new menu which lets user select if he wishes to continue with the game or not (all this is done via “Handle_Game”). In case the user makes a “Replay” selection, the “Wild_Math_Question_Appears” is called again and the new menu is set and the process continues until the user quits.