Bump version to 1.8.2.

[nageru-docs] / theme.rst
diff --git a/theme.rst b/theme.rst

index 9028b6868256584fcbdff260239081bbbfbb9329..04146e8fce0003e701d66566419fb4ec869bf65d 100644 (file)
--- a/theme.rst
+++ b/theme.rst
@@ -320,6 +320,8 @@ Transitions involving scenes tend to be the most complicated parts of the theme
  logic, but also make for the most distinct parts of your visual look.
  
  
  logic, but also make for the most distinct parts of your visual look.
  
  
+.. _images:
+
  Image inputs
  ------------
  
  Image inputs
  ------------
  
@@ -343,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.
  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 :doc:`HTML inputs <html>`,
+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 <https://github.com/daurnimator/lua-http>`_
+to listen for external connections and accept more complicated inputs
+from those.