move callbacks/observer examples into examples/events/

examples/events/README.md

@@ -0,0 +1,8 @@
+# Events
+
+If you want to receive updates on certain events there are two routes you can take:
+
+-   Register a class that implements an `on_update(self, event) -> None` method on the `{Remote}.subect` class.
+-   Register callback functions/methods on the `{Remote}.subect` class, one for each type of update.
+
+Included are examples of both approaches.

examples/events/callbacks/README.md

@@ -0,0 +1,33 @@
+## About
+
+This script demonstrates how to interact with the event thread/event object. It also demonstrates how to register event specific callbacks.
+
+By default the interface does not broadcast any events. So even though our callbacks are registered, and the event thread has been initiated, we won't receive updates.
+
+After five seconds the event object is used to subscribe to all events for a total of thirty seconds.
+
+Remember that events can also be unsubscribed to with `vm.event.remove()`. Callbacks can also be deregistered using vm.observer.remove().
+
+The same can be done without a context manager:
+
+```python
+    vm = voicemeeterlib.api(KIND_ID)
+    vm.login()
+    vm.observer.add(on_midi)    # register an `on_midi` callback function
+    vm.init_thread()
+    vm.event.add("midi")    # in this case we only subscribe to midi events.
+    ...
+    vm.end_thread()
+    vm.logout()
+```
+
+Once initialized, the event thread will continously run until end_thread() is called. Even if all events are unsubscribed to.
+
+## Use
+
+Simply run the script and trigger events and you should see the output after 5 seconds. To trigger events do the following:
+
+-   change GUI parameters to trigger pdirty
+-   press any macrobutton to trigger mdirty
+-   play audio through any bus to trigger ldirty
+-   any midi input to trigger midi

examples/events/callbacks/__main__.py

@@ -0,0 +1,53 @@
+import logging
+import time
+
+import voicemeeterlib
+
+logging.basicConfig(level=logging.INFO)
+
+
+class App:
+    def __init__(self, vm):
+        self._vm = vm
+        # register the callbacks for each event
+        self._vm.observer.add(
+            [self.on_pdirty, self.on_mdirty, self.on_ldirty, self.on_midi]
+        )
+
+    def __enter__(self):
+        self._vm.init_thread()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self._vm.end_thread()
+
+    def on_pdirty(self):
+        print('pdirty!')
+
+    def on_mdirty(self):
+        print('mdirty!')
+
+    def on_ldirty(self):
+        for bus in self._vm.bus:
+            if bus.levels.isdirty:
+                print(bus, bus.levels.all)
+
+    def on_midi(self):
+        current = self._vm.midi.current
+        print(f'Value of midi button {current} is {self._vm.midi.get(current)}')
+
+
+def main():
+    KIND_ID = 'banana'
+
+    with voicemeeterlib.api(KIND_ID) as vm:
+        with App(vm):
+            for i in range(5, 0, -1):
+                print(f'events start in {i} seconds')
+                time.sleep(1)
+            vm.event.add(['pdirty', 'ldirty', 'midi', 'mdirty'])
+            time.sleep(30)
+
+
+if __name__ == '__main__':
+    main()

examples/events/observer/README.md

@@ -0,0 +1,14 @@
+## About
+
+Registers a class as an observer and defines a callback.
+
+## Use
+
+Run the script, then:
+
+-   change GUI parameters to trigger pdirty
+-   press any macrobutton to trigger mdirty
+-   play audio through any bus to trigger ldirty
+-   any midi input to trigger midi
+
+Pressing `<Enter>` will exit.

examples/events/observer/__main__.py

@@ -0,0 +1,45 @@
+import logging
+
+import voicemeeterlib
+
+logging.basicConfig(level=logging.INFO)
+
+
+class App:
+    def __init__(self, vm):
+        self._vm = vm
+        # register your app as event observer
+        self._vm.observer.add(self)
+
+    def __str__(self):
+        return type(self).__name__
+
+    # define an 'on_update' callback function to receive event updates
+    def on_update(self, event):
+        if event == 'pdirty':
+            print('pdirty!')
+        elif event == 'mdirty':
+            print('mdirty!')
+        elif event == 'ldirty':
+            for bus in self._vm.bus:
+                if bus.levels.isdirty:
+                    print(bus, bus.levels.all)
+        elif event == 'midi':
+            current = self._vm.midi.current
+            print(f'Value of midi button {current} is {self._vm.midi.get(current)}')
+
+
+def main():
+    KIND_ID = 'banana'
+
+    with voicemeeterlib.api(
+        KIND_ID, **{k: True for k in ('pdirty', 'mdirty', 'ldirty', 'midi')}
+    ) as vm:
+        App(vm)
+
+        while _ := input('Press <Enter> to exit\n'):
+            pass
+
+
+if __name__ == '__main__':
+    main()