Troubleshooting

This page addresses common issues you may encounter when using EasyMenu and provides solutions to resolve them.

Compilation Issues

Error: Cannot Find EasyMenu.h

Symptom: The compiler reports an error like:

fatal error: EasyMenu.h: No such file or directory
// or
cannot open source file "EasyMenu.h"

Cause: The compiler's include path does not point to the Include/ folder of the library.

Solution for g++ users:

Add the include path using the -I flag when compiling:

g++ main.cpp -I path/to/EasyMenu/Include

Solution for Visual Studio users:

  1. Copy the Include/ folder into your project directory, or
  2. Add the include path in Project Properties:
    • Right-click your project → Properties
    • Navigate to: Configuration Properties → C/C++ → General → Additional Include Directories
    • Add the path to the Include folder

See the Installation page for detailed instructions.

Linker Errors

Symptom: Undefined references or unresolved external symbols at link time.

Cause: EasyMenu is header-only and does not require linking. Linker errors typically indicate:

Solution:

Console Layout and Display Issues

Menu Appears Broken or Misaligned

Important: If the menu layout appears broken, displays incorrectly, or has rendering issues, the problem is typically related to the terminal environment, not the library itself.

Tested and Verified Environments

EasyMenu has been extensively tested and verified to work correctly in the following terminal environments:

These environments render the menu interface correctly with proper highlighting, navigation, and layout.

Windows Compatibility

On Windows, EasyMenu does not rely on ANSI escape codes. Instead, it uses the native Windows Console API. This design choice ensures excellent compatibility with older Windows systems, including Windows 7, where ANSI support may be limited or disabled.

VS Code Integrated Terminal Issues

Known Issue: The Visual Studio Code integrated terminal on Windows may sometimes display incorrect layout or cursor behavior when running console UI programs.

Due to differences in how the VS Code integrated terminal handles console output on Windows, EasyMenu may not behave reliably when executed inside the VS Code terminal window.

Recommended Solution: If you experience rendering problems in VS Code, run your program in a dedicated terminal window instead:

VS Code Terminal on Linux

Note: The VS Code integrated terminal works correctly when running inside a Linux environment. The issue is specific to Windows. On Linux and macOS, the VS Code terminal has been tested and functions properly with EasyMenu.

How to Run in a Dedicated Terminal

Windows:

  1. Build your program in Visual Studio or with g++
  2. Open Command Prompt, PowerShell, or Windows Terminal
  3. Navigate to your executable's directory
  4. Run the program directly

Linux/macOS:

  1. Compile your program with g++
  2. Open your system terminal
  3. Navigate to your executable's directory
  4. Run the program with ./yourprogram

Navigation Issues

Menu Returns 0 Immediately

Symptom: Calling RunMenu() returns 0 without displaying the menu.

Cause: The menu is empty or contains no navigable items.

Solution:

EasyMenu menu("Test");
menu.AddItem("Option 1", true, true); // Active and visible

unsigned int choice = menu.RunMenu(); // Will work correctly

Cannot Select Certain Items

Symptom: Some items are visible but cannot be selected when navigating.

Cause: The items are inactive (the second parameter in AddItem() is false).

Solution:

Make items active if you want them to be selectable:

// This item is visible but not selectable
menu.AddItem("Disabled Option", false, true);

// Make it active
menu.SetActivity(1, true); // Item number 1, make active

Off-by-One Selection Issues

Symptom: The selection number doesn't match your expectations.

Cause: Remember that RunMenu() returns a 1-based index, not 0-based.

Solution:

If you're storing items in a 0-based container (like std::vector), adjust the index:

std::vector<std::string> actions = {"Action1", "Action2", "Action3"};

EasyMenu menu("Choose Action");
for (const auto& action : actions) {
    menu.AddItem(action);
}

unsigned int choice = menu.RunMenu();

if (choice > 0 && choice <= actions.size()) {
    // Convert from 1-based to 0-based
    std::string selected = actions[choice - 1];
    std::cout << "Selected: " << selected << std::endl;
}

Runtime Issues

Screen Not Clearing Properly

Symptom: Previous menu content remains visible when the menu refreshes.

Cause: This can happen in certain terminal emulators or configurations.

Solution:

Cursor Remains Visible

Symptom: The text cursor is visible while navigating the menu.

Cause: The terminal may not support cursor visibility control, or the program terminated unexpectedly without restoring the cursor.

Solution:

Customization Issues

Custom Header or Footer Not Appearing

Symptom: You set a custom header or footer, but it doesn't display.

Cause: You need to include the EasyMenuComponents.h header and use the correct classes.

Solution:

#include <EasyMenu.h>
#include <EasyMenuComponents.h>

EasyMenu menu("Test");

// Create custom header
EasyMenuComponents::clsEasyMenuHeader header;
header.AddLine("===================");
header.AddLine("Custom Header");
header.AddLine("===================");

menu.SetHeader(header);

menu.AddItem("Option 1");
menu.RunMenu();

Getting Help

If you encounter an issue not covered here:

  1. Verify you're using a supported terminal environment
  2. Check the installation instructions to ensure proper setup
  3. Review the examples to see working code
  4. Consult the API reference for method details

When reporting issues, please include: