Merge pull request #72 from tmontes/window-bind-events

Window bind events implementation.

Author: tmontes

README.rst

@@ -29,9 +29,11 @@ Thanks
 
 .. marker-start-thanks-dont-remove
 
-.. todo::
+* To the creators and maintainers of `Tcl/Tk <https://www.tcl.tk/>`_, a programming language I used for a while in the late 1990's, in particular for the seriously under-appreciated `Canvas widget <https://www.tcl.tk/man/tcl8.6/TkCmd/canvas.htm>`_ which is amazingly powerful. Python embeds the Tcl/Tk interpreter in the form of the `tkinter <https://docs.python.org/3/library/tkinter.html>`_ Standard Library module. Long live Tcl/Tk and `tkinter`!
+
+* To whoever `Quarks <https://www.daniweb.com/members/228139/quarks>`_ is, for sharing an effective technique for debouncing Tk `KeyPress` / `KeyRelease` events in towards the end of `this thread <https://www.daniweb.com/programming/software-development/threads/70746/keypress-event-with-holding-down-the-key>`_.
 
-   Write thanks section, if applicable.
+* To `Terry Pratchet <https://en.wikipedia.org/wiki/Terry_Pratchett>`_, for his `Discworld <https://en.wikipedia.org/wiki/Discworld>`_ novels and, in particular, for `Great A'Tuin <https://en.wikipedia.org/wiki/Discworld_%28world%29#Great_A%27Tuin>`_, the *"Giant Star Turtle (...) who travels through the Discworld universe's space, carrying four giant elephants (...) who in turn carry the Discworld."*, which has come to my mind often while creating this.
 
 .. marker-end-thanks-dont-remove
 

src/aturtle/window.py

@@ -53,6 +53,13 @@ def __init__(self, width=320, height=320, x=None, y=None,
         self._tk_window = tk_window
         self.canvas = canvas
 
+        # Event bindings.
+        self._binds = {}
+
+        # Direct key support.
+        self._direct_key_callbacks = {}
+        self._direct_key_after_ids = {}
+
 
     @property
     def x(self):
@@ -121,6 +128,114 @@ def _resize_handler(self, event):
         self._y_scroll = new_y_scroll
 
 
+    def bind(self, sequence, cb):
+        """
+        Binds Tk event `sequence` to the `cb` callable, such that `cb` is
+        called with a single event argument, when the event is triggered.
+
+        Existing bindings for the same `sequence` are replaced.
+        """
+        self._binds[sequence] = self._tk_window.bind(sequence, cb)
+
+
+    def unbind(self, sequence=None):
+        """
+        Unbinds the Tk event `sequence`. If `sequence` is None, all events
+        previously bound via `bind` are unbound.
+
+        Raises ValueError if the `sequence` isn't bound.
+        """
+        if sequence is None:
+            sequences = list(self._binds)
+            for sequence in sequences:
+                self.unbind(sequence)
+        elif sequence in self._binds:
+            self._tk_window.unbind(sequence, self._binds[sequence])
+            del self._binds[sequence]
+        else:
+            raise ValueError(f'Unknown bound sequence: {sequence!r}.')
+
+
+    def bind_direct_key(self, keysym, press_cb=None, release_cb=None):
+        """
+        Binds "direct-key" events such that when the key defined by `keysym` is
+        pressed the `press_cb` is called with a single event argument, and when
+        that same key is released the `release_cb` is called, again with a
+        single event argument.
+
+        The difference between bind_direct_key('a') and bind('<KeyPress-a>') is
+        that the former ensures that pressing and holding the A key triggers
+        the `press_cb` just once, while the latter triggers the associated
+        callback multiple times depending on OS level key delay and repeat.
+        """
+        if not press_cb and not release_cb:
+            raise ValueError(f'Missing event handler argument.')
+
+        self.bind(f'<KeyPress-{keysym}>', self._direct_key_press)
+        self.bind(f'<KeyRelease-{keysym}>', self._direct_key_release)
+
+        self._direct_key_callbacks[keysym] = (press_cb, release_cb)
+
+
+    def _direct_key_press(self, event):
+        """
+        Handles "direct-key" KeyPress events.
+        May be called multiple times while a key is held down.
+        """
+        keysym = event.keysym
+        if keysym in self._direct_key_after_ids:
+            # 2nd and subsequent KeyPress events: cancel idle handler.
+            self._tk_window.after_cancel(self._direct_key_after_ids[keysym])
+            del self._direct_key_after_ids[keysym]
+        else:
+            # First KeyPress event: trigger press_cb, if any.
+            press_cb, _release_cb = self._direct_key_callbacks[keysym]
+            if press_cb:
+                press_cb(event)
+
+
+    def _direct_key_release(self, event):
+        """
+        Handles "direct-key" KeyRelease events.
+        May be called multiple times while a key is held down.
+        """
+        keysym = event.keysym
+        # Idle handler will only run when key is raised.
+        after_id = self._tk_window.after_idle(self._direct_key_idle, event)
+        self._direct_key_after_ids[keysym] = after_id
+
+
+    def _direct_key_idle(self, event):
+        """
+        Idle handler, called when keys are raised.
+        """
+        keysym = event.keysym
+        del self._direct_key_after_ids[keysym]
+        # Trigger release_cb, if any.
+        _press_cb, release_cb = self._direct_key_callbacks[keysym]
+        if release_cb:
+            release_cb(event)
+
+
+    def unbind_direct_key(self, keysym=None):
+        """
+        Unbinds the "direct-key" events associated with `keysym`. If `keysym`
+        is None, all "direct-key" events are unbound.
+
+        Raises ValueError if `keysym` isn't "direct-key" bound.
+        """
+        if keysym is None:
+            keysyms = list(self._direct_key_callbacks)
+            for keysym in keysyms:
+                self.unbind_direct_key(keysym)
+        elif keysym in self._direct_key_callbacks:
+            self.unbind(f'<KeyPress-{keysym}>')
+            self.unbind(f'<KeyRelease-{keysym}>')
+            del self._direct_key_callbacks[keysym]
+        else:
+            raise ValueError(f'Unknown bound direct key: {keysym!r}.')
+
+
     def close(self):
 
         is_root = self._tk_window is Window._windows[0]._tk_window

tests/fake_tkinter.py

@@ -48,6 +48,9 @@ def __init__(self, screen_width, screen_height):
         self._w = None
         self._h = None
         self.bind = mock.Mock()
+        self.unbind = mock.Mock()
+        self.after_idle = mock.Mock()
+        self.after_cancel = mock.Mock()
         self.update = mock.Mock()
         self.destroy = mock.Mock()
 

tests/test_window.py

@@ -294,6 +294,233 @@ def test_no_canvas_after_close_all(self):
         self.assertIsNone(w.canvas)
 
 
+
+class TestWindowEventHandling(FakedTkinterTestCase):
+
+    def setUp(self):
+
+        super().setUp()
+        self.w = window.Window()
+
+
+    def test_bind_calls_tk_window_bind(self):
+
+        handler = lambda e: None
+        self.w.bind('<KeyPress-a>', handler)
+
+        self.w._tk_window.bind.assert_called_with('<KeyPress-a>', handler)
+
+
+    def test_bind_unbind_calls_tk_window_bind_unbind(self):
+
+        handler = lambda e: None
+        self.w.bind('<KeyPress-a>', handler)
+        self.w.unbind('<KeyPress-a>')
+
+        self.w._tk_window.bind.assert_called_with('<KeyPress-a>', handler)
+        self.w._tk_window.unbind.assert_called_with('<KeyPress-a>', mock.ANY)
+
+
+    def test_unbind_unbound_raises_ValueError(self):
+
+        with self.assertRaises(ValueError):
+            self.w.unbind('<KeyPress-a>')
+
+
+    def test_unbind_default_works_with_no_bindings(self):
+
+        self.w.unbind()
+        self.w._tk_window.unbind.assert_not_called()
+
+
+    def test_unbind_default_unbinds_all_bindings(self):
+
+        self.w.bind('<KeyPress-a>', lambda e: None)
+        self.w.bind('<KeyPress-b>', lambda e: None)
+
+        self.w.unbind()
+        unbind_call_args = self.w._tk_window.unbind.call_args_list
+        self.assertEqual(len(unbind_call_args), 2, 'unbind call count')
+
+
+    def test_bind_direct_key_with_no_cbs_raises_ValueError(self):
+
+        with self.assertRaises(ValueError):
+            self.w.bind_direct_key('a')
+
+
+    def test_bind_direct_key_with_press_cb_calls_window_bind_twice(self):
+
+        # Ignore any window setup bind calls that may have taken place.
+        self.w._tk_window.bind.reset_mock()
+
+        press_cb = lambda e: None
+        self.w.bind_direct_key('x', press_cb)
+
+        bind_call_args = self.w._tk_window.bind.call_args_list
+        self.assertEqual(len(bind_call_args), 2, 'unbind call count')
+
+        first_call, second_call = bind_call_args
+        self.assertEqual(first_call, mock.call('<KeyPress-x>', mock.ANY))
+        self.assertEqual(second_call, mock.call('<KeyRelease-x>', mock.ANY))
+
+
+    def test_bind_direct_key_with_release_cb_calls_window_bind_twice(self):
+
+        # Ignore any window setup bind calls that may have taken place.
+        self.w._tk_window.bind.reset_mock()
+
+        release_cb = lambda e: None
+        self.w.bind_direct_key('y', None, release_cb)
+
+        bind_call_args = self.w._tk_window.bind.call_args_list
+        self.assertEqual(len(bind_call_args), 2, 'unbind call count')
+
+        first_call, second_call = bind_call_args
+        self.assertEqual(first_call, mock.call('<KeyPress-y>', mock.ANY))
+        self.assertEqual(second_call, mock.call('<KeyRelease-y>', mock.ANY))
+
+
+    def test_bind_direct_key_with_both_cbs_calls_window_bind_twice(self):
+
+        # Ignore any window setup bind calls that may have taken place.
+        self.w._tk_window.bind.reset_mock()
+
+        press_cb = lambda e: None
+        release_cb = lambda e: None
+        self.w.bind_direct_key('z', press_cb, release_cb)
+
+        bind_call_args = self.w._tk_window.bind.call_args_list
+        self.assertEqual(len(bind_call_args), 2, 'bind call count')
+
+        first_call, second_call = bind_call_args
+        self.assertEqual(first_call, mock.call('<KeyPress-z>', mock.ANY))
+        self.assertEqual(second_call, mock.call('<KeyRelease-z>', mock.ANY))
+
+
+    def test_bind_unbind_direct_key_calls_window_bind_unbind_twice(self):
+
+        # Ignore any window setup bind calls that may have taken place.
+        self.w._tk_window.bind.reset_mock()
+
+        press_cb = lambda e: None
+        release_cb = lambda e: None
+        self.w.bind_direct_key('a', press_cb, release_cb)
+        self.w.unbind_direct_key('a')
+
+        bind_call_args = self.w._tk_window.bind.call_args_list
+        self.assertEqual(len(bind_call_args), 2, 'bind call count')
+
+        first_call, second_call = bind_call_args
+        self.assertEqual(first_call, mock.call('<KeyPress-a>', mock.ANY))
+        self.assertEqual(second_call, mock.call('<KeyRelease-a>', mock.ANY))
+
+        unbind_call_args = self.w._tk_window.unbind.call_args_list
+        self.assertEqual(len(unbind_call_args), 2, 'unbind call count')
+
+        first_call, second_call = unbind_call_args
+        self.assertEqual(first_call, mock.call('<KeyPress-a>', mock.ANY))
+        self.assertEqual(second_call, mock.call('<KeyRelease-a>', mock.ANY))
+
+
+    def test_unbind_direct_key_unknown_raises_ValueError(self):
+
+        with self.assertRaises(ValueError):
+            self.w.unbind_direct_key('b')
+
+
+    def test_unbind_default_works_with_no_bindings(self):
+
+        self.w.unbind_direct_key()
+        self.w._tk_window.unbind.assert_not_called()
+
+
+    def test_unbind_direct_key_default_unbinds_all_direct_keys(self):
+
+        press_cb = lambda e: None
+        release_cb = lambda e: None
+        self.w.bind_direct_key('a', press_cb, release_cb)
+        self.w.bind_direct_key('b', press_cb, release_cb)
+
+        self.w.unbind_direct_key()
+
+        # Expect 4 unbind calls: KeyPress/KeyRelease for 2 keys.
+        unbind_call_args = self.w._tk_window.unbind.call_args_list
+        self.assertEqual(len(unbind_call_args), 4, 'unbind call count')
+
+
+    def _event(self, keysym):
+
+        event = mock.Mock()
+        event.keysym = keysym
+        return event
+
+
+    def test_bind_direct_key_press_and_release(self):
+
+        press_cb = mock.Mock()
+        release_cb = mock.Mock()
+        self.w.bind_direct_key('a', press_cb, release_cb)
+
+        # KeyPress event.
+        event = self._event('a')
+        self.w._direct_key_press(event)
+
+        # Press callback called.
+        press_cb.assert_called_once()
+        press_cb.assert_called_with(event)
+        release_cb.assert_not_called()
+
+        press_cb.reset_mock()
+
+        # KeyRelease event. Not held down so _direct_key_idle called.
+        self.w._direct_key_release(event)
+        self.w._direct_key_idle(event)
+
+        # Release callback called.
+        press_cb.assert_not_called()
+        release_cb.assert_called_once()
+        release_cb.assert_called_with(event)
+
+
+    def test_bind_direct_key_press_hold_and_release(self):
+
+        press_cb = mock.Mock()
+        release_cb = mock.Mock()
+        self.w.bind_direct_key('a', press_cb, release_cb)
+
+        # KeyPress event.
+        event = self._event('a')
+        self.w._direct_key_press(event)
+
+        # Press callback called.
+        press_cb.assert_called_once()
+        press_cb.assert_called_with(event)
+        release_cb.assert_not_called()
+
+        press_cb.reset_mock()
+
+        # Holding the key triggers KeyPress/KeyReleases repeatedly.
+        # But never idle, so _direct_key_idle never called.
+        for _ in range(10):
+            self.w._direct_key_release(event)
+            self.w._direct_key_press(event)
+
+            # No callbacks while key held down.
+            press_cb.assert_not_called()
+            release_cb.assert_not_called()
+
+        # Last KeyRelease event. Not held down so _direct_key_idle called.
+        self.w._direct_key_release(event)
+        self.w._direct_key_idle(event)
+
+        # Release callback called.
+        press_cb.assert_not_called()
+        release_cb.assert_called_once()
+        release_cb.assert_called_with(event)
+
+
+
 class TestMultipleWindows(FakedTkinterTestCase):
 
     def test_create_two_windows(self):