org.eclipse.gef.tools

## Class CreationTool

- java.lang.Object
- - org.eclipse.gef.util.FlagSupport
  - - org.eclipse.gef.tools.AbstractTool
    - - org.eclipse.gef.tools.TargetingTool
      - - org.eclipse.gef.tools.CreationTool

All Implemented Interfaces:
  RequestConstants, Tool

    public class CreationTool
    extends TargetingTool

The CreationTool creates new `EditParts` via a `CreationFactory`. If the user simply clicks on the viewer, the default sized EditPart will be created at that point. If the user clicks and drags, the created EditPart will be sized based on where the user clicked and dragged.

### Nested Class Summary

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

`AbstractTool.Input`

### Field Summary

Fields
`static java.lang.Object` `PROPERTY_CREATION_FACTORY` Property to be used in `AbstractTool.setProperties(java.util.Map)` for `setFactory(CreationFactory)`.

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

`MAX_FLAG`

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

`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 and Description
`CreationTool()` Default constructor.
`CreationTool(CreationFactory aFactory)` Constructs a new CreationTool with the given factory.

### Method Summary

Methods
`protected void` `applyProperty(java.lang.Object key, java.lang.Object value)` This method is invoked from `AbstractTool.setProperties(Map)`.
`protected Cursor` `calculateCursor()` Returns the appropriate cursor for the tools current state.
`protected Request` `createTargetRequest()` Creates a `CreateRequest` and sets this tool's factory on the request.
`void` `deactivate()` Deactivates the tool.
`protected void` `enforceConstraintsForSizeOnDropCreate(CreateRequest request)` Ensures size constraints (by default minimum and maximum) are respected by the given request.
`protected java.lang.String` `getCommandName()` Returns the identifier of the command that is being sought.
`protected CreateRequest` `getCreateRequest()` Cast the target request to a CreateRequest and returns it.
`protected java.lang.String` `getDebugName()` Returns the debug name for this tool.
`protected CreationFactory` `getFactory()` Returns the creation factory used to create the new EditParts.
`protected Dimension` `getMaximumSizeFor(CreateRequest request)` Determines the maximum size for CreateRequest's size on drop.
`protected Dimension` `getMinimumSizeFor(CreateRequest request)` Determines the minimum size for CreateRequest's size on drop.
`protected boolean` `handleButtonDown(int button)` The creation tool only works by clicking mouse button 1 (the left mouse button in a right-handed world).
`protected boolean` `handleButtonUp(int button)` If the tool is currently in a drag or drag-in-progress state, it goes into the terminal state, performs some cleanup (erasing feedback, unlocking target edit part), and then calls `performCreation(int)` .
`protected boolean` `handleDragInProgress()` Updates the request, sets the current command, and asks to show feedback.
`protected boolean` `handleDragStarted()` Called only one time during a drag when the drag threshold has been exceeded.
`protected boolean` `handleFocusLost()` If the user is in the middle of creating a new edit part, the tool erases feedback and goes into the invalid state when focus is lost.
`protected boolean` `handleHover()` Handles high-level processing of a mouse hover event.
`protected boolean` `handleMove()` Updates the request and mouse target, gets the current command and asks to show feedback.
`protected void` `performCreation(int button)` Executes the current command and selects the newly created object.
`void` `setFactory(CreationFactory factory)` Sets the creation factory used to create the new edit parts.
`protected void` `updateTargetRequest()` Sets the location (and size if the user is performing size-on-drop) of the request.

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

`doAutoexpose, eraseTargetFeedback, getAutoexposeHelper, getCommand, getExclusionSet, getTargetEditPart, getTargetingConditional, getTargetRequest, handleAutoexpose, handleEnteredEditPart, handleExitingEditPart, handleHoverStop, handleInvalidInput, handleLeavingEditPart, handleViewerExited, isShowingTargetFeedback, isTargetLocked, lockTargetEditPart, resetFlags, resetHover, setAutoexposeHelper, setTargetEditPart, setTargetRequest, showTargetFeedback, unlockTargetEditPart, updateAutoexposeHelper, updateTargetUnderMouse`

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

`acceptArrowKey, activate, addFeedback, commitDrag, createOperationSet, debug, executeCommand, executeCurrentCommand, focusGained, focusLost, getCurrentCommand, getCurrentInput, getCurrentViewer, getDebugNameForState, getDefaultCursor, getDisabledCursor, getDomain, getDragMoveDelta, getLocation, getOperationSet, getStartLocation, getState, handleCommandStackChanged, handleDoubleClick, handleDrag, handleFinished, handleFocusGained, handleKeyDown, handleKeyTraversed, handleKeyUp, handleNativeDragFinished, handleNativeDragStarted, handleViewerEntered, isActive, isHoverActive, isInState, isViewerImportant, keyDown, keyTraversed, keyUp, mouseDoubleClick, mouseDown, mouseDrag, mouseHover, mouseMove, mouseUp, mouseWheelScrolled, movedPastThreshold, nativeDragFinished, nativeDragStarted, performViewerMouseWheel, placeMouseInViewer, reactivate, refreshCursor, releaseToolCapture, removeFeedback, setCurrentCommand, setCursor, setDefaultCursor, setDisabledCursor, setEditDomain, setHoverActive, setProperties, setStartLocation, setState, setToolCapture, setUnloadWhenFinished, setViewer, 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 Detail

#### PROPERTY_CREATION_FACTORY

    public static final java.lang.Object PROPERTY_CREATION_FACTORY

Property to be used in `AbstractTool.setProperties(java.util.Map)` for `setFactory(CreationFactory)`.

### Constructor Detail

#### CreationTool

    public CreationTool()

Default constructor. Sets the default and disabled cursors.

#### CreationTool

    public CreationTool(CreationFactory aFactory)

Constructs a new CreationTool with the given factory.

Parameters:
  `aFactory` - the creation factory

### Method Detail

#### applyProperty

    protected void applyProperty(java.lang.Object key,
                     java.lang.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)`

#### calculateCursor

    protected Cursor calculateCursor()

Description copied from class: `AbstractTool`
Returns the appropriate cursor for the tools current state. If the tool is in its terminal state, `null` is returned. Otherwise, either the default or disabled cursor is returned, based on the existence of a current command, and whether that current command is executable.

Subclasses may override or extend this method to calculate the appropriate cursor based on other conditions.

Overrides:
  `calculateCursor` in class `AbstractTool`
Returns:
  `null` or a cursor to be displayed.
See Also:
  `AbstractTool.calculateCursor()`

#### createTargetRequest

    protected Request createTargetRequest()

Creates a `CreateRequest` and sets this tool's factory on the request.

Overrides:
  `createTargetRequest` in class `TargetingTool`
Returns:
  the new target request
See Also:
  `TargetingTool.createTargetRequest()`

#### deactivate

    public void deactivate()

Description copied from class: `AbstractTool`
Deactivates the tool. This method is called whenever the user switches to another tool. Use this method to do some clean-up when the tool is switched. The abstract tool allows cursors for viewers to be changed. When the tool is deactivated it must revert to normal the cursor of the last tool it changed.

Specified by:
  `deactivate` in interface `Tool`
Overrides:
  `deactivate` in class `TargetingTool`
See Also:
  `Tool.deactivate()`

#### getCommandName

    protected java.lang.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()`

#### getCreateRequest

    protected CreateRequest getCreateRequest()

Cast the target request to a CreateRequest and returns it.

Returns:
  the target request as a CreateRequest
See Also:
  `TargetingTool.getTargetRequest()`

#### getDebugName

    protected java.lang.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()`

#### getFactory

    protected CreationFactory getFactory()

Returns the creation factory used to create the new EditParts.

Returns:
  the creation factory

#### handleButtonDown

    protected boolean handleButtonDown(int button)

The creation tool only works by clicking mouse button 1 (the left mouse button in a right-handed world). If any other button is pressed, the tool goes into an invalid state. Otherwise, it goes into the drag state, updates the request's location and calls `TargetingTool.lockTargetEditPart(EditPart)` with the edit part that was just clicked on.

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)

If the tool is currently in a drag or drag-in-progress state, it goes into the terminal state, performs some cleanup (erasing feedback, unlocking target edit part), and then calls `performCreation(int)` .

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

Updates the request, sets the current command, and asks to show feedback.

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

#### handleDragStarted

    protected boolean handleDragStarted()

Description copied from class: `AbstractTool`
Called only one time during a drag when the drag threshold has been exceeded. By default, nothing happens and `false` is returned. Subclasses may override to interpret the drag starting. Returning `true` indicates that the event was handled.

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

#### handleFocusLost

    protected boolean handleFocusLost()

If the user is in the middle of creating a new edit part, the tool erases feedback and goes into the invalid state when focus is lost.

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

#### handleHover

    protected boolean handleHover()

Description copied from class: `AbstractTool`
Handles high-level processing of a mouse hover event. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the hover. Return `true` to indicate that the hover was handled.

Overrides:
  `handleHover` in class `AbstractTool`
Returns:
  `true` if the hover was handled
See Also:
  `AbstractTool.handleHover()`

#### handleMove

    protected boolean handleMove()

Updates the request and mouse target, gets the current command and asks to show feedback.

Overrides:
  `handleMove` in class `AbstractTool`
Returns:
  `true` if the mouse move was handled
See Also:
  `AbstractTool.handleMove()`

#### performCreation

    protected void performCreation(int button)

Executes the current command and selects the newly created object. The button that was released to cause this creation is passed in, but since `handleButtonDown(int)` goes into the invalid state if the button pressed is not button 1, this will always be button 1.

Parameters:
  `button` - the button that was pressed

#### setFactory

    public void setFactory(CreationFactory factory)

Sets the creation factory used to create the new edit parts.

Parameters:
  `factory` - the factory

#### updateTargetRequest

    protected void updateTargetRequest()

Sets the location (and size if the user is performing size-on-drop) of the request.

Overrides:
  `updateTargetRequest` in class `TargetingTool`
See Also:
  `TargetingTool.updateTargetRequest()`

#### enforceConstraintsForSizeOnDropCreate

    protected void enforceConstraintsForSizeOnDropCreate(CreateRequest request)

Ensures size constraints (by default minimum and maximum) are respected by the given request. May be overwritten by clients to enforce additional constraints.

Since:
  3.7

#### getMaximumSizeFor

    protected Dimension getMaximumSizeFor(CreateRequest request)

Determines the maximum size for CreateRequest's size on drop. It is called from `enforceConstraintsForSizeOnDropCreate(CreateRequest)` during creation. By default, a large `Dimension` is returned.

Parameters:
  `request` - the request.
Returns:
  the minimum size
Since:
  3.7

#### getMinimumSizeFor

    protected Dimension getMinimumSizeFor(CreateRequest request)

Determines the minimum size for CreateRequest's size on drop. It is called from `enforceConstraintsForSizeOnDropCreate(CreateRequest)` during creation. By default, a small `Dimension` is returned.

Parameters:
  `request` - the request.
Returns:
  the minimum size
Since:
  3.7