summaryrefslogtreecommitdiffstats
path: root/DOCS/man/en/lua.rst
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2014-04-08 21:10:00 +0200
committerwm4 <wm4@nowhere>2014-04-08 21:10:00 +0200
commita94020e25bc5fc50ac0cea132a4cccb7743e85fa (patch)
treeb18f44436bae70ce7833c4ff5247cc1fdd2793e1 /DOCS/man/en/lua.rst
parent708f32b74677ae3fac00ecabfbfd866426b06586 (diff)
downloadmpv-a94020e25bc5fc50ac0cea132a4cccb7743e85fa.tar.bz2
mpv-a94020e25bc5fc50ac0cea132a4cccb7743e85fa.tar.xz
lua: add API for observing property changes
A low level API was added already earlier, but that was merely a binding for the raw C API. Add a "proper" one, and document it.
Diffstat (limited to 'DOCS/man/en/lua.rst')
-rw-r--r--DOCS/man/en/lua.rst22
1 files changed, 22 insertions, 0 deletions
diff --git a/DOCS/man/en/lua.rst b/DOCS/man/en/lua.rst
index ac37f1eabb..5b07ebe0ce 100644
--- a/DOCS/man/en/lua.rst
+++ b/DOCS/man/en/lua.rst
@@ -240,6 +240,28 @@ The ``mp`` module is preloaded, although it can be loaded manually with
are equal to the ``fn`` parameter. This uses normal Lua ``==`` comparison,
so be careful when dealing with closures.
+``mp.observe_property(name, type, fn)``
+ Watch a property for changes. If the property ``name`` is changed, then
+ the function ``fn(name)`` will be called. ``type`` can be ``nil``, or be
+ set to one of ``none``, ``native``, ``bool``, ``string``, or ``number``.
+ ``none`` is the same as ``nil``. For all other values, the new value of
+ the property will be passed as second argument to ``fn``, using
+ ``mp.get_property_<type>`` to retrieve it. This means if ``type`` is for
+ example ``string``, ``fn`` is roughly called as in
+ ``fn(name, mp.get_property_string(name))``.
+
+ Sporadic property change events are possible. This means the change function
+ ``fn`` can be called even if the property doesn't actually change. Likewise,
+ in some cases the function is not called even if the property changes. If
+ possible, change events are coalesced. If a property is changed a bunch of
+ times in a row, only the last change triggers the change function. (The
+ exact behavior depends on timing and other things.)
+
+``mp.unobserve_property(fn)``
+ Undo ``mp.observe_property(..., fn)``. This removes all property handlers
+ that are equal to the ``fn`` parameter. This uses normal Lua ``==``
+ comparison, so be careful when dealing with closures.
+
``mp.add_timeout(seconds, fn)``
Call the given function fn when the given number of seconds has elapsed.
Note that the number of seconds can be fractional. As of now, the timer