Modules/game menu

The game_menu module automatically manages menus based on tables representing each page and its interactions.

Dependencies

Dependency on other modules:

• input
• print

Settings

Modules can be customized into the project's msxgl_config.h file to fullfill your needs:

#define MENU_USE_DEFAULT_CALLBACK	TRUE		// Use default input/print callback
#define MENU_SCREEN_WIDTH		MENU_VARIABLE	// Screen width
#define MENU_FRAME_X			0		// Frame position X
#define MENU_FRAME_Y			6		// Frame position Y
#define MENU_FRAME_WIDTH		32		// Frame width
#define MENU_FRAME_HEIGHT		8		// Frame height
#define MENU_CHAR_CLEAR			'\0'		// Clear character
#define MENU_CHAR_CURSOR		'@'		// Cursor character 
#define MENU_CHAR_TRUE			'O'		// True character
#define MENU_CHAR_FALSE			'X'		// False character
#define MENU_CHAR_LEFT			'<'		// Left edit character
#define MENU_CHAR_RIGHT			'>'		// Right edit character
#define MENU_TITLE_X			4		// Title position X
#define MENU_TITLE_Y			6		// Title position Y
#define MENU_ITEM_X			6		// Item label X position
#define MENU_ITEM_Y			8		// Item label X position
#define MENU_ITEM_X_GOTO		6		// Goto type item label X position
#define MENU_ITEM_ALIGN			MENU_ITEM_ALIGN_LEFT // Item label alignment
#define MENU_ITEM_ALIGN_GOTO		ENU_ITEM_ALIGN_LEFT // Goto type item label alignment
#define MENU_VALUE_X			14		// Item value X position
// Type of cursor
// - MENU_CURSOR_MODE_NONE		No cursor
// - MENU_CURSOR_MODE_CHAR		Character cursor
// - MENU_CURSOR_MODE_SPRT		Sprite cursor (WIP)
#define MENU_CURSOR_MODE		MENU_CURSOR_MODE_CHAR
#define MENU_CURSOR_OFFSET		(-2)		// Cursor X position offset

Usage

The module is data-driven, meaning that its behavior is completely determined by the data passed to it. The system is based on two structures.

Structure that represents an entry on a menu page:

// Menu item structure
typedef struct
{
	const c8* Text;		// Name of the item
	u8        Type;		// Type of the item (see <MENU_ITEM_TYPE>)
	void*     Action;	// Action associated to the item (depends on item type)
	i16       Value;	// Value associated to the item (depends on item type)
} MenuItem;

Structure that represents a complete page:

// Menu structure
typedef struct
{
	const c8* Title;		// Title of the page (NULL means no title)
	MenuItem* Items;		// List of the page's menu entries
	u8        ItemNum;		// Number of the page's menu entries
	callback  Callback;		// Function to be called when page is opened
} Menu;

A page is generally composed of a list of entries, and a menu is composed of a list of pages.

The menu system initialization function (Menu_Initialize) takes as its parameter an array of pages representing a whole menu.

Menu item types

Here's a list of possible menu entry types and how they use the 'Action' and 'Value' parameters:

MENU_ITEM_ACTION	// Execute callback function defined in 'Action' with 'Value' as a parameter
MENU_ITEM_GOTO		// Change page to the one defined in 'Value'
MENU_ITEM_INT		// Handle pointer to 8-bits integer defined in 'Action' (can be incremented or decremented)
MENU_ITEM_BOOL		// Handle pointer to boolean defined in 'Action' (can be turned ON or OFF)
MENU_ITEM_TEXT		// Handle pointer to zero-terminated string (non-interactive)
MENU_ITEM_EMPTY		// Empty entry (used to create an empty gap in the menu)
MENU_ITEM_UPDATE	// Execute callback function defined in 'Action' with 'Value' as a parameter every frame

Exemple

Here's an example of a table with 2 pages (Main and Option) each containing 5 entries.

// Entries description for the Main menu
const MenuItem g_MenuMain[] =
{
	{ "Start",               MENU_ITEM_ACTION, MenuAction_Start, 1 }, // Entry to start a game (will trigger MenuAction_Start with 'value' parameter equal to '1')
	{ "Options",             MENU_ITEM_GOTO, NULL, MENU_OPTION },     // Entry to go to Option menu page (page are defined using their index into the menu structure)
	{ "Align",               MENU_ITEM_GOTO, NULL, MENU_ALIGN },      // Entry to go to Align menu page
	{ NULL,                  MENU_ITEM_EMPTY, NULL, 0 },              // Blank entry to create a gap
	{ "Exit",                MENU_ITEM_ACTION, MenuAction_Start, 0 }, // Entry to exit the game (will trigger MenuAction_Start with 'value' parameter equal to '0')
};

// Entries description for the Option menu
MenuItem g_MenuOption[] =
{
	{ "Mode",                MENU_ITEM_ACTION, MenuAction_Screen, 0 }, // Entry to change the screen mode (will trigger MenuAction_Screen)
	{ "Integer",             MENU_ITEM_INT, &g_Integer, 0 },           // Entry to edit an integer
	{ "Boolean",             MENU_ITEM_BOOL, &g_Boolean, 0 },          // Entry to edit a boolean
	{ NULL,                  MENU_ITEM_EMPTY, NULL, 0 },               // Blank entry to create a gap
	{ "Back",                MENU_ITEM_GOTO, NULL, MENU_MAIN },        // Entry to go back to the main menu
};

// List of all menus
const Menu g_Menus[MENU_MAX] =
{
	{ "Main",    g_MenuMain,   numberof(g_MenuMain),   NULL }, // MENU_MAIN
	{ "Options", g_MenuOption, numberof(g_MenuOption), NULL }, // MENU_OPTION
};

Then, you can itnialize the menu using: Menu_Initialize(&g_Menus);

Annexe

• See also: Sample program s_menu