API Overview

This section provides comprehensive documentation for the EasyMenu public API. The library exposes a clean, minimal interface designed for ease of use while providing powerful menu functionality.

Public Headers

EasyMenu provides two main headers for public use:

EasyMenu.h

The primary header containing the EasyMenu class. This is the main entry point for the library and is required for all applications using EasyMenu.

#include <EasyMenu.h>

This header provides:

• The EasyMenu class for creating and managing menus
• All core functionality for adding, updating, and removing items
• Methods for running interactive menu sessions

EasyMenuComponents.h

An optional header that exposes visual components for menu customization. Include this header only if you need to create custom headers or footers.

#include <EasyMenuComponents.h>

This header provides access to:

• EasyMenuComponents::clsEasyMenuHeader - For creating custom menu headers
• EasyMenuComponents::clsEasyMenuFooter - For creating custom menu footers

Primary Classes

See the Classes Reference for detailed documentation of each class.

Typical Usage Pattern

Most applications follow this pattern when using EasyMenu:

#include <iostream>
#include <EasyMenu.h>

int main() {
    // 1. Create a menu
    EasyMenu menu("Application Menu");

    // 2. Add items
    menu.AddItem("Item 1");
    menu.AddItem("Item 2");
    menu.AddItem("Exit");

    // 3. Display and get selection
    unsigned int choice = menu.RunMenu();

    // 4. Handle the selection
    switch (choice) {
        case 1:
            // Handle item 1
            break;
        case 2:
            // Handle item 2
            break;
        case 3:
            // Handle exit
            break;
    }

    return 0;
}

Key Design Principles

Header-Only Library

EasyMenu is entirely header-based. No compilation or linking of library files is required. Simply include the headers and use the classes.

One-Based Indexing

Menu items are numbered starting from 1, not 0. This makes the API more intuitive:

• AddItem() adds items sequentially (1, 2, 3, ...)
• RunMenu() returns the selected item number (1-based)
• UpdateItem(), RemoveItem(), etc., use 1-based numbering
• A return value of 0 indicates no selection or an empty menu

Platform Independence

The API is identical across all supported platforms. Write your code once and it works on Windows, Linux, and macOS without modification.

Minimal Dependencies

EasyMenu depends only on the C++ standard library. No external dependencies are required.

Error Handling

EasyMenu uses return values to indicate success or failure for operations that might fail:

Boolean Return Values

Methods like UpdateItem(), RemoveItem(), SetVisibility(), and SetActivity() return bool:

• true - Operation succeeded
• false - Operation failed (typically because the item number is out of range)

if (menu.UpdateItem(5, "New Label")) {
    // Success
} else {
    // Failed - item 5 doesn't exist
}

Special Return Values

RunMenu() returns 0 when:

• The menu is empty (no items have been added)
• No items are navigable (all items are either hidden or inactive)

unsigned int choice = menu.RunMenu();

if (choice == 0) {
    std::cout << "Menu is empty or not navigable" << std::endl;
} else {
    // Handle selection
}

API Categories

Menu Creation and Configuration

• Constructors for creating menus
• Methods for setting headers and footers
• Methods for clearing menu components

Item Management

• Adding items to the menu
• Updating existing items
• Removing items
• Controlling item visibility and activity

Menu Execution

• Running the menu and capturing user selection
• Controlling the starting position

Menu Inspection

• Querying the number of items
• Checking if the menu is empty
• Retrieving header and footer components

Customization Components

• Creating custom headers with multiple lines
• Creating custom footers with multiple lines

Thread Safety

EasyMenu is not thread-safe. If you need to use menus from multiple threads, ensure proper synchronization (mutexes, locks, etc.) in your application code.

Next Steps

• View the complete class reference for detailed method documentation
• Explore practical examples showing common patterns
• Follow the quick start guide to create your first menu