Write some more basic Futatabi docs.

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

index 162d86234dd29afbc9603461746cdece1162a94e..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.
  
-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
@@ -55,7 +55,7 @@ the screen, and in this case, that would be the input)::
  
  Note the “hq” parameter. Every chain needs to be able to run in two
  situations: Both for the stream output (the ”live” pane) and for the preview
-displays (the big “preview” pane and the smaller ones). The details have
+displays (the big “preview” pane and the :ref:`channels <channels>`). The details have
  to do with Nageru internals (high-quality chains need to have an additional
  Y'CbCr output), but the distinction is also useful for themes. In particular,
  some operations, like scaling, can be done in various quality levels,
@@ -67,6 +67,7 @@ and then scaled down for the GUI. Preview chains are rendered in exactly
  the resolution required, although of course, intermediate steps could be
  bigger.
  
+
  Setting parameters, and the get_chain entry point
  -------------------------------------------------
  
@@ -228,6 +229,8 @@ the transition is over and changes back to showing only one input
  (presumably the new one).
  
  
+.. _channels:
+
  Channels
  --------
  
@@ -317,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.
  
  
+.. _images:
+
  Image inputs
  ------------
  
@@ -340,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 :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.