Menu Public API

Public functions to interact with the menu subsystem. More...

Collaboration diagram for Menu Public API:

Functions
ERR_te	menu_init_subsys (void)
	Initializes the menu subsystem.
ERR_te	menu_deinit_subsys (void)
	Deinitializes the menu subsystem.
ERR_te	menu_start_subsys (void)
	Starts the menu subsystem.
ERR_te	menu_stop_subsys (void)
	Stops the menu subsystem.
ERR_te	menu_init_handle (MENU_CFG_ts *menu_cfg, MENU_HANDLE_ts **menu_handle_o)
	Initializes and registers a menu handle.
ERR_te	menu_run_handle (MENU_HANDLE_ts *menu_handle)
	Renders a single menu to the display.
ERR_te	menu_run_handle_all (void)
	Renders all registered menus to the display.
ERR_te	menu_get_selected_option (MENU_HANDLE_ts const *menu_handle, char *selected_option_o)
	Retrieves the string of the currently highlighted option.
ERR_te	menu_scroll (MENU_HANDLE_ts *menu_handle, VERTICAL_DIR_te vertical_dir)
	Moves the menu selection cursor by one step in the given direction.
ERR_te	menu_get_prev_menu (MENU_HANDLE_ts *menu_handle, MENU_HANDLE_ts **prev_menu_handle_o)
	Pops and returns the previous menu from the navigation history stack.
ERR_te	menu_set_prev_menu (MENU_HANDLE_ts *menu_handle, MENU_HANDLE_ts *prev_menu_handle)
	Pushes a menu onto the navigation history stack of another menu.

Detailed Description

Public functions to interact with the menu subsystem.

Function Documentation

menu_init_subsys()

ERR_te menu_init_subsys

(

void

)

Initializes the menu subsystem.

Resets the internal state, initializes the logging dependency, and registers the CLI commands.

Must be called before any other menu API function.

Returns

• ERR_OK on success
• ERR_MODULE_ALREADY_INITIALIZED if the subsystem is already initialized
• Propagated error from cmd_register on failure

Note

Should only be called once during system startup.

See also

menu_init_subsys

Definition at line 159 of file menu.c.

                              {
    ERR_te err = 0;
 
    if(internal_state.initialized) {
        return ERR_MODULE_ALREADY_INITIALIZED;
    }
 
    internal_state = (struct internal_state_s){ 0 };
 
    internal_state.log_level = LOG_LEVEL_INFO;
    internal_state.subsys = MODULES_MENU;
    internal_state.initialized = true;
    internal_state.started = false;
 
    init_log();
 
    err = cmd_register(&menu_cmd_client_info);
    if(err != ERR_OK) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "menu_init_subsys: cmd_register error"
        );
 
        return err;
    }
    LOG_INFO(
        internal_state.subsys,
        internal_state.log_level,
        "menu_init_subsys: subsys initialized"
    );
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

menu_deinit_subsys()

ERR_te menu_deinit_subsys

(

void

)

Deinitializes the menu subsystem.

Resets the internal state to zero and deregisters the CLI commands. The subsystem must be stopped before calling this function.

Returns

• ERR_OK on success
• ERR_DEINITIALIZATION_FAILURE if the subsystem is not initialized or still running

See also

menu_deinit_subsys

Definition at line 195 of file menu.c.

                                {
    if(internal_state.initialized && !internal_state.started) {
        internal_state = (struct internal_state_s){ 0 };
 
        cmd_deregister(&menu_cmd_client_info);
    }
    else {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "menu_deinit_subsys: subsys is not initialized or not stopped"
        );
 
        return ERR_DEINITIALIZATION_FAILURE;
    }
    LOG_INFO(
        internal_state.subsys,
        internal_state.log_level,
        "menu_deinit_subsys: subsys deinitialized"
    );
 
    return ERR_OK;
}

Here is the call graph for this function:

menu_start_subsys()

ERR_te menu_start_subsys

(

void

)

Starts the menu subsystem.

Returns

• ERR_OK on success
• ERR_UNKNOWN if the subsystem is not initialized or already started

See also

menu_start_subsys

Definition at line 220 of file menu.c.

                               {
    if(internal_state.initialized && !internal_state.started) {
        internal_state.started = true;
 
        LOG_INFO(
            internal_state.subsys,
            internal_state.log_level,
            "menu_start_subsys: subsys started"
        );
    }
    else {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "menu_start_subsys: subsys not initialized or already started"
        );
 
        return ERR_UNKNOWN;
    }
 
    return ERR_OK;
}

Here is the caller graph for this function:

menu_stop_subsys()

ERR_te menu_stop_subsys

(

void

)

Stops the menu subsystem.

Returns

• ERR_OK on success
• ERR_UNKNOWN if the subsystem is not initialized or already stopped

See also

menu_stop_subsys

Definition at line 244 of file menu.c.

                              {
    if(internal_state.initialized && internal_state.started) {
        internal_state.started = false;
 
        LOG_INFO(
            internal_state.subsys,
            internal_state.log_level,
            "menu_stop_subsys: subsys stopped"
        );
    }
    else {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "menu_stop_subsys: subsys not initialized or already already stopped"
        );
 
        return ERR_UNKNOWN;
    }
 
    return ERR_OK;
}

menu_init_handle()

ERR_te menu_init_handle	(	MENU_CFG_ts *	menu_cfg,
		MENU_HANDLE_ts **	menu_handle_o )

Initializes and registers a menu handle.

Counts the number of options in menu_cfg by scanning for the first entry whose first character is ‘’\0'`, copies all configuration into the internal pool, and sets up initial scroll state.

For MENU_TYPE_DATA_VIEW menus, the internal option count is doubled to account for interleaved label and value rows.

Parameters

[in]	menu_cfg	Pointer to the menu configuration structure.
[out]	menu_handle_o	Pointer to a handle pointer that will be set to the allocated menu instance.

Returns

• ERR_OK on success
• ERR_NOT_ENOUGH_SPACE if the maximum number of handles is reached or the option count exceeds CONFIG_MENU_MAX_OPTIONS
• ERR_INVALID_ARGUMENT if no options are found in menu_cfg

See also

menu_init_handle

Definition at line 268 of file menu.c.

                                                                               {
    if(internal_state.menu_num == CONFIG_MENU_MAX_OBJECTS)
        return ERR_NOT_ENOUGH_SPACE;
 
    // Count number of options in the input data
    uint8_t options_count = 0;
    while(menu_cfg->options[options_count][0] != '\0')
        options_count++;
 
    if(options_count == 0)
        return ERR_INVALID_ARGUMENT;
    else if(options_count > CONFIG_MENU_MAX_OPTIONS)
        return ERR_NOT_ENOUGH_SPACE;
 
    for(uint32_t i = 0; i < CONFIG_MENU_MAX_OBJECTS; i++) {
        if(internal_state.menus[i].in_use == false) {
            // Copy input data (menu title) to internal state
            txt_cpy(
                internal_state.menus[i].title,
                menu_cfg->title,
                get_str_len(menu_cfg->title)
            );
 
            // Copy input data (menu name) to internal state
            txt_cpy(
                internal_state.menus[i].name,
                menu_cfg->name,
                get_str_len(menu_cfg->name)
            );
 
            // Copy input data (menu options) to internal state
            for(uint8_t j = 0; j < options_count; j++) {
                txt_cpy(
                    internal_state.menus[i].options[j],
                    menu_cfg->options[j],
                    get_str_len(menu_cfg->options[j])
                );
            }
 
            // For dataview mode, options count covers both the labels and their live values
            if(menu_cfg->type == MENU_TYPE_DATA_VIEW) {
                options_count *= 2;
            }
 
            if(options_count > 7) {
                internal_state.menus[i].last_visible_option = 6;
            }
            else {
                internal_state.menus[i].last_visible_option = options_count - 1;
            }
 
            internal_state.menus[i].line_to_highlight = 1;
            internal_state.menus[i].selected_option = 0;
            internal_state.menus[i].prev_selected_option = 0;
            internal_state.menus[i].get_value_fn = menu_cfg->get_value_fn;
            internal_state.menus[i].type = menu_cfg->type;
            internal_state.menus[i].first_visible_option = 0;
            internal_state.menus[i].options_count = options_count;
            internal_state.menus[i].in_use = true;
 
            *menu_handle_o = &internal_state.menus[i];
 
            internal_state.menu_num++;
 
            break;
        }
    }
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

menu_run_handle()

ERR_te menu_run_handle

(

MENU_HANDLE_ts *

menu_handle

)

Renders a single menu to the display.

Clears the display area, dispatches to the appropriate internal renderer based on MENU_TYPE_ts, and triggers a display update.

Parameters

[in,out]

menu_handle

Pointer to the menu handle to render.

Returns

• ERR_OK always

See also

menu_run_handle

Definition at line 340 of file menu.c.

                                                    {
    ssd1309_clear_rect(1, 1, 128, 64, false);
 
    if(menu_handle->type == MENU_TYPE_SELECTABLE) {
        menu_selectable_run(menu_handle);
    }
    else if(menu_handle->type == MENU_TYPE_DATA_VIEW) {
        menu_dataview_run(menu_handle);
    }
 
    ssd1309_update(false);
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

menu_run_handle_all()

ERR_te menu_run_handle_all

(

void

)

Renders all registered menus to the display.

Iterates over all active handles and calls menu_run_handle on each.

Returns

• ERR_OK always

See also

menu_run_handle_all

Definition at line 356 of file menu.c.

                                 {
    for(uint32_t i = 0; i < CONFIG_MENU_MAX_OBJECTS; i++) {
        if(internal_state.menus[i].in_use == true) {
            menu_run_handle(&internal_state.menus[i]);
        }
    }
 
    return ERR_OK;
}

Here is the call graph for this function:

menu_get_selected_option()

ERR_te menu_get_selected_option	(	MENU_HANDLE_ts const *	menu_handle,
		char *	selected_option_o )

Retrieves the string of the currently highlighted option.

Only valid for MENU_TYPE_SELECTABLE menus. Returns ERR_INVALID_ARGUMENT for MENU_TYPE_DATA_VIEW menus.

Parameters

[in]	menu_handle	Pointer to the menu handle to query.
[out]	selected_option_o	Pointer to a buffer that will receive the selected option string (null-terminated). Must be at least SSD1309_MAX_CHARS_IN_LINE bytes.

Returns

• ERR_OK on success
• ERR_INVALID_ARGUMENT if the menu type is MENU_TYPE_DATA_VIEW
• ERR_DATA_COPY_FAILURE if the string copy fails

See also

menu_get_selected_option

Definition at line 367 of file menu.c.

                                                                                            {
    ERR_te err;
 
    if(menu_handle->type == MENU_TYPE_DATA_VIEW) {
        return ERR_INVALID_ARGUMENT;
    }
 
    err = str_cpy(
        selected_option_o,
        menu_handle->options[menu_handle->selected_option],
        get_str_len(menu_handle->options[menu_handle->selected_option]) + 1
    );
    if(err != ERR_OK) {
        return ERR_DATA_COPY_FAILURE;
    }
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

menu_scroll()

ERR_te menu_scroll	(	MENU_HANDLE_ts *	menu_handle,
		VERTICAL_DIR_te	vertical_dir )

Moves the menu selection cursor by one step in the given direction.

Increments or decrements the internal selection index. The actual clamping to valid bounds and display update happen on the next call to menu_run_handle.

Parameters

[in,out]	menu_handle	Pointer to the menu handle to scroll.
[in]	vertical_dir	UP to move the selection up, DOWN to move it down.

Returns

• ERR_OK always

See also

menu_scroll

Definition at line 387 of file menu.c.

                                                                              {
    switch(vertical_dir) {
        case DOWN:
            menu_handle->selected_option += 1;
            break;
 
        case UP:
            menu_handle->selected_option -= 1;
            break;
    }
 
    return ERR_OK;
}

Here is the caller graph for this function:

menu_get_prev_menu()

ERR_te menu_get_prev_menu	(	MENU_HANDLE_ts *	menu_handle,
		MENU_HANDLE_ts **	prev_menu_handle_o )

Pops and returns the previous menu from the navigation history stack.

Used to implement back-navigation. The popped handle is removed from the stack.

Parameters

[in,out]	menu_handle	Pointer to the current menu handle.
[out]	prev_menu_handle_o	Pointer to a handle pointer that will be set to the previous menu.

Returns

• ERR_OK on success
• ERR_INVALID_ARGUMENT if the navigation history stack is empty

See also

menu_get_prev_menu

Definition at line 402 of file menu.c.

                                                                                            {
    if(menu_handle->prev_menu_count == 0)
        return ERR_INVALID_ARGUMENT;
 
    *prev_menu_handle_o = menu_handle->prev_menu[--menu_handle->prev_menu_count];
 
    return ERR_OK;
}

Here is the caller graph for this function:

menu_set_prev_menu()

ERR_te menu_set_prev_menu	(	MENU_HANDLE_ts *	menu_handle,
		MENU_HANDLE_ts *	prev_menu_handle )

Pushes a menu onto the navigation history stack of another menu.

Used to record the menu to return to when the user navigates back. Call this before transitioning to a new menu.

Parameters

[in,out]	menu_handle	Pointer to the current menu handle whose history stack will be updated.
[in]	prev_menu_handle	Pointer to the menu handle to push onto the history stack.

Returns

• ERR_OK on success
• ERR_NOT_ENOUGH_SPACE if the history stack is full

See also

menu_set_prev_menu

Definition at line 412 of file menu.c.

                                                                                         {
    if(menu_handle->prev_menu_count == CONFIG_MENU_MAX_BUF_SIZE)
        return ERR_NOT_ENOUGH_SPACE;
 
    menu_handle->prev_menu[menu_handle->prev_menu_count++] = prev_menu_handle;
 
    return ERR_OK;
}

Here is the caller graph for this function: