Bump version to 1.8.2.

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

index afc22c09591c941b6d0525621e51888177c81968..04146e8fce0003e701d66566419fb4ec869bf65d 100644 (file)
--- a/theme.rst
+++ b/theme.rst
@@ -30,7 +30,7 @@ is a library for high-quality, high-performance video filters,
  and Nageru's themes can use a simplified version of Movit's API where
  most of the low-level details are abstracted away.
  
  and Nageru's themes can use a simplified version of Movit's API where
  most of the low-level details are abstracted away.
  
-Every frame, the theme choses a chain and a set of parameters to it,
+Every frame, the theme chooses a chain and a set of parameters to it,
  based on what it thinks the picture should look like. Every chain
  consists of a set of *inputs* (which can be either live video streams
  or static pictures) and then a set of operators or *effects* to combine
  based on what it thinks the picture should look like. Every chain
  consists of a set of *inputs* (which can be either live video streams
  or static pictures) and then a set of operators or *effects* to combine
@@ -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.