feat(toolEvent): added an event that is triggered when a tool is acti…

…vated (#718)

* feat(toolEvent): added an event that is triggered when a tool is activated

* feat(toolEvent): api doc

* code review

common/reviews/api/tools.api.md

@@ -1743,6 +1743,8 @@ enum Events {
     // (undocumented)
     SEGMENTATION_REPRESENTATION_REMOVED = "CORNERSTONE_TOOLS_SEGMENTATION_REPRESENTATION_REMOVED",
     // (undocumented)
+    TOOL_ACTIVATED = "CORNERSTONE_TOOLS_TOOL_ACTIVATED",
+    // (undocumented)
     TOUCH_DRAG = "CORNERSTONE_TOOLS_TOUCH_DRAG",
     // (undocumented)
     TOUCH_END = "CORNERSTONE_TOOLS_TOUCH_END",
@@ -1825,6 +1827,8 @@ declare namespace EventTypes_2 {
         NormalizedInteractionEventDetail,
         NormalizedMouseEventType,
         NormalizedTouchEventType,
+        ToolActivatedEventDetail,
+        ToolActivatedEventType,
         AnnotationAddedEventDetail,
         AnnotationAddedEventType,
         AnnotationCompletedEventDetail,
@@ -5025,6 +5029,16 @@ function throttle(func: Function, wait?: number, options?: {
     trailing?: boolean;
 }): Function;
 
+// @public (undocumented)
+type ToolActivatedEventDetail = {
+    toolGroupId: string;
+    toolName: string;
+    toolBindingsOptions: SetToolBindingsType;
+};
+
+// @public (undocumented)
+type ToolActivatedEventType = Types_2.CustomEventType<ToolActivatedEventDetail>;
+
 // @public (undocumented)
 interface ToolData {
     // (undocumented)

packages/tools/src/enums/Events.ts

@@ -5,6 +5,19 @@
  *
  */
 enum Events {
+  ///////////////////////////////////////
+  //            Tools
+  ///////////////////////////////////////
+
+  /**
+   * Triggers on the eventTarget when a new tools is activated.
+   *
+   * Make use of {@link EventTypes.ToolActivatedEventType | Tool Activated Event Type  }
+   * for typing your event listeners for this tool activated event, and see what event
+   * detail is included in {@link EventTypes.ToolActivatedEventDetail | Tool Activated Event Detail}.
+   */
+  TOOL_ACTIVATED = 'CORNERSTONE_TOOLS_TOOL_ACTIVATED',
+
   ///////////////////////////////////////
   //            Annotations
   ///////////////////////////////////////

packages/tools/src/store/ToolGroupManager/ToolGroup.ts

@@ -2,13 +2,17 @@ import { MouseBindings, ToolModes } from '../../enums';
 import cloneDeep from 'lodash.clonedeep';
 import get from 'lodash.get';
 import {
+  triggerEvent,
+  eventTarget,
   getRenderingEngine,
   getRenderingEngines,
   getEnabledElementByIds,
   Settings,
   utilities as csUtils,
 } from '@cornerstonejs/core';
 import type { Types } from '@cornerstonejs/core';
+import { Events } from '../../enums';
+import { ToolActivatedEventDetail } from '../../types/EventTypes';
 import { state } from '../index';
 import {
   IToolBinding,
@@ -69,7 +73,7 @@ export default class ToolGroup implements IToolGroup {
     const toolInstance = this._toolInstances[toolInstanceName];
     if (!toolInstance) {
       console.warn(
-        `'${toolInstanceName}' is not registered with this toolGroup.`
+        `'${toolInstanceName}' is not registered with this toolGroup (${this.id}).`
       );
       return;
     }
@@ -372,6 +376,14 @@ export default class ToolGroup implements IToolGroup {
       toolInstance.onSetToolActive();
     }
     this._renderViewports();
+
+    const eventDetail: ToolActivatedEventDetail = {
+      toolGroupId: this.id,
+      toolName,
+      toolBindingsOptions,
+    };
+
+    triggerEvent(eventTarget, Events.TOOL_ACTIVATED, eventDetail);
   }
 
   /**

packages/tools/src/types/EventTypes.ts

@@ -3,6 +3,7 @@ import { Annotation } from './AnnotationTypes';
 import IPoints from './IPoints';
 import ITouchPoints from './ITouchPoints';
 import IDistance from './IDistance';
+import { SetToolBindingsType } from './ISetToolModeOptions';
 import { Swipe } from '../enums/Touch';
 
 /**
@@ -70,6 +71,18 @@ type InteractionStartEventDetail = InteractionEventDetail;
 
 type InteractionEndEventDetail = InteractionEventDetail;
 
+/**
+ * The data that is passed to the event handler when a tool is activated.
+ */
+type ToolActivatedEventDetail = {
+  /** unique id of the toolGroup */
+  toolGroupId: string;
+  /** Tool name */
+  toolName: string;
+  /** Tool binding options */
+  toolBindingsOptions: SetToolBindingsType;
+};
+
 /**
  * The data that is passed to the event handler when a new annotation is added
  * to the annotations.
@@ -411,6 +424,11 @@ type NormalizedMouseEventType = Types.CustomEventType<MouseCustomEventDetail>;
  */
 type NormalizedTouchEventType = Types.CustomEventType<TouchCustomEventDetail>;
 
+/**
+ * The ToolActivated event type
+ */
+type ToolActivatedEventType = Types.CustomEventType<ToolActivatedEventDetail>;
+
 /**
  * The AnnotationAdded event type
  */
@@ -611,6 +629,8 @@ export {
   NormalizedInteractionEventDetail,
   NormalizedMouseEventType,
   NormalizedTouchEventType,
+  ToolActivatedEventDetail,
+  ToolActivatedEventType,
   AnnotationAddedEventDetail,
   AnnotationAddedEventType,
   AnnotationCompletedEventDetail,