Package org.eclipse.gef.tools

# Class MarqueeSelectionTool

java.lang.Object
org.eclipse.gef.util.FlagSupport
org.eclipse.gef.tools.AbstractTool
org.eclipse.gef.tools.MarqueeSelectionTool

All Implemented Interfaces:
  `RequestConstants`, `Tool`

Direct Known Subclasses:
  `MarqueeDragTracker`

public class MarqueeSelectionTool extends AbstractTool
A Tool which selects multiple `EditPart`s inside a rectangular area of a Graphical Viewer. Selection behavior can be configured by selecting (via `setMarqueeBehavior(int)`) one of six supported marquee behaviors, which are:

- `BEHAVIOR_NODES_CONTAINED`
- `BEHAVIOR_NODES_TOUCHED`
- `BEHAVIOR_CONNECTIONS_CONTAINED`
- `BEHAVIOR_CONNECTIONS_TOUCHED`
- `BEHAVIOR_NODES_CONTAINED_AND_RELATED_CONNECTIONS`
- `BEHAVIOR_NODES_TOUCHED_AND_RELATED_CONNECTIONS`

By default, only edit parts whose figure's are on the primary layer that are fully enclosed in the marquee selection rectangle will be considered ( `BEHAVIOR_NODES_CONTAINED`). Besides different marquee behaviors, the tool supports different modes, which the user can influence by pressing modifier keys at the beginning of the drag operation. I.e. if the SHIFT key is pressed at the beginning of the drag, the enclosed items will be appended to the current viewer selection. If the MOD1 key is pressed at the beginning of the drag, the enclosed items will have their selection state inverted.

## Nested Class Summary

## Nested classes/interfaces inherited from class org.eclipse.gef.tools.AbstractTool

`AbstractTool.Input`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`BEHAVIOR_CONNECTIONS_CONTAINED`
This behavior selects connections that intersect the marquee rectangle.
`static final int`
`BEHAVIOR_CONNECTIONS_TOUCHED`
This behavior selects connections that intersect the marquee rectangle.
`static final int`
`BEHAVIOR_NODES_AND_CONNECTIONS`
Deprecated.
use `BEHAVIOR_NODES_CONTAINED_AND_RELATED_CONNECTIONS` instead.
`static final int`
`BEHAVIOR_NODES_CONTAINED`
This behavior selects nodes completely encompassed by the marquee rectangle.
`static final int`
`BEHAVIOR_NODES_CONTAINED_AND_RELATED_CONNECTIONS`
This behavior selects nodes completely encompassed by the marquee rectangle, and all connections between those nodes.
`static final int`
`BEHAVIOR_NODES_TOUCHED`
This behavior selects nodes that intersect the marquee rectangle.
`static final int`
`BEHAVIOR_NODES_TOUCHED_AND_RELATED_CONNECTIONS`
This behavior selects nodes that intersect the marquee rectangle.
`static final int`
`DEFAULT_MARQUEE_BEHAVIOR`
Constant defining the default marquee selection behavior.
`static final Object`
`PROPERTY_MARQUEE_BEHAVIOR`
The property to be used in `AbstractTool.setProperties(java.util.Map)` for `setMarqueeBehavior(int)`.

### Fields inherited from class org.eclipse.gef.tools.AbstractTool

`MAX_FLAG, MAX_STATE, MOUSE_BUTTON_ANY, MOUSE_BUTTON1, MOUSE_BUTTON2, MOUSE_BUTTON3, PROPERTY_UNLOAD_WHEN_FINISHED, STATE_ACCESSIBLE_DRAG, STATE_ACCESSIBLE_DRAG_IN_PROGRESS, STATE_DRAG, STATE_DRAG_IN_PROGRESS, STATE_INITIAL, STATE_INVALID, STATE_TERMINAL`

### Fields inherited from interface org.eclipse.gef.RequestConstants

`REQ_ADD, REQ_ALIGN, REQ_ALIGN_CHILDREN, REQ_CLONE, REQ_CONNECTION_END, REQ_CONNECTION_START, REQ_CREATE, REQ_CREATE_BENDPOINT, REQ_DELETE, REQ_DELETE_DEPENDANT, REQ_DIRECT_EDIT, REQ_MOVE, REQ_MOVE_BENDPOINT, REQ_MOVE_CHILDREN, REQ_OPEN, REQ_ORPHAN, REQ_ORPHAN_CHILDREN, REQ_RECONNECT_SOURCE, REQ_RECONNECT_TARGET, REQ_RESIZE, REQ_RESIZE_CHILDREN, REQ_SELECTION, REQ_SELECTION_HOVER`

## Constructor Summary

Constructors
Constructor
Description
`MarqueeSelectionTool()`
Creates a new MarqueeSelectionTool of default type `BEHAVIOR_NODES_CONTAINED`.

## Method Summary

Modifier and Type
Method
Description
`protected void`
`applyProperty(Object key, Object value)`
This method is invoked from `AbstractTool.setProperties(Map)`.
`protected Collection<? extends GraphicalEditPart>`
`calculateMarqueeSelectedEditParts()`
Called from `performMarqueeSelect()` to determine those `GraphicalEditPart`s that are affected by the current marquee selection.
`protected org.eclipse.draw2d.IFigure`
`createMarqueeRectangleFigure()`
create a new marquee rectangle feedback figure Sub classes my provide their own feedback rectangle
`void`
`deactivate()`
Erases feedback if necessary and puts the tool into the terminal state.
`protected String`
`getCommandName()`
Returns the identifier of the command that is being sought.
`protected org.eclipse.draw2d.geometry.Rectangle`
`getCurrentMarqueeSelectionRectangle()`
Returns the current marquee selection rectangle.
`protected int`
`getCurrentSelectionMode()`
Returns the current selection mode, i.e. default, append, or toggle
`protected String`
`getDebugName()`
Returns the debug name for this tool.
`protected boolean`
`handleButtonDown(int button)`
Called when the mouse button has been pressed.
`protected boolean`
`handleButtonUp(int button)`
Called when the mouse button has been released.
`protected boolean`
`handleDragInProgress()`
Called whenever a mouse is being dragged and the drag threshold has been exceeded.
`protected boolean`
`handleFocusLost()`
Handles high-level processing of a focus lost event.
`protected boolean`
`handleInvalidInput()`
This method is called when mouse or keyboard input is invalid and erases the feedback.
`protected boolean`
`handleKeyDown(KeyEvent e)`
Handles high-level processing of a key down event.
`protected boolean`
`isMarqueeSelectable(GraphicalEditPart editPart)`
Decides whether the given edit part may potentially be included in the current marquee selection.
`protected boolean`
`isViewerImportant(EditPartViewer viewer)`
MarqueeSelectionTool is only interested in GraphicalViewers, not TreeViewers.
`protected void`
`performMarqueeSelect()`
Calculates and sets a new viewer selection based on the current marquee selection.
`void`
`setMarqueeBehavior(int type)`
Sets the type of parts that this tool will select.
`void`
`setViewer(EditPartViewer viewer)`
Sets the active EditPartViewer.

### Methods inherited from class org.eclipse.gef.tools.AbstractTool

`acceptArrowKey, accGetStep, accStepIncrement, accStepReset, activate, addFeedback, calculateCursor, commitDrag, createOperationSet, debug, executeCommand, executeCurrentCommand, focusGained, focusLost, getCommand, getCurrentCommand, getCurrentInput, getCurrentViewer, getDebugNameForState, getDefaultCursor, getDisabledCursor, getDomain, getDragMoveDelta, getLocation, getOperationSet, getStartLocation, getState, handleCommandStackChanged, handleDoubleClick, handleDrag, handleDragStarted, handleFinished, handleFocusGained, handleHover, handleKeyTraversed, handleKeyUp, handleMove, handleNativeDragFinished, handleNativeDragStarted, handleViewerEntered, handleViewerExited, isActive, isHoverActive, isInState, keyDown, keyTraversed, keyUp, mouseDoubleClick, mouseDown, mouseDrag, mouseHover, mouseMove, mouseUp, mouseWheelScrolled, movedPastThreshold, nativeDragFinished, nativeDragStarted, performViewerMouseWheel, placeMouseInViewer, reactivate, refreshCursor, releaseToolCapture, removeFeedback, resetFlags, setCurrentCommand, setCursor, setDefaultCursor, setDisabledCursor, setEditDomain, setHoverActive, setProperties, setStartLocation, setState, setToolCapture, setUnloadWhenFinished, stateTransition, unloadWhenFinished, viewerEntered, viewerExited`

### Methods inherited from class org.eclipse.gef.util.FlagSupport

`getFlag, setFlag`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### BEHAVIOR_CONNECTIONS_CONTAINED

public static final int BEHAVIOR_CONNECTIONS_CONTAINED
This behavior selects connections that intersect the marquee rectangle.

Since:
  3.7
See Also:
  - Constant Field Values

### BEHAVIOR_CONNECTIONS_TOUCHED

public static final int BEHAVIOR_CONNECTIONS_TOUCHED
This behavior selects connections that intersect the marquee rectangle.

Since:
  3.1
See Also:
  - Constant Field Values

### BEHAVIOR_NODES_CONTAINED

public static final int BEHAVIOR_NODES_CONTAINED
This behavior selects nodes completely encompassed by the marquee rectangle. This is the default behavior for this tool.

Since:
  3.1
See Also:
  - Constant Field Values

### BEHAVIOR_NODES_CONTAINED_AND_RELATED_CONNECTIONS

public static final int BEHAVIOR_NODES_CONTAINED_AND_RELATED_CONNECTIONS
This behavior selects nodes completely encompassed by the marquee rectangle, and all connections between those nodes.

Since:
  3.7
See Also:
  - Constant Field Values

### BEHAVIOR_NODES_TOUCHED

public static final int BEHAVIOR_NODES_TOUCHED
This behavior selects nodes that intersect the marquee rectangle.

Since:
  3.7
See Also:
  - Constant Field Values

### BEHAVIOR_NODES_TOUCHED_AND_RELATED_CONNECTIONS

public static final int BEHAVIOR_NODES_TOUCHED_AND_RELATED_CONNECTIONS
This behavior selects nodes that intersect the marquee rectangle.

Since:
  3.7
See Also:
  - Constant Field Values

### BEHAVIOR_NODES_AND_CONNECTIONS

@Deprecated public static final int BEHAVIOR_NODES_AND_CONNECTIONS
Deprecated.
use `BEHAVIOR_NODES_CONTAINED_AND_RELATED_CONNECTIONS` instead.
This behavior selects nodes completely encompassed by the marquee rectangle, and all connections between those nodes.

Since:
  3.1
See Also:
  - Constant Field Values

### PROPERTY_MARQUEE_BEHAVIOR

public static final Object PROPERTY_MARQUEE_BEHAVIOR
The property to be used in `AbstractTool.setProperties(java.util.Map)` for `setMarqueeBehavior(int)`.

### DEFAULT_MARQUEE_BEHAVIOR

public static final int DEFAULT_MARQUEE_BEHAVIOR
Constant defining the default marquee selection behavior.

Since:
  3.7
See Also:
  - Constant Field Values

## Constructor Details

### MarqueeSelectionTool

public MarqueeSelectionTool()
Creates a new MarqueeSelectionTool of default type `BEHAVIOR_NODES_CONTAINED`.

## Method Details

### applyProperty

protected void applyProperty(Object key, Object value)
Description copied from class: `AbstractTool`
This method is invoked from `AbstractTool.setProperties(Map)`. Sub-classes can override to add support for more properties. This method should fail silently in case of any error.

AbstractTool uses introspection to match any keys with properties. For instance, the key "defaultCursor" would lead to the invocation of `AbstractTool.setDefaultCursor(Cursor)` with the provided value.

Overrides:
  `applyProperty` in class `AbstractTool`
Parameters:
  `key` - the key; may be `null`
  `value` - the new value
See Also:
  - `AbstractTool.applyProperty(java.lang.Object, java.lang.Object)`

### calculateMarqueeSelectedEditParts

protected Collection<? extends GraphicalEditPart> calculateMarqueeSelectedEditParts()
Called from `performMarqueeSelect()` to determine those `GraphicalEditPart`s that are affected by the current marquee selection. In default and append mode, the edit parts returned here will become selected in the current viewer's new selection (which is calculated and set in `performMarqueeSelect()`), while in toggle mode their selection state will be inverted. Calculation is delegated to `calculatePrimaryMarqueeSelectedEditParts()` and `calculateSecondaryMarqueeSelectedEditParts(Collection)` to compute the set of marquee selected edit parts in a two step-process, where all directly affected edit parts are determined first, and those indirectly affected (related connections in case of `BEHAVIOR_NODES_TOUCHED_AND_RELATED_CONNECTIONS`, or `BEHAVIOR_NODES_CONTAINED_AND_RELATED_CONNECTIONS`) afterwards. Clients may overwrite to customize the calculation of marquee selected edit parts.

Returns:
  A collection containing all GraphicalEditPart that should be regarded as being included in the current marquee selection, i.e. which should get selected in default or append mode, and whose selection state should get inverted in toggle mode.
Since:
  3.7

### deactivate

public void deactivate()
Erases feedback if necessary and puts the tool into the terminal state.

Specified by:
  `deactivate` in interface `Tool`
Overrides:
  `deactivate` in class `AbstractTool`
See Also:
  - `AbstractTool.activate()`

### getCommandName

protected String getCommandName()
Description copied from class: `AbstractTool`
Returns the identifier of the command that is being sought. This name is also the named that will be logged in the debug view.

Specified by:
  `getCommandName` in class `AbstractTool`
Returns:
  the identifier for the command
See Also:
  - `AbstractTool.getCommandName()`

### getCurrentMarqueeSelectionRectangle

protected org.eclipse.draw2d.geometry.Rectangle getCurrentMarqueeSelectionRectangle()
Returns the current marquee selection rectangle.

Returns:
  A `Rectangle` representing the current marquee selection.
Since:
  3.7

### getCurrentSelectionMode

protected int getCurrentSelectionMode()
Returns the current selection mode, i.e. default, append, or toggle

Returns:
  on of `DEFAULT_MODE`, `APPEND_MODE`, or `TOGGLE_MODE`
Since:
  3.7

### getDebugName

protected String getDebugName()
Description copied from class: `AbstractTool`
Returns the debug name for this tool.

Overrides:
  `getDebugName` in class `AbstractTool`
Returns:
  the debug name
See Also:
  - `AbstractTool.getDebugName()`

### createMarqueeRectangleFigure

protected org.eclipse.draw2d.IFigure createMarqueeRectangleFigure()
create a new marquee rectangle feedback figure Sub classes my provide their own feedback rectangle

Since:
  3.13

### handleButtonDown

protected boolean handleButtonDown(int button)
Description copied from class: `AbstractTool`
Called when the mouse button has been pressed. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the meaning of a mouse down. Returning `true` indicates that the button down was handled in some way.

Overrides:
  `handleButtonDown` in class `AbstractTool`
Parameters:
  `button` - which button went down
Returns:
  `true` if the buttonDown was handled
See Also:
  - `AbstractTool.handleButtonDown(int)`

### handleButtonUp

protected boolean handleButtonUp(int button)
Description copied from class: `AbstractTool`
Called when the mouse button has been released. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the mouse up. Returning `true` indicates that the mouse up was handled in some way.

Overrides:
  `handleButtonUp` in class `AbstractTool`
Parameters:
  `button` - the button being released
Returns:
  `true` if the button up was handled
See Also:
  - `AbstractTool.handleButtonUp(int)`

### handleDragInProgress

protected boolean handleDragInProgress()
Description copied from class: `AbstractTool`
Called whenever a mouse is being dragged and the drag threshold has been exceeded. Prior to the drag threshold being exceeded, only `AbstractTool.handleDrag()` is called. This method gets called repeatedly for every mouse move during the drag. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the drag. Returning `true` indicates that the drag was handled.

Overrides:
  `handleDragInProgress` in class `AbstractTool`
Returns:
  `true` if the drag was handled
See Also:
  - `AbstractTool.handleDragInProgress()`

### handleFocusLost

protected boolean handleFocusLost()
Description copied from class: `AbstractTool`
Handles high-level processing of a focus lost event. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the focus lost event. Return `true` to indicate that the event was processed.

Overrides:
  `handleFocusLost` in class `AbstractTool`
Returns:
  `true` if the event was handled
See Also:
  - `AbstractTool.handleFocusLost()`

### handleInvalidInput

protected boolean handleInvalidInput()
This method is called when mouse or keyboard input is invalid and erases the feedback.

Overrides:
  `handleInvalidInput` in class `AbstractTool`
Returns:
  `true`

### handleKeyDown

protected boolean handleKeyDown(KeyEvent e)
Handles high-level processing of a key down event. KeyEvents are forwarded to the current viewer's `KeyHandler`, via `KeyHandler.keyPressed(KeyEvent)`.

Overrides:
  `handleKeyDown` in class `AbstractTool`
Parameters:
  `e` - the key event
Returns:
  `true` if the key down was handled.
See Also:
  - `AbstractTool.handleKeyDown(KeyEvent)`

### isMarqueeSelectable

protected boolean isMarqueeSelectable(GraphicalEditPart editPart)
Decides whether the given edit part may potentially be included in the current marquee selection.

Parameters:
  `editPart` - the `EditPart` of interest
Returns:
  `true` if the given edit part may be included into the marquee selection, `false` otherwise
Since:
  3.7

### isViewerImportant

protected boolean isViewerImportant(EditPartViewer viewer)
MarqueeSelectionTool is only interested in GraphicalViewers, not TreeViewers.

Overrides:
  `isViewerImportant` in class `AbstractTool`
Parameters:
  `viewer` - the viewer where the event occured
Returns:
  `true` if this tool is interested in events occuring in the given viewer; `false` otherwise
See Also:
  - `AbstractTool.isViewerImportant(org.eclipse.gef.EditPartViewer)`

### performMarqueeSelect

protected void performMarqueeSelect()
Calculates and sets a new viewer selection based on the current marquee selection. By default, this method delegates to `calculateMarqueeSelectedEditParts()` to obtain the set of edit parts, which should be regarded as being affected by the current marquee selection. It then calculates a new viewer selection based on the current selection state of all affected edit parts and the current selection mode of the tool ( `getCurrentSelectionMode()`), as well as the current selection of the viewer (in case of APPEND mode), which is then passed to the current viewer.

Since:
  3.7

### setMarqueeBehavior

public void setMarqueeBehavior(int type)
Sets the type of parts that this tool will select. This method should only be invoked once: when the tool is being initialized.

Parameters:
  `type` - `BEHAVIOR_CONNECTIONS_TOUCHED` or `BEHAVIOR_CONNECTIONS_CONTAINED` `BEHAVIOR_NODES_TOUCHED` or `BEHAVIOR_NODES_CONTAINED` or `BEHAVIOR_NODES_TOUCHED_AND_RELATED_CONNECTIONS` or `BEHAVIOR_NODES_CONTAINED_AND_RELATED_CONNECTIONS`
Since:
  3.1

### setViewer

public void setViewer(EditPartViewer viewer)
Description copied from class: `AbstractTool`
Sets the active EditPartViewer. The active viewer is the viewer from which the last event was received.

Specified by:
  `setViewer` in interface `Tool`
Overrides:
  `setViewer` in class `AbstractTool`
Parameters:
  `viewer` - the viewer
See Also:
  - `Tool.setViewer(org.eclipse.gef.EditPartViewer)`