Core Concepts

EasyMenu is built around a small set of intuitive concepts that work together to create interactive console menus. Understanding these concepts will help you use the library effectively.

Menu

A menu is the main container that holds all the components of your interactive interface. It consists of:

The EasyMenu class is the primary entry point for creating and managing menus.

// Create a menu with a label
EasyMenu menu("Main Menu");

// The menu now has a default header showing "Main Menu"
// and a default footer

Menu Items

A menu item is an individual selectable option within the menu. Items have several properties:

Label

The text displayed for the item. This is what the user sees.

menu.AddItem("Save Game");

Visibility

Controls whether the item is shown to the user. Hidden items are completely invisible.

// Third parameter is visibility
menu.AddItem("Debug Options", true, false); // Hidden item

Activity

Controls whether the item can be selected. Inactive items are visible but cannot be chosen (typically displayed in a different style).

// Second parameter is activity, third is visibility
menu.AddItem("Multiplayer", false, true); // Visible but inactive

Navigability

An item is navigable if it is both visible and active. Only navigable items can be highlighted and selected by the user.

Item Indexing

Items in a menu are numbered starting from 1 (one-based indexing). This makes the API more intuitive for users:

menu.AddItem("First Item");   // Item number 1
menu.AddItem("Second Item");  // Item number 2
menu.AddItem("Third Item");   // Item number 3

unsigned int choice = menu.RunMenu();
// Returns 1 for first item, 2 for second item, etc.
Note: When RunMenu() returns 0, it means the menu is empty or contains no navigable items.

Headers and Footers

Headers and footers are optional visual blocks that appear above and below the menu items.

Default Header and Footer

When you create a menu with a label, EasyMenu automatically generates a default header displaying the label and a simple footer:

EasyMenu menu("Settings");
// Automatically includes:
// - Header with "Settings" label
// - Default footer

Custom Headers and Footers

You can create custom headers and footers using the components from the EasyMenuComponents namespace:

#include <EasyMenuComponents.h>

// Create custom header
EasyMenuComponents::clsEasyMenuHeader customHeader;
customHeader.AddLine("================================");
customHeader.AddLine("    My Custom Application Menu");
customHeader.AddLine("         Version 1.0");
customHeader.AddLine("================================");

menu.SetHeader(customHeader);

Empty Menu

If you create a menu without a label, it will not have a default header or footer:

EasyMenu menu; // Empty menu, no default header/footer
menu.AddItem("Item 1");
menu.AddItem("Item 2");

Menu Navigation

When a menu is displayed, users navigate using keyboard input:

Key Action
Up Arrow Move to the previous navigable item
Down Arrow Move to the next navigable item
Enter Select the currently highlighted item

Navigation automatically skips over items that are inactive or hidden. The highlighted item wraps around when reaching the top or bottom of the menu.

Rendering and Pagination

EasyMenu automatically adapts the menu display to fit the terminal window size.

Automatic Terminal Detection

The library detects the current terminal dimensions and adjusts the display accordingly.

Pagination

If the menu has more items than can fit on the screen, EasyMenu automatically paginates the display. Only the items that fit in the current terminal are shown at once, and the view scrolls as the user navigates.

Adaptive Sizing

The menu recalculates the available space based on:

This ensures the menu always displays correctly regardless of terminal size.

Platform Abstraction

EasyMenu works consistently across different operating systems through an internal platform abstraction layer. You don't need to write platform-specific code.

Supported Platforms

The same code works on all platforms without modification.

Menu Lifecycle

A typical menu follows this lifecycle:

  1. Creation - Create an EasyMenu object
  2. Configuration - Add items, customize header/footer if needed
  3. Display - Call RunMenu() to show the menu
  4. Navigation - User navigates and selects an item
  5. Return - RunMenu() returns the selected item number
  6. Action - Your code handles the selection
// 1. Creation
EasyMenu menu("Game Menu");

// 2. Configuration
menu.AddItem("Play");
menu.AddItem("Options");
menu.AddItem("Quit");

// 3-5. Display, Navigation, Return
unsigned int choice = menu.RunMenu();

// 6. Action
switch (choice) {
    case 1: startGame(); break;
    case 2: showOptions(); break;
    case 3: quit(); break;
}

Design Philosophy

EasyMenu is designed with these principles in mind:

Simplicity

The API is intentionally minimal. Common tasks require just a few method calls.

Header-Only

No separate compilation or linking required. Just include the headers and use the library.

Zero Dependencies

EasyMenu depends only on the standard C++ library. No external dependencies to manage.

Cross-Platform

Write once, run anywhere. The same code works on Windows, Linux, and macOS.

Intuitive

One-based indexing and clear method names make the library easy to understand and use.

Next Steps

Now that you understand the core concepts, you can: