@cornerstonejs/tools 0.56.1 → 0.56.3

package/src/eventDispatchers/mouseEventHandlers/mouseClick.ts

@@ -0,0 +1,13 @@
+import customCallbackHandler from '../shared/customCallbackHandler';
+
+/**
+ * mouseClick - Event handler for mouse click events. Uses `customCallbackHandler` to fire
+ * the `mouseClickCallback` function on active tools.
+ */
+const mouseClick = customCallbackHandler.bind(
+  null,
+  'Mouse',
+  'mouseClickCallback'
+);
+
+export default mouseClick;

package/src/eventDispatchers/mouseEventHandlers/mouseDoubleClick.ts

@@ -0,0 +1,13 @@
+import customCallbackHandler from '../shared/customCallbackHandler';
+
+/**
+ * @function mouseDoubleClick - Event handler for mouse double click events. Uses `customCallbackHandler` to fire
+ * the `doubleClickCallback` function on active tools.
+ */
+const mouseDoubleClick = customCallbackHandler.bind(
+  null,
+  'Mouse',
+  'doubleClickCallback'
+);
+
+export default mouseDoubleClick;

package/src/eventDispatchers/mouseEventHandlers/mouseDown.ts

@@ -0,0 +1,196 @@
+import { state } from '../../store';
+import { ToolModes } from '../../enums';
+import { EventTypes } from '../../types';
+import {
+  ToolAnnotationPair,
+  ToolsWithMoveableHandles,
+} from '../../types/InternalToolTypes';
+
+import {
+  setAnnotationSelected,
+  isAnnotationSelected,
+} from '../../stateManagement/annotation/annotationSelection';
+
+import { isAnnotationLocked } from '../../stateManagement/annotation/annotationLocking';
+import { isAnnotationVisible } from '../../stateManagement/annotation/annotationVisibility';
+
+// Util
+import filterToolsWithMoveableHandles from '../../store/filterToolsWithMoveableHandles';
+import filterToolsWithAnnotationsForElement from '../../store/filterToolsWithAnnotationsForElement';
+import filterMoveableAnnotationTools from '../../store/filterMoveableAnnotationTools';
+import getActiveToolForMouseEvent from '../shared/getActiveToolForMouseEvent';
+import getToolsWithModesForMouseEvent from '../shared/getToolsWithModesForMouseEvent';
+
+const { Active, Passive } = ToolModes;
+
+/**
+ * When the mouse is depressed we check which entities can process these events in the following manner:
+ *
+ * - First we get the `activeTool` for the mouse button pressed.
+ * - If the `activeTool` has a `preMouseDownCallback`, this is called. If the callback returns `true`,
+ *   the event does not propagate further.
+ * - Next we get all tools which are active or passive (`activeAndPassiveTools`), as annotation. for these tools could
+ *   possibly catch and handle these events. We then filter the `activeAndPassiveTools` using `filterToolsWithAnnotationsForElement`, which filters tools with annotations
+ *   for this frame of reference. Optionally a tool can employ a further filtering (via a
+ *   `filterInteractableAnnotationsForElement` callback) for tools interactable within the current camera view
+ *   (e.g. tools that only render when viewed from a certain direction).
+ * - Next we check if any handles are interactable for each tool (`filterToolsWithMoveableHandles`). If interactable
+ *   handles are found, the first tool/handle found consumes the event and the event does not propagate further.
+ * - Next we check any tools are interactable (e.g. moving an entire length annotation rather than one of its handles:
+ *   `filterMoveableAnnotationTools`). If interactable tools are found, the first tool found consumes the event and the
+ *   event does not propagate further.
+ * - Finally, if the `activeTool` has `postMouseDownCallback`, this is called.  If the callback returns `true`,
+ *   the event does not propagate further.
+ *
+ * If the event is not consumed the event will bubble to the `mouseDownActivate` handler.
+ *
+ * @param evt - The normalized mouseDown event.
+ */
+export default function mouseDown(evt: EventTypes.MouseDownEventType) {
+  // If a tool has locked the current state it is dealing with an interaction within its own eventLoop.
+  if (state.isInteractingWithTool) {
+    return;
+  }
+
+  const activeTool = getActiveToolForMouseEvent(evt);
+
+  // Check for preMouseDownCallbacks,
+  // If the tool claims it consumed the event, prevent further checks.
+  if (activeTool && typeof activeTool.preMouseDownCallback === 'function') {
+    const consumedEvent = activeTool.preMouseDownCallback(evt);
+
+    if (consumedEvent) {
+      return;
+    }
+  }
+
+  // Find all tools that might respond to this mouse down
+  const isPrimaryClick = evt.detail.event.buttons === 1;
+  const activeToolsWithEventBinding = getToolsWithModesForMouseEvent(
+    evt,
+    [Active],
+    evt.detail.event.buttons
+  );
+  const passiveToolsIfEventWasPrimaryMouseButton = isPrimaryClick
+    ? getToolsWithModesForMouseEvent(evt, [Passive])
+    : undefined;
+  const applicableTools = [
+    ...(activeToolsWithEventBinding || []),
+    ...(passiveToolsIfEventWasPrimaryMouseButton || []),
+  ];
+
+  const eventDetail = evt.detail;
+  const { element } = eventDetail;
+
+  // Filter tools with annotations for this element
+  const annotationToolsWithAnnotations = filterToolsWithAnnotationsForElement(
+    element,
+    applicableTools
+  );
+
+  const canvasCoords = eventDetail.currentPoints.canvas;
+
+  // For the canvas coordinates, find all tools that might respond to this mouse down
+  // on their handles. This filter will call getHandleNearImagePoint for each tool
+  // instance (each annotation)
+  const annotationToolsWithMoveableHandles = filterToolsWithMoveableHandles(
+    element,
+    annotationToolsWithAnnotations,
+    canvasCoords,
+    'mouse'
+  );
+
+  // Preserve existing selections when shift key is pressed
+  const isMultiSelect = !!evt.detail.event.shiftKey;
+
+  // If there are annotation tools whose handle is near the mouse, select the first one
+  // that isn't locked. If there's only one annotation tool, select it.
+  if (annotationToolsWithMoveableHandles.length > 0) {
+    const { tool, annotation, handle } = getAnnotationForSelection(
+      annotationToolsWithMoveableHandles
+    ) as ToolsWithMoveableHandles;
+
+    toggleAnnotationSelection(annotation.annotationUID, isMultiSelect);
+    tool.handleSelectedCallback(evt, annotation, handle, 'Mouse');
+
+    return;
+  }
+
+  // If there were no annotation tools whose handle was near the mouse, try to check
+  // if any of the annotation tools are interactable (e.g. moving an entire length annotation)
+  const moveableAnnotationTools = filterMoveableAnnotationTools(
+    element,
+    annotationToolsWithAnnotations,
+    canvasCoords,
+    'mouse'
+  );
+
+  // If there are annotation tools that are interactable, select the first one
+  // that isn't locked. If there's only one annotation tool, select it.
+  if (moveableAnnotationTools.length > 0) {
+    const { tool, annotation } = getAnnotationForSelection(
+      moveableAnnotationTools
+    );
+
+    toggleAnnotationSelection(annotation.annotationUID, isMultiSelect);
+    tool.toolSelectedCallback(evt, annotation, 'Mouse');
+
+    return;
+  }
+
+  // Run the postMouseDownCallback for the active tool if it exists
+  if (activeTool && typeof activeTool.postMouseDownCallback === 'function') {
+    const consumedEvent = activeTool.postMouseDownCallback(evt);
+
+    if (consumedEvent) {
+      // If the tool claims it consumed the event, prevent further checks.
+      return;
+    }
+  }
+
+  // Don't stop propagation so that mouseDownActivate can handle the event
+}
+
+/**
+ * If there are multiple annotation tools, return the first one that isn't locked neither hidden.
+ * If there's only one annotation tool, return it
+ * @param annotationTools - An array of tools and annotation.
+ * @returns The candidate for selection
+ */
+function getAnnotationForSelection(
+  toolsWithMovableHandles: ToolAnnotationPair[]
+): ToolAnnotationPair {
+  return (
+    (toolsWithMovableHandles.length > 1 &&
+      toolsWithMovableHandles.find(
+        (item) =>
+          !isAnnotationLocked(item.annotation) &&
+          isAnnotationVisible(item.annotation.annotationUID)
+      )) ||
+    toolsWithMovableHandles[0]
+  );
+}
+
+/**
+ * If the annotation is selected, deselect it. If it's not selected, select it
+ * @param annotationUID - The AnnotationUID that we
+ * want to toggle the selection of.
+ * @param isMultiSelect - If true, the annotation. will be deselected if it is
+ * already selected, or deselected if it is selected.
+ */
+function toggleAnnotationSelection(
+  annotationUID: string,
+  isMultiSelect = false
+): void {
+  if (isMultiSelect) {
+    if (isAnnotationSelected(annotationUID)) {
+      setAnnotationSelected(annotationUID, false);
+    } else {
+      const preserveSelected = true;
+      setAnnotationSelected(annotationUID, true, preserveSelected);
+    }
+  } else {
+    const preserveSelected = false;
+    setAnnotationSelected(annotationUID, true, preserveSelected);
+  }
+}

package/src/eventDispatchers/mouseEventHandlers/mouseDownActivate.ts

@@ -0,0 +1,35 @@
+import { state } from '../../store';
+import getActiveToolForMouseEvent from '../shared/getActiveToolForMouseEvent';
+import { setAnnotationSelected } from '../../stateManagement/annotation/annotationSelection';
+import { EventTypes } from '../../types';
+
+/**
+ * If the `mouseDown` handler does not consume an event,
+ * activate the creation loop of the active tool, if one is found for the
+ * mouse button pressed.
+ *
+ * @param evt - The normalized mouseDown event.
+ */
+export default function mouseDownActivate(
+  evt: EventTypes.MouseDownActivateEventType
+) {
+  // If a tool has locked the current state it is dealing with an interaction within its own eventLoop.
+  if (state.isInteractingWithTool) {
+    return;
+  }
+
+  const activeTool = getActiveToolForMouseEvent(evt);
+
+  if (!activeTool) {
+    return;
+  }
+
+  if (state.isMultiPartToolActive) {
+    return;
+  }
+
+  if (activeTool.addNewAnnotation) {
+    const annotation = activeTool.addNewAnnotation(evt, 'mouse');
+    setAnnotationSelected(annotation.annotationUID);
+  }
+}

package/src/eventDispatchers/mouseEventHandlers/mouseDrag.ts

@@ -0,0 +1,25 @@
+import getActiveToolForMouseEvent from '../shared/getActiveToolForMouseEvent';
+import { state } from '../../store';
+import { MouseDragEventType } from '../../types/EventTypes';
+
+/**
+ * mouseDrag - Event handler for mouse drag events. Fires the `mouseDragCallback`
+ * function on active tools.
+ *
+ * @param evt - The normalized mouseDown event.
+ */
+export default function mouseDrag(evt: MouseDragEventType) {
+  if (state.isInteractingWithTool) {
+    return;
+  }
+
+  const activeTool = getActiveToolForMouseEvent(evt);
+
+  const noFoundToolOrDoesNotHaveMouseDragCallback =
+    !activeTool || typeof activeTool.mouseDragCallback !== 'function';
+  if (noFoundToolOrDoesNotHaveMouseDragCallback) {
+    return;
+  }
+
+  activeTool.mouseDragCallback(evt);
+}

package/src/eventDispatchers/mouseEventHandlers/mouseMove.ts

@@ -0,0 +1,70 @@
+// // State
+import { state } from '../../store';
+import { ToolModes } from '../../enums';
+
+// // Util
+import filterToolsWithAnnotationsForElement from '../../store/filterToolsWithAnnotationsForElement';
+import getToolsWithModesForMouseEvent from '../shared/getToolsWithModesForMouseEvent';
+import triggerAnnotationRender from '../../utilities/triggerAnnotationRender';
+import { MouseMoveEventType } from '../../types/EventTypes';
+
+const { Active, Passive } = ToolModes;
+
+/**
+ * mouseMove - On mouse move when not dragging, fire tools `mouseMoveCallback`s.
+ * This is mostly used to update the [un]hover state
+ * of a tool.
+ *
+ * @param evt - The normalized mouseDown event.
+ */
+export default function mouseMove(evt: MouseMoveEventType) {
+  // Tool interactions when mouse moved are handled inside each tool.
+  // This function is mostly used to update the [un]hover state
+  if (state.isInteractingWithTool || state.isMultiPartToolActive) {
+    return;
+  }
+
+  const activeAndPassiveTools = getToolsWithModesForMouseEvent(evt, [
+    Active,
+    Passive,
+  ]);
+
+  const eventDetail = evt.detail;
+  const { element } = eventDetail;
+
+  // Annotation tool specific
+  const toolsWithAnnotations = filterToolsWithAnnotationsForElement(
+    element,
+    activeAndPassiveTools
+  );
+
+  const toolsWithoutAnnotations = activeAndPassiveTools.filter((tool) => {
+    const doesNotHaveAnnotations = !toolsWithAnnotations.some(
+      (toolAndAnnotation) =>
+        toolAndAnnotation.tool.getToolName() === tool.getToolName()
+    );
+
+    return doesNotHaveAnnotations;
+  });
+
+  let annotationsNeedToBeRedrawn = false;
+
+  for (const { tool, annotations } of toolsWithAnnotations) {
+    if (typeof tool.mouseMoveCallback === 'function') {
+      annotationsNeedToBeRedrawn =
+        tool.mouseMoveCallback(evt, annotations) || annotationsNeedToBeRedrawn;
+    }
+  }
+
+  // Run mouse move handlers for non-annotation tools
+  toolsWithoutAnnotations.forEach((tool) => {
+    if (typeof tool.mouseMoveCallback === 'function') {
+      tool.mouseMoveCallback(evt);
+    }
+  });
+
+  // Annotation activation status changed, redraw the annotations
+  if (annotationsNeedToBeRedrawn === true) {
+    triggerAnnotationRender(element);
+  }
+}

package/src/eventDispatchers/mouseEventHandlers/mouseUp.ts

@@ -0,0 +1,9 @@
+import customCallbackHandler from '../shared/customCallbackHandler';
+
+/**
+ * mouseClick - Event handler for mouse up events. Uses `customCallbackHandler` to fire
+ * the `mouseUpCallback` function on active tools.
+ */
+const mouseUp = customCallbackHandler.bind(null, 'Mouse', 'mouseUpCallback');
+
+export default mouseUp;

package/src/eventDispatchers/mouseEventHandlers/mouseWheel.ts

@@ -0,0 +1,13 @@
+import customCallbackHandler from '../shared/customCallbackHandler';
+
+/**
+ * Event handler for mouse wheel events. Uses `customCallbackHandler` to fire
+ * the `mouseWheelCallback` function on active tools.
+ */
+const mouseWheel = customCallbackHandler.bind(
+  null,
+  'MouseWheel',
+  'mouseWheelCallback'
+);
+
+export default mouseWheel;

package/src/eventDispatchers/mouseToolEventDispatcher.ts

@@ -0,0 +1,64 @@
+import Events from '../enums/Events';
+
+import {
+  mouseClick,
+  mouseDown,
+  mouseDownActivate,
+  mouseDoubleClick,
+  mouseDrag,
+  mouseMove,
+  mouseUp,
+  mouseWheel,
+} from './mouseEventHandlers';
+
+/**
+ * Enable these listeners are emitted in order, and can be cancelled/prevented from bubbling
+ * by any previous event.
+ *
+ * @param element - The element to add the event listeners to.
+ */
+const enable = function (element: HTMLDivElement): void {
+  element.addEventListener(Events.MOUSE_CLICK, mouseClick as EventListener);
+  element.addEventListener(Events.MOUSE_DOWN, mouseDown as EventListener);
+  element.addEventListener(
+    Events.MOUSE_DOWN_ACTIVATE,
+    mouseDownActivate as EventListener
+  );
+  element.addEventListener(
+    Events.MOUSE_DOUBLE_CLICK,
+    mouseDoubleClick as EventListener
+  );
+  element.addEventListener(Events.MOUSE_DRAG, mouseDrag as EventListener);
+  element.addEventListener(Events.MOUSE_MOVE, mouseMove as EventListener);
+  element.addEventListener(Events.MOUSE_UP, mouseUp as EventListener);
+  element.addEventListener(Events.MOUSE_WHEEL, mouseWheel as EventListener);
+};
+
+/**
+ * Disable and Remove the MouseToolEventDispatcher handlers from the element.
+ *
+ * @param element - HTMLDivElement
+ */
+const disable = function (element: HTMLDivElement) {
+  element.removeEventListener(Events.MOUSE_CLICK, mouseClick as EventListener);
+  element.removeEventListener(Events.MOUSE_DOWN, mouseDown as EventListener);
+  element.removeEventListener(
+    Events.MOUSE_DOWN_ACTIVATE,
+    mouseDownActivate as EventListener
+  );
+  element.removeEventListener(
+    Events.MOUSE_DOUBLE_CLICK,
+    mouseDoubleClick as EventListener
+  );
+  element.removeEventListener(Events.MOUSE_DRAG, mouseDrag as EventListener);
+  element.removeEventListener(Events.MOUSE_MOVE, mouseMove as EventListener);
+  element.removeEventListener(Events.MOUSE_UP, mouseUp as EventListener);
+  element.removeEventListener(Events.MOUSE_WHEEL, mouseWheel as EventListener);
+};
+
+const mouseToolEventDispatcher = {
+  enable,
+  disable,
+};
+
+export default mouseToolEventDispatcher;

package/src/eventDispatchers/shared/customCallbackHandler.ts

@@ -0,0 +1,73 @@
+import { state, ToolGroupManager } from '../../store';
+import ToolModes from '../../enums/ToolModes';
+
+const { Active } = ToolModes;
+
+/**
+ * @function customCallbackHandler This is used as a generic event handler for tool events
+ * on viewports. It:
+ *
+ * - Finds an "active" tool with:
+ *    - A matching `handlerType`
+ *    - A matching `customFunction` on its tool instance
+ *
+ * Then calls that custom function with raised event.
+ *
+ * @param handlerType - 'Mouse' | 'Touch' | 'MouseWheel'
+ * @param customFunction - Function name that's expected to live on implementing
+ *   (and event handling) active tool ex. 'doubleClickCallback'
+ * @param evt
+ */
+export default function customCallbackHandler(
+  handlerType: string,
+  customFunction: string,
+  evt
+) {
+  if (state.isInteractingWithTool) {
+    return false;
+  }
+
+  const { renderingEngineId, viewportId } = evt.detail;
+  const toolGroup = ToolGroupManager.getToolGroupForViewport(
+    viewportId,
+    renderingEngineId
+  );
+
+  if (!toolGroup) {
+    return false;
+  }
+
+  // TODO: Filter tools by interaction type?
+  /**
+   * Iterate tool group tools until we find a tool that is:
+   * - active
+   * - has the custom callback function
+   *
+   */
+  let activeTool;
+  const toolGroupToolNames = Object.keys(toolGroup.toolOptions);
+
+  for (let j = 0; j < toolGroupToolNames.length; j++) {
+    const toolName = toolGroupToolNames[j];
+    const tool = toolGroup.toolOptions[toolName];
+    // TODO: Should be getter
+    const toolInstance = toolGroup.getToolInstance(toolName);
+
+    if (
+      // TODO: Should be enum?
+      tool.mode === Active &&
+      // TODO: Should be implements interface?
+      // Weird that we need concrete instance. Other options to filter / get callback?
+      typeof toolInstance[customFunction] === 'function'
+    ) {
+      activeTool = toolGroup.getToolInstance(toolName);
+      break;
+    }
+  }
+
+  if (!activeTool) {
+    return;
+  }
+
+  activeTool[customFunction](evt);
+}

package/src/eventDispatchers/shared/getActiveToolForKeyboardEvent.ts

@@ -0,0 +1,58 @@
+import { ToolGroupManager } from '../../store';
+import { ToolModes, MouseBindings } from '../../enums';
+import { keyEventListener } from '../../eventListeners';
+import { EventTypes } from '../../types';
+import { getMouseButton } from '../../eventListeners/mouse/mouseDownListener';
+
+const { Active } = ToolModes;
+
+/**
+ * Iterate tool group tools until we find a tool that has a "ToolBinding"
+ * that matches our Keyboard pressed keys. It's possible there will be no match
+ * (no active tool for that mouse button combination).
+ *
+ * @param evt - The normalized keyboard event.
+ *
+ * @returns tool
+ */
+export default function getActiveToolForKeyboardEvent(
+  evt: EventTypes.KeyDownEventType
+) {
+  const { renderingEngineId, viewportId } = evt.detail;
+
+  // Get the current mouse button clicked
+  const mouseButton = getMouseButton();
+
+  // If any keyboard modifier key is also pressed
+  const modifierKey = keyEventListener.getModifierKey();
+
+  const toolGroup = ToolGroupManager.getToolGroupForViewport(
+    viewportId,
+    renderingEngineId
+  );
+
+  if (!toolGroup) {
+    return null;
+  }
+
+  const toolGroupToolNames = Object.keys(toolGroup.toolOptions);
+
+  for (let j = 0; j < toolGroupToolNames.length; j++) {
+    const toolName = toolGroupToolNames[j];
+    const toolOptions = toolGroup.toolOptions[toolName];
+
+    // tool has binding that matches the mouse button, if mouseEvent is undefined
+    // it uses the primary button
+    const correctBinding =
+      toolOptions.bindings.length &&
+      toolOptions.bindings.some(
+        (binding) =>
+          binding.mouseButton === (mouseButton ?? MouseBindings.Primary) &&
+          binding.modifierKey === modifierKey
+      );
+
+    if (toolOptions.mode === Active && correctBinding) {
+      return toolGroup.getToolInstance(toolName);
+    }
+  }
+}

package/src/eventDispatchers/shared/getActiveToolForMouseEvent.ts

@@ -0,0 +1,61 @@
+import { ToolGroupManager } from '../../store';
+import { MouseBindings, ToolModes } from '../../enums';
+import { keyEventListener } from '../../eventListeners';
+import { EventTypes } from '../../types';
+import getMouseModifier from './getMouseModifier';
+
+const { Active } = ToolModes;
+
+/**
+ * Iterate tool group tools until we find a tool that has a "ToolBinding"
+ * that matches our MouseEvent's `buttons`. It's possible there will be no match
+ * (no active tool for that mouse button combination).
+ *
+ * @param evt - The event dispatcher mouse event.
+ *
+ * @returns tool
+ */
+export default function getActiveToolForMouseEvent(
+  evt: EventTypes.NormalizedMouseEventType
+) {
+  // Todo: we should refactor this to use getToolsWithModesForMouseEvent instead
+  const { renderingEngineId, viewportId } = evt.detail;
+  const mouseEvent = evt.detail.event;
+
+  // If any keyboard modifier key is also pressed
+  // Use the actual key if set, otherwise get the key from the mouse event.
+  const modifierKey =
+    keyEventListener.getModifierKey() || getMouseModifier(mouseEvent);
+
+  const toolGroup = ToolGroupManager.getToolGroupForViewport(
+    viewportId,
+    renderingEngineId
+  );
+
+  if (!toolGroup) {
+    return null;
+  }
+
+  const toolGroupToolNames = Object.keys(toolGroup.toolOptions);
+
+  for (let j = 0; j < toolGroupToolNames.length; j++) {
+    const toolName = toolGroupToolNames[j];
+    const toolOptions = toolGroup.toolOptions[toolName];
+
+    // tool has binding that matches the mouse button, if mouseEvent is undefined
+    // it uses the primary button
+    const correctBinding =
+      toolOptions.bindings.length &&
+      toolOptions.bindings.some((binding) => {
+        return (
+          binding.mouseButton ===
+            (mouseEvent ? mouseEvent.buttons : MouseBindings.Primary) &&
+          binding.modifierKey === modifierKey
+        );
+      });
+
+    if (toolOptions.mode === Active && correctBinding) {
+      return toolGroup.getToolInstance(toolName);
+    }
+  }
+}