API Docs

Class: UserModeHandler

PD. UserModeHandler

Provides the infrastructure for handling user interaction with a model.

Subclasses of this class are used to handle the various interactive user modes defined in PD.MODE. References or instances of each class are automatically added to the central registry, but you can override them with your own custom handlers at any time using PD.Registry.registerUserModeHandler. You can obtain the current handler using PD.Registry.getUserModeHandler.

The role of the user mode handler is to process any user interaction with the model whilst it is currently set. This process basically means handling sequences of events that are generated by the scene and selection managers when reacting to user input, and returning values that let them know if it has been handled.

These event handling methods are all optional. If not implemented by a particular user mode handler class, they will not be called by the host selection manager.

The event sequence and corresponding methods are as follows:

  • Pointer Down: handlePreSelect()
    This is called when the pointer is first pressed within a clear area of the model (not on a 3D model cursor) and it is not yet obvious whether the user wants to select something in the model or manipulate the view. The role of this method is to give some visual indication of what would happen in the model if the user subsequently releases the pointer without dragging. The method should return true if your handler would like to be notified if/when that subsequently occurs.

  • Pointer Drag: handlePreSelectClear()
    This is called if the user subsequently drags the pointer after pressing it in a clear area of the model. This indicates that the user wants to manipulate the model view so, after calling this method, the scene manager takes over to manage either region selection or view manipulation.

  • Pointer Release: handleClickSelect()
    This is called when the user releases the pointer without dragging after pressing it in a clear area of the model. This indicates that the user wants to click-select or do whatever was indicated during pre-selection, so this method typically accepts the current pre-selection and either adds to, removes from or sets it as the current selection set.

  • Cursor Drag Start: handleDragStart()
    This is called when the user has pressed the pointer on one of the 3D model cursor manipulators and the very first drag event has been detected. It is called only once at the very start of the drag sequence and immediately before the first call to handleDragMove().

  • Cursor Drag Move: handleDragMove()
    This is called multiple times whenever the pointer is moved whilst pressing down on one of the 3D model cursor manipulators. The role of this method is to process the cursor movement and apply whatever changes are required to the selection set or model.

  • Cursor Drag End: handleDragEnd()
    This is called when the user releases the pointer after it was dragged whilst pressing down on one of the 3D model cursor manipulators. The role of this method is to finalise the cursor movement and remove any additional scene overlays such as interactive dimensions and snap point indicators. It is also an opportunity to initiate more detailed processing that there may not have been time to perform during the interactive drag.

The edit mode handler also offers an opportunity to display dimension overlays during cursor drag events by implementing a displayDimensions() method. This method cannot be called directly as it must use a mesh that is managed by the host selection manager. However, you can call it indirectly at anytime within the handleDragMove() method by calling host.updateDisplayedDimensions().

new UserModeHandler()

Author:
  • drajmarsh
Example
const original_handler = PD.Registry.getUserModeHandler(PD.MODE.EDIT);
PD.Registry.registerUserModeHandler(PD.MODE.EDIT, MyCustomUserModelHandlerClass);
/// ...

/// When done, reset to the original.
PD.Registry.registerUserModeHandler(PD.MODE.EDIT, original_handler);

Classes

Capture
None
WorkPlane

Members

:boolean

isUserModeHandler <readonly>

A flag identifying this object as an edit mode handler.

Type
  • boolean

Methods

cancel(host)

Cancels this edit mode.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.

complete(host)

Completes any pending modal action(s) in this edit mode.

If this is a multi-stage action and it is still within the setup stages, this method should perform any cleanup actions that may be required to cancel out, then reset the user mode to the default edit mode and return false.

If setup stages are over, the user mode should perform whatever actions are required to complete or finalise the action, reset the user mode to the default edit mode and return true.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.
Returns:

Returns true if a pending action was completed.

Type
boolean

displayDimensions(host, mesh)

Regenerates dimension lines associated with this action, if any.

This method is called when the host selection manager is updating the model view after something has changed. The role of this method is to add whatever dimensions are associated with this action to the given dimension mesh.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.
mesh PD.PolyMesh

The mesh to add the dimension(s) to.
Returns:

Returns true if something in the model was dimensioned and the mesh should be visible, otherwise false.

Type
boolean

handleClickSelect(host, raycaster, event)

Handle interactive click/tap selection events in the canvas.

This method is called when the user has clicked/tapped and released the pointer within the model canvas without dragging, but away from the 3D cursor.

For actions that have one or more initial setup stages (such as a rotation that first needs an origin and then a reference point to rotate from), this method typically checks whether the host.userActionStage is still within setup and, if so, progresses it to the next stage and returns true.

If setup stages are over and the action is completed, the user mode should be returned to the default edit mode and the method should return false.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.
raycaster THREE.Raycaster

The ray cast into the current scene.
event object

The DOM event that triggered this selection.
Returns:

Returns true if something in the model was selected and geometry was added to the mesh, otherwise false.

Type
boolean

handleDragEnd(host, cursor, event)

Complete the action when the 3D cursor drag has finished.

This method is called when the user interactively releases the pointer after dragging the 3D cursor in the model canvas.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.
cursor PD.Cursor

The cursor that just finished moving.
event object

The DOM event that triggered the end of the move.
Returns:

Returns true if the move was finalised.

Type
boolean

handleDragMove(host, newPos, cursor, event)

Update the action as the 3D cursor is interactively dragged.

This method is called multiple times as the user interactively drags the 3D cursor in the model canvas with the pointer down.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.
newPos THREE.Vector3

The proposed new position of the cursor.
cursor PD.Cursor

The cursor that moved.
event object

The DOM event that triggered this move.
Returns:

Returns true if the move was applied.

Type
boolean

handleDragStart(host, cursor, event)

Prepare the action just prior to a 3D cursor drag event.

This method is called when the user has clicked/tapped the pointer on one of the active cursor manipulators in the model canvas and has just begun to drag with the pointer down.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.
cursor PD.Cursor

The cursor that is about to move.
event object

The DOM event that triggered this move.
Returns:

Returns true if the move is allowed.

Type
boolean

handlePreSelect(host, raycaster, event)

Handle interactive pre-selection events within the model canvas.

This method is called when the user first clicks/taps within the model canvas, but away from the 3D cursor. At this stage, the system doesn't yet know whether the user intends to select something in the model or is simply trying to pan or rotate the view. Thus, the role of this method is to provide some visual feedback to indicate what would be selected if the user were to release the pointer without dragging.

For actions that have one or more initial setup stages (such as a rotation that first needs an origin and then a reference point to rotate from), this method typically checks whether the host.userActionStage is still within setup and, if so, positions the 3D cursor at the position at the clicked point on the cursor plane, ready to be dragged into position.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.
raycaster THREE.Raycaster

The ray cast into the current scene.
event object

The DOM event that triggered this callback.
Returns:

Returns true if something in the model was pre-selected and geometry was added to the mesh, otherwise false.

Type
boolean

initialise(host)

Called each time this edit mode is entered.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.

progressToNextStage(host [, stage])

Increments through the stages of an interactive process.

This method should do whatever is required to end the previous stage and transition to the next stage in a multi-stage action.

Parameters:
Name Type Argument Description
host PD.SelectionManager

The selection manager.
stage number <optional>

An optional stage in the progress, defaults to -1.

setCursorPosition(host, pos [, event])

Manually sets the cursor position during an action.

This method is called when the user manually edits the cursor position using the keyboard or other numeric input within the UI, as opposed to dragging the cursor. It is not called when the cursor is moved interactively using the manipulators and a pointer.

This method should undertake whatever action dragging the cursor would have at the current progress stage.

Parameters:
Name Type Argument Description
host PD.SelectionManager

The selection manager.
pos Object | Array

The new position to move the cursor to.
event Event <optional>

The event that invoked this method.

dimensionCurrentSelection(host, mesh) <static>

A utility method to dimension the current selection set.

This will update dimensions on either the selected junction, path segment or element.

Parameters:
Name Type Description
host PD.SelectionManager

The selection manager.
mesh PD.PolyMesh

The mesh to add the dimension(s) to.

isUserModeHandlerClass() <static>

Indicates that this is an edit mode class rather than instance.