menu.h

/**
 * @file menu.h
 * @brief Menu system library for Raspberry Pi Pico
 *
 * This library provides a hierarchical menu system for displays.
 *
 * @author Turi Scandurra
 */

#ifndef RP2040_MENU_H
#define RP2040_MENU_H

#include "pico/stdlib.h"
#include <stdbool.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @def MENU_MAX_ITEMS
 * @brief Maximum number of items per menu
 */
#define MENU_MAX_ITEMS 16

/**
 * @def MENU_MAX_DEPTH
 * @brief Maximum menu nesting depth
 */
#define MENU_MAX_DEPTH 8

/**
 * @def MENU_MAX_STRING_OPTIONS
 * @brief Maximum number of string options for string value items
 */
#define MENU_MAX_STRING_OPTIONS 16

/**
 * @def MENU_FORMAT_BUFFER_SIZE
 * @brief Buffer size for formatted text strings
 */
#define MENU_FORMAT_BUFFER_SIZE 64

/**
 * @typedef menu_callback_t
 * @brief Callback function type for menu actions
 */
typedef void (*menu_callback_t)(void);

/**
 * @typedef menu_value_change_callback_t
 * @brief Callback function type for value changes
 */
typedef void (*menu_value_change_callback_t)(void);

/**
 * @enum menu_item_type_t
 * @brief Menu item type enumeration
 */
typedef enum {
    MENU_ITEM_ACTION,        /**< Simple action item */
    MENU_ITEM_SUBMENU,       /**< Submenu item */
    MENU_ITEM_VALUE_UINT8,   /**< Unsigned 8-bit integer value */
    MENU_ITEM_VALUE_INT16,   /**< Signed 16-bit integer value */
    MENU_ITEM_VALUE_STRING,  /**< String value with options */
    MENU_ITEM_RADIO,         /**< Radio button (boolean) */
    MENU_ITEM_AB             /**< A/B toggle (boolean) */
} menu_item_type_t;

/**
 * @struct menu_item_t
 * @brief Represents a single menu item
 */
typedef struct menu_item_t {
    /**
     * @var label
     * @brief Display label for the menu item
     */
    const char *label;
    /**
     * @var callback
     * @brief Callback function to execute when item is selected (NULL for submenu)
     */
    menu_callback_t callback;
    /**
     * @var submenu
     * @brief Pointer to submenu (NULL if this is an action item)
     */
    struct menu_t *submenu;
    /**
     * @var type
     * @brief Type of menu item
     */
    menu_item_type_t type;
    /**
     * @var value
     * @brief Union storing different value types
     */
    union {
        uint8_t value_uint8;     /**< Unsigned 8-bit integer value */
        int16_t value_int16;     /**< Signed 16-bit integer value */
        const char *value_string;/**< String value (pointer to option) */
        bool value_bool;         /**< Boolean value for radio/ab */
    } value;
    /**
     * @var min_value
     * @brief Minimum value for numeric items (union)
     */
    union {
        uint8_t min_uint8;
        int16_t min_int16;
    } min_value;
    /**
     * @var max_value
     * @brief Maximum value for numeric items (union)
     */
    union {
        uint8_t max_uint8;
        int16_t max_int16;
    } max_value;
    /**
     * @var step
     * @brief Step value for numeric items (union)
     */
    union {
        uint8_t step_uint8;
        int16_t step_int16;
    } step;
    /**
     * @var string_options
     * @brief Array of string options for string value items
     */
    const char *string_options[MENU_MAX_STRING_OPTIONS];
    /**
     * @var string_option_count
     * @brief Number of string options
     */
    uint8_t string_option_count;
    /**
     * @var string_option_index
     * @brief Current selected string option index
     */
    uint8_t string_option_index;
    /**
     * @var value_change_callback
     * @brief Callback function called when value changes
     */
    menu_value_change_callback_t value_change_callback;
} menu_item_t;

/**
 * @struct menu_t
 * @brief Represents a menu with its items
 */
typedef struct menu_t {
    /**
     * @var title
     * @brief Menu title
     */
    const char *title;
    /**
     * @var items
     * @brief Array of menu items
     */
    menu_item_t items[MENU_MAX_ITEMS];
    /**
     * @var item_count
     * @brief Number of items in this menu
     */
    uint8_t item_count;
    /**
     * @var parent
     * @brief Pointer to parent menu (NULL for root menu)
     */
    struct menu_t *parent;
    /**
     * @var selected_index
     * @brief Last selected item index in this menu
     */
    uint8_t selected_index;
    /**
     * @var first_visible_index
     * @brief First visible item index (for scrolling)
     */
    uint8_t first_visible_index;
} menu_t;

/**
 * @struct menu_system_t
 * @brief Represents the menu system state
 */
typedef struct menu_system_t {
    /**
     * @var root_menu
     * @brief Root menu of the system
     */
    menu_t *root_menu;
    /**
     * @var current_menu
     * @brief Currently displayed menu
     */
    menu_t *current_menu;
    /**
     * @var selected_index
     * @brief Currently selected item index
     */
    uint8_t selected_index;
    /**
     * @var first_visible_index
     * @brief First visible item index (for scrolling)
     */
    uint8_t first_visible_index;
    /**
     * @var visible_count
     * @brief Number of visible items on display
     */
    uint8_t visible_count;
    /**
     * @var draw_callback
     * @brief Callback function to draw menu on display
     */
    void (*draw_callback)(struct menu_system_t *menu_system);
} menu_system_t;

/**
 * @brief Create a new menu
 * @param title Menu title
 * @return Pointer to menu_t structure, or NULL on failure
 */
menu_t *menu_create(const char *title);

/**
 * @brief Add an action item to a menu
 * @param menu Pointer to menu_t structure
 * @param label Item label
 * @param callback Callback function to execute when selected
 * @return 0 on success, -1 on failure
 */
int menu_add_action(menu_t *menu, const char *label, menu_callback_t callback);

/**
 * @brief Add a submenu item to a menu
 * @param parent_menu Pointer to parent menu_t structure
 * @param label Item label
 * @param submenu Pointer to submenu menu_t structure
 * @return 0 on success, -1 on failure
 */
int menu_add_submenu(menu_t *parent_menu, const char *label, menu_t *submenu);

/**
 * @brief Initialize menu system
 * @param menu_system Pointer to menu_system_t structure
 * @param root_menu Root menu
 * @param visible_count Number of visible items on display
 * @param draw_callback Callback function to draw menu
 */
void menu_system_init(menu_system_t *menu_system, menu_t *root_menu, 
                     uint8_t visible_count, void (*draw_callback)(menu_system_t *));

/**
 * @brief Navigate up in menu hierarchy
 * @param menu_system Pointer to menu_system_t structure
 */
void menu_system_up(menu_system_t *menu_system);

/**
 * @brief Navigate down in menu hierarchy
 * @param menu_system Pointer to menu_system_t structure
 */
void menu_system_down(menu_system_t *menu_system);

/**
 * @brief Select current menu item
 * @param menu_system Pointer to menu_system_t structure
 */
void menu_system_select(menu_system_t *menu_system);

/**
 * @brief Go back to parent menu
 * @param menu_system Pointer to menu_system_t structure
 */
void menu_system_back(menu_system_t *menu_system);

/**
 * @brief Get currently selected item
 * @param menu_system Pointer to menu_system_t structure
 * @return Pointer to menu_item_t, or NULL if none selected
 */
menu_item_t *menu_system_get_selected(menu_system_t *menu_system);

/**
 * @brief Refresh menu display
 * @param menu_system Pointer to menu_system_t structure
 */
void menu_system_refresh(menu_system_t *menu_system);

/**
 * @brief Destroy menu and free resources
 * @param menu Pointer to menu_t structure
 */
void menu_destroy(menu_t *menu);

/**
 * @brief Add a uint8_t value item to a menu
 * @param menu Pointer to menu_t structure
 * @param label Item label
 * @param initial_value Initial value
 * @param min_value Minimum value
 * @param max_value Maximum value
 * @param step Step size for increment/decrement
 * @param callback Optional callback function called when value changes
 * @return 0 on success, -1 on failure
 */
int menu_add_value_uint8(menu_t *menu, const char *label, uint8_t initial_value,
                         uint8_t min_value, uint8_t max_value, uint8_t step,
                         menu_value_change_callback_t callback);

/**
 * @brief Add an int16_t value item to a menu
 * @param menu Pointer to menu_t structure
 * @param label Item label
 * @param initial_value Initial value
 * @param min_value Minimum value
 * @param max_value Maximum value
 * @param step Step size for increment/decrement
 * @param callback Optional callback function called when value changes
 * @return 0 on success, -1 on failure
 */
int menu_add_value_int16(menu_t *menu, const char *label, int16_t initial_value,
                         int16_t min_value, int16_t max_value, int16_t step,
                         menu_value_change_callback_t callback);

/**
 * @brief Add a string value item to a menu
 * @param menu Pointer to menu_t structure
 * @param label Item label
 * @param options Array of string options
 * @param option_count Number of options
 * @param initial_index Initial selected option index
 * @param callback Optional callback function called when value changes
 * @return 0 on success, -1 on failure
 */
int menu_add_value_string(menu_t *menu, const char *label, const char *options[],
                          uint8_t option_count, uint8_t initial_index,
                          menu_value_change_callback_t callback);

/**
 * @brief Add a radio button item to a menu
 * @param menu Pointer to menu_t structure
 * @param label Item label
 * @param initial_value Initial boolean value
 * @param callback Optional callback function called when value changes
 * @return 0 on success, -1 on failure
 */
int menu_add_radio(menu_t *menu, const char *label, bool initial_value,
                   menu_value_change_callback_t callback);

/**
 * @brief Add an A/B toggle item to a menu
 * @param menu Pointer to menu_t structure
 * @param label Item label
 * @param option_a Label for option A
 * @param option_b Label for option B
 * @param initial_value Initial boolean value (false = A, true = B)
 * @param callback Optional callback function called when value changes
 * @return 0 on success, -1 on failure
 */
int menu_add_ab(menu_t *menu, const char *label, const char *option_a,
                const char *option_b, bool initial_value,
                menu_value_change_callback_t callback);

/**
 * @brief Format a menu item as a text string
 * @param item Pointer to menu_item_t structure
 * @param buffer Buffer to store formatted string
 * @param buffer_size Size of buffer
 * @param selected Whether the item is currently selected
 * @return Number of characters written (excluding null terminator)
 */
int menu_item_format_text(menu_item_t *item, char *buffer, size_t buffer_size, bool selected);

/**
 * @brief Get display string for a menu item
 * @param item Pointer to menu_item_t structure
 * @param buffer Buffer to store display string
 * @param buffer_size Size of buffer
 * @return Number of characters written (excluding null terminator)
 */
int menu_item_get_display_string(menu_item_t *item, char *buffer, size_t buffer_size);

/**
 * @brief Increment a menu item's value
 * @param item Pointer to menu_item_t structure
 * @return 0 on success, -1 on failure or value at maximum
 */
int menu_item_increment(menu_item_t *item);

/**
 * @brief Decrement a menu item's value
 * @param item Pointer to menu_item_t structure
 * @return 0 on success, -1 on failure or value at minimum
 */
int menu_item_decrement(menu_item_t *item);

/**
 * @brief Toggle a boolean/radio/ab menu item's value
 * @param item Pointer to menu_item_t structure
 * @return 0 on success, -1 on failure (not a toggleable item)
 */
int menu_item_toggle(menu_item_t *item);

/**
 * @brief Set a menu item's value directly
 * @param item Pointer to menu_item_t structure
 * @param value_ptr Pointer to value (type depends on item type)
 * @return 0 on success, -1 on failure or invalid value
 */
int menu_item_set_value(menu_item_t *item, const void *value_ptr);

/**
 * @brief Get a menu item's value
 * @param item Pointer to menu_item_t structure
 * @return Pointer to value (type depends on item type), or NULL on failure
 */
const void *menu_item_get_value(menu_item_t *item);

/**
 * @brief Enter edit mode for current menu item (increment/decrement)
 * @param menu_system Pointer to menu_system_t structure
 * @param increment True to increment, false to decrement
 */
void menu_system_edit(menu_system_t *menu_system, bool increment);

#ifdef __cplusplus
}
#endif

#endif