From bad09555ec5ff7f571cf2ee7ac5599caa74fee76 Mon Sep 17 00:00:00 2001
From: TEParsons <todd.e.parsons@gmail.com>
Date: Mon, 20 May 2024 12:32:26 +0100
Subject: [PATCH] ENH: Add method to query wether there's an unfinished message

---
 psychopy_bbtk/tpad.py | 47 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/psychopy_bbtk/tpad.py b/psychopy_bbtk/tpad.py
index 220da15..b5d4416 100644
--- a/psychopy_bbtk/tpad.py
+++ b/psychopy_bbtk/tpad.py
@@ -132,6 +132,17 @@ def dispatchMessages(self):
             True if request sent successfully
         """
         self.parent.dispatchMessages()
+    
+    def hasUnfinishedMessage(self):
+        """
+        Is the parent TPad waiting for an end-of-line character?
+        
+        Returns
+        -------
+        bool
+            True if there is a partial message waiting for an end-of-line
+        """
+        return self.parent.hasUnfinishedMessage()
 
     def parseMessage(self, message):
         # if given a string, split according to regex
@@ -225,6 +236,17 @@ def dispatchMessages(self):
             True if request sent successfully
         """
         self.parent.dispatchMessages()
+    
+    def hasUnfinishedMessage(self):
+        """
+        Is the parent TPad waiting for an end-of-line character?
+        
+        Returns
+        -------
+        bool
+            True if there is a partial message waiting for an end-of-line
+        """
+        return self.parent.hasUnfinishedMessage()
 
     def parseMessage(self, message):
         # if given a string, split according to regex
@@ -450,6 +472,31 @@ def dispatchMessages(self):
                     logging.debug(f"Received unparsable message from TPad: {line}")
         # mark that a dispatch has finished
         self._dispatchInProgress = False
+    
+    def hasUnfinishedMessage(self):
+        """
+        We don't wait for an end-of-line from the TPad device before continuing, as 
+        dispatchMessages is often called in a frame loop so waiting for messages would 
+        ruin the frame rate. If just the start of a message has been received, this 
+        function will return True.
+
+        Usage
+        -----
+        If you want to be certain that all events have been dispatched, you can do:
+        ```
+        timeout = Clock()
+        while myTPad.hasUnfinishedMessage() and timeout.getTime() < 0.1:
+            myTPad.dispatchMessages()
+        ```
+        (the purpose of the `timeout` clock is to avoid getting into an infinite loop 
+        if the TPad sends anything unexpected)
+        
+        Returns
+        -------
+        bool
+            True if there is a partial message waiting for an end-of-line
+        """
+        return bool(self._lastMessage)
 
     @staticmethod
     def _detectComPort():