From: Steinar H. Gunderson Date: Wed, 7 Mar 2018 23:07:43 +0000 (+0100) Subject: Document theme menus. X-Git-Url: https://git.sesse.net/?p=nageru-docs;a=commitdiff_plain;h=61349658c873ac976bb3bf53d3463c9b12c42d38 Document theme menus. --- diff --git a/html.rst b/html.rst index 644e924..ede59fb 100644 --- a/html.rst +++ b/html.rst @@ -54,7 +54,7 @@ however, this is normal even in a hardware chain, and most overlay graphics does not need to be timed to the input more than through a few frames. This, and the fact that the theme can not present a very detailed UI -(short of :ref:`simple menus `), means that it can be hard to +(short of :ref:`simple menus `), means that it can be hard to exert detailed control over the graphics using Nageru alone—you will probably want to have the theme contact some non-Nageru backend (possibly over WebSockets) from where it can take detailed instructions. diff --git a/theme.rst b/theme.rst index 72da4bc..e7abc4f 100644 --- a/theme.rst +++ b/theme.rst @@ -345,3 +345,42 @@ so if you update the file on-disk, it will be available in Nageru without a restart. (If the file contains an error, the update will be ignored.) This allows you to e.g. have simple message overlays that you can change without restarting Nageru. + + +.. _menus: + +Theme menus +----------- + +Complicated themes, especially those dealing with `HTML inputs `, +may have needs for user control that go beyond those of transition buttons. +(An obvious example may be “reload the HTML file”.) For this reason, +themes can also set simple *theme menus*, which are always visible +no matter what inputs are chosen. + +If a theme chooses to set a theme menu, it will be available on the +main menu bar under “Theme”; if not, it will be hidden. You can set +the menu at startup or at any other point, using a simple series of +labels and function references:: + + function modify_aspect() + -- Your code goes here. + end + + function reload_html() + html_input:reload() + end + + ThemeMenu.set( + { "Change &aspect", modify_aspect }, + { "&Reload overlay", reload_html } + ) + +When the user chooses a menu entry, the given Lua function will +automatically be called. There are no arguments nor return values. + +There currently is no support for checkboxes, submenus, input boxes +or the likes. However, do note that since the theme is written in unrestricted +Lua, so you can use e.g. `lua-http `_ +to listen for external connections and accept more complicated inputs +from those.