Plugin API

Plugin API

Copy include/MenuHelper/MenuHelper.h into your project. The comments in the header describe every function and field. examples/basic/main.cpp uses every feature.

Load the API once all plugins have loaded (F4SE kPostLoad or later):

#include <Windows.h>
#include "MenuHelper/MenuHelper.h"

void OnShowMarkers(MenuHelper_ItemId, double value, void*)
{
    // value is 0 or 1
}

void Register()
{
    const MenuHelper_API* api = MenuHelper_Load();  // NULL when Menu Helper is not installed
    if (!api) {
        return;
    }

    MenuHelper_MenuDesc menuDesc{ sizeof(menuDesc) };
    menuDesc.modName = "MyMod";
    const MenuHelper_MenuId menu = api->CreateMenu(&menuDesc);

    MenuHelper_ItemDesc item{ sizeof(item) };
    item.type = MENUHELPER_ITEM_CHECKBOX;
    item.label = "SHOW MARKERS";
    item.description = "Shows map markers.";
    item.saveKey = "bShowMarkers";
    item.onChange = OnShowMarkers;
    const MenuHelper_ItemId checkbox = api->AddItem(menu, &item);
    OnShowMarkers(checkbox, api->GetItemValue(checkbox), nullptr);  // apply the saved value

    MenuHelper_EntryDesc entry{ sizeof(entry) };
    entry.modName = "MyMod";
    entry.label = "MY MOD";
    entry.menus = MENUHELPER_MENU_ALL;
    entry.insertBefore = MENUHELPER_VANILLA_QUIT;
    entry.submenu = menu;
    api->AddEntry(&entry);
}

Functions

Function	Use
AddEntry, RemoveEntry, SetEntryLabel, SetEntryEnabled	Entries in the main menu, pause menu, or both.
CreateMenu, DestroyMenu	Menus of items or of text pages.
AddItem, RemoveItem	Items in a menu.
SetItemLabel, SetItemDescription, SetItemEnabled, SetItemVisible, SetItemValue, GetItemValue	Read or change an item.
OpenMenu, CloseMenu	Open or close a menu while the main or pause menu is open.
ChangeVanillaEntry, RemoveVanillaChange	Hide or move a vanilla entry.
ShowMessageBox, ShowConfirm, ShowNotification	See Dialogs.
GetSavedValue, SetSavedValue	Read or write a saved value without an item.
RegisterSettingListener, RegisterActionListener	Get changes and actions of a mod, for example of its JSON menu.
Translate	See Translations.
GetKeyName	See Hotkeys.

Item types

Type	Shows	Value
Button	A row to press. Can open a submenu.	none
Checkbox	ON or OFF	0 or 1
Stepper	Options changed with Left and Right	option index
Slider	A slider and its value, for example 50 %	min to max
Dropdown	The chosen option. Pressing it opens a list.	option index
Hotkey	The key name. Pressing it waits for a key.	key code
Color	#RRGGBB. Pressing it opens red, green and blue sliders.	0xAARRGGBB
Header	A row that cannot be selected	none
Text	A row that shows its description	none
Topic	A page of a pages menu	none

Rules

• Functions can be called from any thread. Callbacks run on the game's UI thread.
• Changes show in open menus right away.
• A menu with only buttons, headers and text looks like the Settings category list. Other items, or a button with a description, make it look like a Settings page.
• Menus with value items show DEFAULTS (T). It sets visible value items back to the value they were added with, then calls onReset.
• onSelect runs when an item becomes the selected row.
• A button with submenu opens that menu. Esc goes back one level.
• SetItemValue does not call onChange.
• Labels are plain text.

Saved values

Give a value item a saveKey. Its value is saved to Data/F4SE/Plugins/MenuHelper/Settings/<modName>.ini when it changes, and AddItem starts from the saved value. Read it with GetItemValue after adding the item.

Vanilla entries

ChangeVanillaEntry hides a vanilla entry or moves it. Changes apply in order, after mod entries are placed.

MenuHelper_VanillaChangeDesc change{ sizeof(change) };
change.menus = MENUHELPER_MENU_MAIN;
change.entry = MENUHELPER_VANILLA_LOAD;
change.move = 2;  // two rows down
api->ChangeVanillaEntry(&change);

Many entries

When the main or pause menu would have more than 9 rows, all mod entries move into one MODS entry. Players can change this with sModsFolder.