NetBeans Platform Cookbook Chapter 07 04

Add Actions

The behavior of widgets is implemented via actions. First read the basic important information. Then we show ist of prepared actions.


Actions and Event Handling

Each widget knows its parent, children, location and how to paint itself. Each widget has set of actions. It is a chain that receives AWT events. Then it finds which widget is addressed for. It passes widgets tree and uses bounds and isHitAt(Point) method for it. The event is wrapped to specific type of WidgetEvent. The event-point is converted to local coordinates. The action receives this event, processes its work and returns the WidgetAction.State instance to indicate to action chain how to continue handling of the event. Used WidgetAction.States are:

  • WidgetAction.State.REJECTED - the action does not handle the event, the event can be processed by next action in the chain.
  • WidgetAction.State.CONSUMED - the event was handled by the action and processing of this event is stopped.
  • WidgetAction.State.CHAIN_ONLY - the event was handled by the action, was consumed but the event can be passed to next actions in the chain for handling.
  • WidgetAction.State.createLocked(Widget, WidgetAction) - the event was handled by the action and the next event must be processed by this action on this widget - it is used for actions that require multiple events to perform their work, e.g. move, drag or create new connection.

First are processed scene prior actions, then widget actions and next tool actions. There are their description.

Sets of actions

Prior actions of the Scene are processed as the first before others. They can consume the event (handling of the event is then stopped) or need not, but they can't lock the event. They can be retrieved by Scene.getPriorActions() method.

Actions of the widget (the Scene is also a Widget) are processed after prior actions. If previous event handling returned lock then the event is passed to locking action and corresponding widget else the chain is processed until the event is consumed or all actions were used. This set can be retrieved by getActions() method.

Tool actions are sets of actions grouped to named sets. The Scene has a String property activeTool. If the event was not consumed and the widget.getActions(String tool) method returns not null chain then it continues handling of the event. The behavior of the Scene/Widget can be altered by the Scene state, e.g. you can switch between select, move, create connection modes. The default tool is the null value (not set tool). If you want create actions for specified tool call createActions(String tool) method and add actions to the tool set.

Action Creation

Actions are created by ActionFactory or by the Scene. Some actions can receive decorator and/or provider parameter. The decorator visualizes the operation by temporary visible widgets. For example the Rectangular Select Action paints blue rectangle to visualize selection area. The Align With Move Action paints dashed lines. The provider defines bahaviour of the action. Explore the ObjectSelectProvider inner class of the ObjectScene.

Order of Actions

Each action handles events. So you have to care of order of actions. E. g. the select actions consumes one click so the double-click would not be handled.

We show an example from documentation:

WidgetAction.Chain actions = nodeWidget.getActions ();

// this action consumes only double-click events
actions.addAction (ActionFactory.createTextFieldInplaceEditor (...));

// handles mouse-button is pressed on the node widget
// this action does not consume any event
actions.addAction (myObjectScene.createSelectAction ());

// this action consumes all events when the mouse is dragged
// (means: while the mouse button is pressed on the node widget)
actions.addAction (ActionFactory.createMoveAction ());

// this action consumes all events while the mouse is over the node widget
// (means: almost everytime) - therefore use it as the last action.
actions.addAction (myObjectScene.createObjectHoverAction ());

The next example is troubles using move action and create connection action. The both use mouse dragging. The solution is switch the active tool or use any modification key. The Visual Library offers the extended connection action which works if the Ctrl key is pressed while dragging. You can switch the active tool using prior action that checks if the Ctrl key is pressed. You can see and try the test.tool.CtrlKeySwitchToolTest example in official Visual Library examples.

How to

Actions are created by ActionFactory or by Scene or ObjectScene using createXXXAction() methods. Set of prepared actions is sufficient for all purposes and you do not need create any special action, provider and decorator. But you can. The documentation is clear and useful. We can not copy it so we list most used actions for quick review without reading the documentation. Note the ActionFactory has methods for creating prepared providers, decorators and strategies, too. The action can be mostly used by multiple widgets.

Actions retrieving by ActionFactory.createXXXAction() method (some of Scene or ObjectScene):


MoveAction moves the widget dragging it. It locks events for itself.

MoveControlPointAction is the same for control point.

AlignWithMoveAction moves the widget. Uses decorator to show how the widget will be aligned with others.

ResizeAction resizes widget dragging control points checked by ResizeControlPointResolver.


HoverAction shows which widget mouse cursor is located over by highlighting background or border.

AcceptAction accepts drag operation as a target.


EditAction enables edit any properties joined with the widget.

InplaceEditorAction calls simple editing, e.g. edit the label text.

PopupMenuAction shows the popup menu given by provider.

SwitchCardAction is select action with specialized SelectProvider switching visible children using CardLayout.


ActionMapAction is bridge between key-strokes and called actions. Be careful to avoid conflicts.

ForwardKeyEventsAction passes key event to other widget for handling.

CycleFocusAction changes focused widget by Tab or Shift+Tab key.

CycleObjectSceneFocusAction switches focus on objects behind the scene.


ConnectAction creates new connection by dragging mouse from source to the target widget.

ExtendedConnectAction is the same but the Ctrl key must be pressed to prevent conflicts with other actions.

ReconnectAction changes target of the connection by dragging.





SelectAction adds/removes widgets to/from actual selected widget list.

RectangularSelectAction selects widgets by dragged rectangle area.

ContiguousSelectAction changes behaviour by modifiers.

Scene specific

ZoomAction changes scene zoom factor by mouse wheel rolling. It uses animator.

CenteredZoomAction changes zoom keeping center of the scene.

MouseCenteredZoomAction changes zoom with center by mouse location.

PanAction scrolls the scene by dragging with middle mouse button.

WheelPanAction uses mouse wheel + Shift or Ctrl key for scene panning.

Created by Scene, ObjectScene

Scene.createWidgetHoverAction() creates hover action with its own provider that changes widget state.

ObjectScene.createObjectHoverAction() the same but changes object state.

ObjectScene.createSelectAction() creates select action using its own object-specific provider.

List of ActionFactory.createXXXyyyy() for decorators and providers:


DefaultAlignWithMoveDecorator DefaultConnectDecorator DefaultReconnectDecorator DefaultRectangularSelectDecorator


DefaultMoveProvider FreeMoveControlPointProvider DefaultResizeProvider ObjectSceneRectangularSelectProvider MoveControlPointProvider

Other, algorithms

SnapToGridMoveStrategy FreeMoveStrategy FreeResizeStategy DefaultResizeControlPointResolver InplaceEditorController


Figure 7.5 Actions


Note from documentation: For preventing deadlocks, use AWT-thread when manipulating with the library structures.

Example sources are stored in the 07_Visual_Library / vl04_add_actions directory.

Visual Library 2.0 - Examples are stored on this page

Text and sources were created under NB 6.8 and will be upgraded.


Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo