Menu

Group menu · 17 exports · from forks/gamexueren/scripthook.h (framework 1.0-beta7-wildm1, SH_API_VERSION 2)

One root owned by the API; every plugin adds a submenu.

Export	Summary
ShMenuCreate	A top level entry for your plugin.
ShMenuSub	See ShMenuCreate.
ShMenuAction	See ShMenuCreate.
ShMenuToggle	See ShMenuCreate.
ShMenuNumber	See ShMenuCreate.
ShMenuList	opts must outlive the menu.
ShMenuSetValue	Sync a toggle/list row's displayed value without firing its callback.
ShMenuDisable	Draw a row as unavailable, and refuse to change it.
ShMenuClear	Drop a menu's items, keeping the row, so a plugin can rebuild its own menu without stacking duplicates.
ShMenuDestroy	Remove the row and its subtree.
ShMenuStatus	The line under the items.
ShMenuStatusF	Set the status line from a printf template.
ShMenuHint	The hint shown under the title of this submenu, replacing the control hints the root menu shows.
ShMenuSetKey	See ShMenuHint.
ShMenuIsOpen	—
ShMenuIsShowing	Is that menu the page on screen right now?
ShMenuOpen	See ShMenuIsShowing.

ShMenuCreate

SH_API uint32_t ShMenuCreate(const char *title);

A top level entry for your plugin. F4 opens the root.

scripthook.h, line 1298

ShMenuSub

SH_API uint32_t ShMenuSub(uint32_t parent, const char *label);

Documented together with ShMenuCreate just above.

scripthook.h, line 1299

ShMenuAction

SH_API int  ShMenuAction(uint32_t menu, const char *label,
                         ShMenuFn fn, void *user);

Documented together with ShMenuCreate just above.

scripthook.h, line 1300

ShMenuToggle

SH_API int  ShMenuToggle(uint32_t menu, const char *label,
                         int initial, ShMenuFn fn, void *user);

Documented together with ShMenuCreate just above.

scripthook.h, line 1302

ShMenuNumber

SH_API int  ShMenuNumber(uint32_t menu, const char *label,
                         float initial, float lo, float hi,
                         float step, ShMenuFn fn, void *user);

Documented together with ShMenuCreate just above.

scripthook.h, line 1304

ShMenuList

SH_API int  ShMenuList(uint32_t menu, const char *label,
                       const char **opts, int n, int initial,
                       ShMenuFn fn, void *user);

opts must outlive the menu. String literals are fine, and so are numbers built once into a static buffer - an hour row is just "0" to "23" and needs no translation. The row WRAPS: one step past the last option is the first, which is what makes a clock row usable with the left/right keys at all. Up to 64 options; anything past that is dropped.

scripthook.h, line 1313

ShMenuSetValue

SH_API int  ShMenuSetValue(uint32_t menu, const char *label,
                           int value);

Sync a toggle/list row's displayed value without firing its callback. A plugin that changed the state behind the menu's back (a hotkey flip) calls this so the next capture shows the truth. Matches on the label inside that one menu.

scripthook.h, line 1320

ShMenuDisable

SH_API int  ShMenuDisable(uint32_t menu, const char *label,
                          int disabled);

Draw a row as unavailable, and refuse to change it.

A disabled row is still listed and still navigable - the player can see what it is and what it is set to - but the left/right keys and Enter do nothing on it, and the renderer draws it dimmed. It is the answer to "this setting has no effect while that master switch is off": hiding the row instead loses the information that the setting exists and what it was left at.

Matches on the label inside that one menu, the same way ShMenuSetValue does. A row can be disabled and enabled again at any time; the flag lives with the row, so it survives the menu being captured every frame.

scripthook.h, line 1335

ShMenuClear

SH_API int  ShMenuClear(uint32_t menu);

Drop a menu's items, keeping the row, so a plugin can rebuild its own menu without stacking duplicates.

scripthook.h, line 1339

ShMenuDestroy

SH_API int  ShMenuDestroy(uint32_t menu);

Remove the row and its subtree.

scripthook.h, line 1341

ShMenuStatus

SH_API int  ShMenuStatus(uint32_t menu, const char *text);

The line under the items. Empty text removes it.

scripthook.h, line 1343

ShMenuStatusF

SH_API int  ShMenuStatusF(uint32_t menu, const char *fmt, ...);

Set the status line from a printf template. The English template is translated as the menu's own scope first, so the [lang.<menu>] value keeps the same % placeholders and the result is formatted once with the arguments. The language is fixed at startup, so translating here matches the capture path. The template and value must use the same conversion specifications.

scripthook.h, line 1351

ShMenuHint

SH_API int  ShMenuHint(uint32_t menu, const char *text);

The hint shown under the title of this submenu, replacing the control hints the root menu shows. Empty text removes it. The text is translated as the menu's own scope, so it can be an English key in the [lang.<menu>] table.

scripthook.h, line 1356

ShMenuSetKey

SH_API void ShMenuSetKey(int vk);

Documented together with ShMenuHint just above.

scripthook.h, line 1357

ShMenuIsOpen

SH_API int  ShMenuIsOpen(void);

No doc comment in the header.

scripthook.h, line 1371

ShMenuIsShowing

SH_API int  ShMenuIsShowing(uint32_t menu);

Is that menu the page on screen right now? 1 when the menu is up and menu is exactly the page being shown; 0 when another page is showing, when the menu is closed (nothing is on screen then, whatever page was left open last), or when the id names no menu.

Exactly that page, not "somewhere on the way to it": the framework draws the status line of the current page and of no other, so while the player is inside a submenu the parent's page is not showing even though the player came through it. Asking about the parent there answers 0; asking about the submenu answers 1. A plugin whose status line lives in a submenu passes that submenu's id, and a plugin that wants to know whether any of several pages of its own is up asks about each of them.

This is the guard for a status line. ShMenuStatus/ShMenuStatusF write into the menu model, and a plugin that keeps a line current while nobody can read it is spending work on nothing; gate the refresh on this and the line is only written while it can be seen. The framework shows whatever was written last the moment the page comes up, so a plugin that wants the first frame to be right keeps a dirty flag of its own (any page with a live readout does exactly that).

0 for a menu that exists and is simply not showing is an answer, not a failure: ShLastError is set only when the id names no menu.

scripthook.h, line 1396

ShMenuOpen

SH_API void ShMenuOpen(int open);

Documented together with ShMenuIsShowing just above.

scripthook.h, line 1397