Document promise_to_disable_if_enabled.

[nageru-docs] / theme.rst

diff --git a/theme.rst b/theme.rst
index 2e70ca9db8004b9fe44d579d05e78818fea3c66e..dbfdebe8e684ba302f8fe74498b212bf7775ece1 100644 (file)
--- a/theme.rst
+++ b/theme.rst
@@ -203,6 +203,9 @@ you must set it directly on the effect::
   input0_scaled:set_int("width", 1280)  -- Set on both alternatives.
   input0_scaled:set_int("height", 720)
 
+  -- This is also possible, as choose() returns the chosen effect:
+  input0_scaled:choose(ResampleEffect):set_float("zoom_y", 1.0001)
+
 Actually, more versions are created than you'd immediately expect.
 In particular, the output format for the live output and all previews are
 different (Y'CbCr versus RGBA), which is also handled transparently for you.
@@ -396,6 +399,17 @@ crop is. If so, you can do this::
 
    resample_effect:always_disable_if_disabled(crop_effect)
 
+Also, since Nageru 1.9.1, you can disable an optional effect if a given other
+effect is *enabled*::
+
+   overlay1_effect:promise_to_disable_if_enabled(overlay2_effect)
+   overlay2_effect:promise_to_disable_if_enabled(overlay1_effect)
+
+Note that the latter is a promise from the user, not automatic disabling; since
+it is mostly useful for mutual exclusions, Nageru wouldn't know which of the
+two to disable. (If you violate the promise, you will get an error message at
+runtime.) It can still be useful for reducing the number of alternatives, though.
+
 For more advanced exclusions, you may choose to split up the scenes into several
 distinct ones that you manage yourself; indeed, before Nageru 1.9.0, that was
 the only option. At some point, however, you may choose to simply accept the
@@ -493,3 +507,22 @@ or frame rate:
 You can use this either for display purposes, or for choosing the right
 effect alternatives. In particular, you may want to disable scaling if
 the frame is already of the correct resolution.
+
+
+Overriding the status line
+--------------------------
+
+Some users may wish to override the status line, e.g. with recording time.
+If so, it is possible (since Nageru 1.9.1) to declare a function **format_status_line**::
+
+  function format_status_line(disk_space_text, file_length_seconds)
+    if file_length_seconds > 86400.0 then
+      return "Time to make a new segment"
+    else
+      return "Disk space left: " .. disk_space_text
+    end
+  end
+
+As demonstrated, it is given the disk space text (that would normally
+be there), and the length of the current recording file in seconds.
+HTML is supported.