What Problem(s) Does DragSelect Solve?
- Provides a framework for enacting and visualizing the marquee selection of multiple nodes
- Allows you to select nodes in screen-space, projecting your selection onto the nodes situated in your 3D scene.
- Allows you to generate and respond to events on selection, deselection, marquee update, begin selection, and end selection.
What Problem(s) Does DragSelect Not Solve
- Does not inherently 'do' anything with your selections (this is the responsibility of the game developer)
The default marquee selection interface is implemented on the client $INPUT system node in combination with the "DragSelectButton" command (CTRL+RIGHT_BUTTON, by default) of the HE_Mouse input layer. Entering marquee selection mode involves making a call to $INPUT._InputDoDragSelectBegin(), while leaving it involves making a call to $INPUT._InputDoDragSelectEnd().
Upon entering marquee selection mode, a GUIControl is displayed on-screen which visualizes the current screen-space selection area. This control is retrieved by making a call to $INPUT._GetDragSelectConrol(), which can be overridden to provide your own game-specific selection control.
At this point, any mouse movement will trigger a callback to $INPUT._OnDragSelectPositionChanged(...) and - per the default implementation - cause the visualization GUIControl to resize appropriately. In addition, any nodes newly detected to be within the projection of the marquee selection rectangle onto the 3D scene (i.e. anything visibly contained within the selection rectangle) will make a callback to $INPUT._OnDragSelectModeNodeSelected(...); nodes that once were within the selection rectangle but are no longer present will make a callback to $INPUT._OnDragSelectModeNodeUnselected(...).
Finally, any node which implements the _AbstractInputDragSelectionListener interface may register to receive marquee selection events by calling $INPUT._AddDragSelectEventListener(...). Conversely, any node which is no longer interested in marquee selection events may stop receiving them by calling $INPUT._RemoveDragSelectEventListener(...).
There are several ways of extending or overriding the default marquee selection implementation.
Modifying Entry To / Exit From DragSelect Mode
By default, marquee selection mode is enabled and disabled as a result of the command "DragSelectButton" being passed to the _Input_Mouse script, which then calls $INPUT._InputDoDragSelectBegin/End. This command can be modified, overridden or removed by modifying GameKeyBindings.ini. Additionally, you may trigger marquee selection mode at any time by manually making a call to $INPUT._InputDoDragSelectBegin() from any script (and ending it with $INPUT._InputDoDragSelectEnd().
Changing the Default DragSelect GUIControl
The method $INPUT._GetDragSelectConrol() may be overridden to provide your own custom marquee selection control. This control must inherit from _AbstractInputDragSelectionListener and implement the interface.
Changing the Selection Logic
Overriding the $INPUT._OnDragSelectModeNodeSelected(...) method will allow custom selection logic to be applied. If the node detected is of the type you wish to select, return 'true'. If not, return 'false'. By default, all nodes detected will be selected, though this may be changed in an override.
// Registers a node to receive callbacks for DragSelect events. This node must inherit from // the _AbstractInputDragSelectionListener class. method _AddDragSelectEventListener(listener as NodeRef of Class _AbstractInputDragSelectionListener) // Unregisters a node which had previously been registered to receive callbacks for DragSelect events. method _RemoveDragSelectEventListener(listener as NodeRef of Class _AbstractInputDragSelectionListener) // Gets the default DragSelect GUIControl which will be rendered during DragSelect operations. // The returned control must inherit from _AbstractInputDragSelectionListener. method _GetDragSelectControl() as NodeRef of Class GUIControl // Toggles DragSelect mode ON and notifies all DragSelect listeners of the event. unique method _InputDoDragSelectBegin() // Toggles DragSelect mode OFF and notifies all DragSelect listeners of the event. method _InputDoDragSelectEnd() // C++ callback made when DragSelect mode is ON and the position of the mouse has changed unique method _OnDragSelectPositionChanged(selection as Class rectangle) // C++ callback made when DragSelect mode is ON and an HBNode that is not currently a member of // the 'selected nodes' list falls within the selection area. unique method _OnDragSelectModeNodeSelected(selected_node as NodeRef of Class HBNode) as Boolean // C++ callback made when DragSelect mode is ON and an HBNode that is currently a member of // the 'selected nodes' list no longer falls within the selection area. unique method _OnDragSelectModeNodeUnselected(unselected_node as NodeRef of Class HBNode)
method _DragSelectModeOnBegin() method _DragSelectModeOnEnd(selectedNodes as List of NodeRef) method _DragSelectOnPositionChanged(selection as Class rectangle) method _DragSelectModeOnNodeSelected(selected_node as NodeRef) method _DragSelectModeOnNodeUnselected(unselected_node as NodeRef)