feat(Controller): add event for action of toggling visibility

The Controller Actions script now emits events when the visibility
of the controller is toggled.

When the visibility is toggled on then the:
`ControllerModelVisible` event is emitted.

When the visibility is toggled off then the:
`ControllerModelInvisible` event is emitted.

Assets/VRTK/Scripts/Helper/UnityEvents/VRTK_ControllerActions_UnityEvents.cs

@@ -0,0 +1,65 @@
+namespace VRTK.UnityEventHelper
+{
+    using UnityEngine;
+    using UnityEngine.Events;
+
+    [RequireComponent(typeof(VRTK_ControllerActions))]
+    public class VRTK_ControllerActions_UnityEvents : MonoBehaviour
+    {
+        private VRTK_ControllerActions ca;
+
+        [System.Serializable]
+        public class UnityObjectEvent : UnityEvent<ControllerActionsEventArgs> { };
+
+        /// <summary>
+        /// Emits the ControllerModelVisible class event.
+        /// </summary>
+        public UnityObjectEvent OnControllerModelVisible;
+        /// <summary>
+        /// Emits the ControllerModelInvisible class event.
+        /// </summary>
+        public UnityObjectEvent OnControllerModelInvisible;
+
+        private void SetControllerAction()
+        {
+            if (ca == null)
+            {
+                ca = GetComponent<VRTK_ControllerActions>();
+            }
+        }
+
+        private void OnEnable()
+        {
+            SetControllerAction();
+            if (ca == null)
+            {
+                Debug.LogError("The VRTK_ControllerActions_UnityEvents script requires to be attached to a GameObject that contains a VRTK_ControllerActions script");
+                return;
+            }
+
+            ca.ControllerModelVisible += ControllerModelVisible;
+            ca.ControllerModelInvisible += ControllerModelInvisible;
+        }
+
+        private void ControllerModelVisible(object o, ControllerActionsEventArgs e)
+        {
+            OnControllerModelVisible.Invoke(e);
+        }
+
+        private void ControllerModelInvisible(object o, ControllerActionsEventArgs e)
+        {
+            OnControllerModelInvisible.Invoke(e);
+        }
+
+        private void OnDisable()
+        {
+            if (ca == null)
+            {
+                return;
+            }
+
+            ca.ControllerModelVisible -= ControllerModelVisible;
+            ca.ControllerModelInvisible -= ControllerModelInvisible;
+        }
+    }
+}

Assets/VRTK/Scripts/VRTK_ControllerActions.cs

@@ -5,6 +5,22 @@ namespace VRTK
     using System.Collections;
     using System.Collections.Generic;
 
+    /// <summary>
+    /// Event Payload
+    /// </summary>
+    /// <param name="controllerIndex">The index of the controller that was used.</param>
+    public struct ControllerActionsEventArgs
+    {
+        public uint controllerIndex;
+    }
+
+    /// <summary>
+    /// Event Payload
+    /// </summary>
+    /// <param name="sender">this object</param>
+    /// <param name="e"><see cref="ControllerActionsEventArgs"/></param>
+    public delegate void ControllerActionsEventHandler(object sender, ControllerActionsEventArgs e);
+
     /// <summary>
     /// The Controller Actions script provides helper methods to deal with common controller actions. It deals with actions that can be done to the controller.
     /// </summary>
@@ -15,15 +31,40 @@ namespace VRTK
     /// </example>
     public class VRTK_ControllerActions : MonoBehaviour
     {
+        /// <summary>
+        /// Emitted when the controller model is toggled to be visible.
+        /// </summary>
+        public event ControllerActionsEventHandler ControllerModelVisible;
+
+        /// <summary>
+        /// Emitted when the controller model is toggled to be invisible.
+        /// </summary>
+        public event ControllerActionsEventHandler ControllerModelInvisible;
+
         private bool controllerVisible = true;
         private ushort hapticPulseStrength;
-
         private uint controllerIndex;
         private ushort maxHapticVibration = 3999;
         private bool controllerHighlighted = false;
         private Dictionary<GameObject, Material> storedMaterials;
         private Dictionary<string, Transform> cachedElements;
 
+        public virtual void OnControllerModelVisible(ControllerActionsEventArgs e)
+        {
+            if (ControllerModelVisible != null)
+            {
+                ControllerModelVisible(this, e);
+            }
+        }
+
+        public virtual void OnControllerModelInvisible(ControllerActionsEventArgs e)
+        {
+            if (ControllerModelInvisible != null)
+            {
+                ControllerModelInvisible(this, e);
+            }
+        }
+
         /// <summary>
         /// The IsControllerVisible method returns true if the controller is currently visible by whether the renderers on the controller are enabled.
         /// </summary>
@@ -60,7 +101,16 @@ public void ToggleControllerModel(bool state, GameObject grabbedChildObject)
                     renderer.enabled = state;
                 }
             }
+
             controllerVisible = state;
+            if(state)
+            {
+                OnControllerModelVisible(SetActionEvent(controllerIndex));
+            }
+            else
+            {
+                OnControllerModelInvisible(SetActionEvent(controllerIndex));
+            }
         }
 
         /// <summary>
@@ -345,5 +395,12 @@ private void ToggleHighlightAlias(bool state, string transformPath, Color? highl
                 ToggleHighlightControllerElement(state, element.gameObject, highlight, duration);
             }
         }
+
+        private ControllerActionsEventArgs SetActionEvent(uint index)
+        {
+            ControllerActionsEventArgs e;
+            e.controllerIndex= index;
+            return e;
+        }
     }
 }

DOCUMENTATION.md

@@ -652,6 +652,22 @@ The IsButtonPressed method takes a given button alias and returns a boolean whet
 
 The Controller Actions script provides helper methods to deal with common controller actions. It deals with actions that can be done to the controller.
 
+### Class Events
+
+ * `ControllerModelVisible` - Emitted when the controller model is toggled to be visible.
+ * `ControllerModelInvisible` - Emitted when the controller model is toggled to be invisible.
+
+### Unity Events
+
+Adding the `VRTK_ControllerActions_UnityEvents` component to `VRTK_ControllerActions` object allows access to `UnityEvents` that will react identically to the Class Events.
+
+ * `OnControllerModelVisible` - Emits the ControllerModelVisible class event.
+ * `OnControllerModelInvisible` - Emits the ControllerModelInvisible class event.
+
+### Event Payload
+
+ * `uint controllerIndex` - The index of the controller that was used.
+
 ### Class Methods
 
 #### IsControllerVisible/0