Merge pull request #152 from martinmmueller/master

added pause/resume to Tracker.cs

Author: jackbrookes

Assets/UXF/Scripts/Etc/Tracker.cs

@@ -7,12 +7,13 @@
 namespace UXF
 {
     /// <summary>
-    /// Create a new class that inherits from this component to create custom tracking behaviour on a frame-by-frame basis.
+    /// Create a new class that inherits from this component to create custom tracking behaviour
+    /// on a frame-by-frame basis.
     /// </summary>
     public abstract class Tracker : MonoBehaviour
     {
-        private bool recording = false;
         private static string[] baseHeaders = new string[] { "time" };
+        private TrackerState currentState = TrackerState.Stopped;
 
         /// <summary>
         /// Name of the object used in saving
@@ -36,20 +37,27 @@ public string DataName
         {
             get
             {
-                Debug.AssertFormat(MeasurementDescriptor.Length > 0, "No measurement descriptor has been specified for this Tracker!");
+                Debug.AssertFormat(MeasurementDescriptor.Length > 0,
+                    "No measurement descriptor has been specified for this Tracker!");
                 return string.Join("_", new string[]{ objectName, MeasurementDescriptor });
             }
         }
 
-        public bool Recording { get { return recording; } }
+        public bool Recording { get { return currentState == TrackerState.Recording; } }
 
         public UXFDataTable Data { get; private set; } = new UXFDataTable();
-        
+
+        /// <summary>
+        /// The current state of the tracker.
+        /// </summary>
+        public TrackerState CurrentState { get => currentState; }
 
         /// <summary>
         /// When the tracker should take measurements.
         /// </summary>
-        [Tooltip("When the measurements should be taken.\n\nManual should only be selected if the user is calling the RecordRow method either from another script or a custom Tracker class.")]
+        [Tooltip("When the measurements should be taken." +
+            "\n\nManual should only be selected if the user is calling the RecordRow method" +
+            " either from another script or a custom Tracker class.")]
         public TrackerUpdateType updateType = TrackerUpdateType.LateUpdate;
 
         // called when component is added
@@ -61,21 +69,22 @@ void Reset()
         // called by unity just before rendering the frame
         void LateUpdate()
         {
-            if (recording && updateType == TrackerUpdateType.LateUpdate) RecordRow();
+            if (Recording && updateType == TrackerUpdateType.LateUpdate) RecordRow();
         }
 
         // called by unity when physics simulations are run
         void FixedUpdate()
         {
-            if (recording && updateType == TrackerUpdateType.FixedUpdate) RecordRow();
+            if (Recording && updateType == TrackerUpdateType.FixedUpdate) RecordRow();
         }
 
         /// <summary>
         /// Records a new row of data at current time.
         /// </summary>
         public void RecordRow()
         {
-            if (!recording) throw new System.InvalidOperationException("Tracker measurements cannot be taken when not recording!");
+            if (!Recording) throw new System.InvalidOperationException(
+                "Tracker measurements cannot be taken when not recording!");
 
             UXFDataRow newRow = GetCurrentValues();
             newRow.Add(("time", Time.time));
@@ -87,17 +96,54 @@ public void RecordRow()
         /// </summary>
         public void StartRecording()
         {
+            if (currentState == TrackerState.Recording)
+            {
+                Utilities.UXFDebugLogWarning($"Start command received for tracker in state: '{TrackerState.Recording}'." +
+                    " This will dump exisiting data! " +
+                    $"If you want to restart a paused tracker, use '{nameof(ResumeRecording)}()' instead.");
+            }
             var header = baseHeaders.Concat(CustomHeader);
             Data = new UXFDataTable(header.ToArray());
-            recording = true;
+            currentState = TrackerState.Recording;
         }
 
         /// <summary>
         /// Stops recording.
         /// </summary>
         public void StopRecording()
         {
-            recording = false;
+            if (currentState != TrackerState.Recording)
+            {
+                Utilities.UXFDebugLogWarning($"Stop command received for tracker in state: '{currentState}'." +
+                    $" This should only be called when tracker is in state '{TrackerState.Recording}'");
+            }
+            currentState = TrackerState.Stopped;
+        }
+
+        /// <summary>
+        /// Pauses recording.
+        /// </summary>
+        public void PauseRecording()
+        {
+            if (currentState != TrackerState.Recording)
+            {
+                Utilities.UXFDebugLogWarning($"Pause command received for tracker in state: '{currentState}'." +
+                    $"This should only be called when tracker is in state '{TrackerState.Recording}'");
+            }
+            currentState = TrackerState.Paused;
+        }
+
+        /// <summary>
+        /// Resumes recording.
+        /// </summary>
+        public void ResumeRecording()
+        {
+            if (currentState != TrackerState.Paused)
+            {
+                Utilities.UXFDebugLogWarning($"Resume command received for tracker in state: '{currentState}'." +
+                    $"This should only be called when tracker is in state '{TrackerState.Paused}'");
+            }
+            currentState = TrackerState.Recording;
         }
 
         /// <summary>
@@ -109,10 +155,20 @@ public void StopRecording()
     }
 
     /// <summary>
-    /// When the tracker should collect new measurements. Manual should only be selected if the user is calling the RecordRow method either from another script or a custom Tracker class.
+    /// When the tracker should collect new measurements. 
+    /// Manual should only be selected if the user is calling the RecordRow method
+    /// either from another script or a custom Tracker class.
     /// </summary>
     public enum TrackerUpdateType
     {
         LateUpdate, FixedUpdate, Manual
     }
+
+    /// <summary>
+    /// The possible states a tracker can be in.
+    /// </summary>
+    public enum TrackerState
+    {
+        Recording, Paused, Stopped
+    }
 }