DragSelect

From HEWIKI
Jump to: navigation, search

Contents


Overview

Sample marquee selection visualization
Some game designs allow the player to marquee-select multiple objects in order to facilitate making complex commands. Examples of this might include group unit selection in an RTS, where each unit is added to the selection group in real-time as it is enclosed within the selection rectangle. To support this behavior, HeroEngine provides a flexible marquee selection framework that allows a developer to visualize the marquee selection process, respond to individual selection events, and act on a final set of selected nodes once the process is complete.

What Problem(s) Does DragSelect Solve?

What Problem(s) Does DragSelect Not Solve

Usage

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(...).

Extending

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.

Methods

$INPUT

// 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)

_AbstractInputDragSelectionListener

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)
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox