Create an information dialog via the NotifyDescriptor.Message class. Pass the text to be displayed to the constructor, as well as an optional message type. By default, the dialog shows the information symbol, as shown in Figure 8-1.

NotifyDescriptor nd = new NotifyDescriptor.Message("Information");

Figure 8.1. Information dialog

Should the user be enabled to answer a question posed in the dialog (see Figure 8-2), use the NotifyDescriptor.Confirmation class. To that end, a range of constructors are available for passing in the message, message type, and additional option types.

NotifyDescriptor d = new NotifyDescriptor.Confirmation(
   "You can place any String or Component here",
   "That's a question");

Figure 8.2. Question dialog

An input dialog is easily created via the NotifyDescriptor.InputLine class. Define the text and title to be displayed in the input area of the dialog (see Figure 8-3). Optionally, pass in an option type and message type so that the desired buttons and symbols are shown.

NotifyDescriptor d = new NotifyDescriptor.InputLine(
   "First and last name:",
   "Please enter your name");

Figure 8.3. Input dialog

Access text entered by the user via the getInputText() method. Optionally, enter text into the field via the setInputText() method.

To show an exception (see Figure 8-4), use the NotifyDescriptor.Exception class. Pass in a Throwable instance to the constructor, such as an Exception object:

Exception ex = new Exception("An exception has occured");
NotifyDescriptor d = new NotifyDescriptor.Exception(ex);

Figure 8.4. Error dialog

The WizardDescriptor class describes and configures wizards. The class is a subclass of the DialogDescriptor class, explained in the previous section. The DialogDescriptor class, in turn, is a subclass of NotifyDescriptor. The WizardDescriptor contains and manages all panels in the wizards and is responsible for tasks such as management of steps and display of user interface components. In other words, the WizardDescriptor is the controller of the entire wizard. Typically, the WizardDescriptor also provides the DataModel, from which data collected over various steps is saved as properties. Rather than using this DataModel, your own can be provided.

For each step in the wizard, provide a panel. Typically, a panel is built out of two separate classes. The first class implements the GUI. This class is known as the visual panel, and normally extends JPanel. The second class, handling the management and validation of the panel, is known as the wizard panel. This class extends the NetBeans API WizardDescriptor. Panel<Data> class. It creates the visual panel on demand and makes it available to the wizard.

In terms of the MVC paradigm, the visual panel is the view, and the wizard panel is the controller. The visual panel only deals with user interface concerns, providing entry fields for the user and making them available via getters and setters. The visual panel does not contain business logic and, in particular, does not deal with wizard-specific classes or calls. As a result, the panel is completely reusable and can be easily ported to an entirely different wizard. In this way, the panel is reused in a dialog where data is edited in a different context. The relationship between WizardDescriptor, WizardPanel, and VisualPanel is shown in Figure 8-7.

Figure 8.7. Architecture of a wizard

The skeleton of a wizard is created in the NetBeans IDE. Go to File

First, open the user interface of the visual panel (the PlaylistVisualPanel1 panel) in the NetBeans Form Editor. Add the several fields the user interacts with to describe the playlist. The user must be able to assign a name to the playlist, while choosing a genre and providing a description and image. The completed panel should look like Figure 8-6, where the panel is shown integrated into the wizard.

The panel is a normal Swing component, extending JPanel; however, you should bear in mind the following implementation details:

Listing 8-2 shows a section from the visual panel PlaylistWizardPanel1. Notice the panel is completely free from wizard logic, focusing only on the user interface of the wizard step.

public final class PlaylistVisualPanel1 extends JPanel implements DocumentListener {
   public static final String PROP_PLAYLIST_NAME = "playlist";
   public static final String PROP_GENRE = "genre";
   public static final String PROP_DESCRIPTION = "description";
   public static final String PROP_IMAGE_PATH = "imagePath";
   public PlaylistVisualPanel1() {
      initComponents();
      playlistName.getDocument().addDocumentListener(this);
      imagePath.getDocument().addDocumentListener(this);
   }
   public String getName() {
      return NbBundle.getMessage(PlaylistWizardPanel1.class, "Panel1.Name");
   }
   public String getPlaylistName() {
      return playlistName.getText();
   }
   public String getGenre() {
      return (String)genre.getSelectedItem();
   }
   public String getDescription() {
      return description.getText();
   }
   public String getImagePath() {
      return imagePath.getText();
   }
   public void changedUpdate( DocumentEvent e ) {
      if (playlistName.getDocument() == e.getDocument()) {
         firePropertyChange(PROP_PLAYLIST_NAME, 0, 1);
      } else if(imagePath.getDocument() == e.getDocument()) {
         firePropertyChange(PROP_IMAGE_PATH, 0, 1);
      }
   }
}

Look at the content of the related wizard panel, providing the controller for the visual panel. The class implements the WizardDescriptor.Panel<Data> interface, defining the interfaces of wizard panels. Pass in a class used as the DataModel. As you need no special custom DataModel, the class WizardDescriptor is used to define the wizard panel. In addition, implement a PropertyChangeListener, allowing reaction to changes in the visual panel. A wizard panel has a status: valid or invalid. Validity depends on extensions provided to the wizard panel. In our case, a panel is only valid when the name has at least three characters. The status is saved via the private Boolean isValid.

public class PlaylistWizardPanel1 implements
   WizardDescriptor.Panel<WizardDescriptor>, PropertyChangeListener {
   private PlaylistVisualPanel1 view = null;
   private WizardDescriptor model = null;
   private boolean isValid = false;
   private ResourceBundle bundle = NbBundle.getBundle(PlaylistWizardPanel1.class);

The getComponent() method is a factory method creating the visual panel where needed. The method is called from the WizardDescriptor when the panel is first created in the wizard. To that end, do not create all panels initially. This will significantly improve the performance of wizards that provide many different steps. Therefore, be very careful using the getComponent() method. For example, do not call it in the getName() method when the wizard is created.

After creating visual panels, set properties that influence display of components in the wizard. Use PROP_CONTENT_SELECTED_INDEX to provide the number of the panel (shown in the table of contents on the left side of the wizard), enabling the user to see the number of the current step, as well as how many steps must still be completed.

Set the property PROP_AUTO_WIZARD_STYLE to true, which creates wizards with a contents section, as well as a header section. Setting this to false makes sense when the wizard has only one step, so that these additional parts become superfluous.

Via the properties PROP_CONTENT_DISPLAYED and PROP_CONTENT_NUMBERED, specify that names and numbers of wizard steps are shown on the left side of the wizard.

public PlaylistVisualPanel1 getComponent() {
      if (view == null) {
         view = new PlaylistVisualPanel1();
         view.putClientProperty(
                 WizardDescriptor.PROP_CONTENT_SELECTED_INDEX, new Integer(0));
         view.putClientProperty(
                 WizardDescriptor.PROP_AUTO_WIZARD_STYLE, Boolean.TRUE);
         view.putClientProperty(
                 WizardDescriptor.PROP_CONTENT_DISPLAYED, Boolean.TRUE);
         view.putClientProperty(
                 WizardDescriptor.PROP_CONTENT_NUMBERED, Boolean.TRUE);
      }
      return view;
   }

Using the getName() method, provide the names shown in the header section of the wizard. With getHelp(), provide a HelpCtx.DEFAULT_HELP, activating the Help button in the wizard. Further information about the HelpCtx class and the NetBeans help system are described in Chapter 9.

The status of panels, as discussed earlier (defining whether the wizard step is valid or not) is provided via the isValid() method. The isValid() method is called from the WizardDescriptor, when a panel is closed or via notifications received from the ChangeListener. When the method returns the value true, the Next or Finish buttons are activated.

The setMessage() method is a helper method for which advice is displayed to the user. The advice area of the wizard is provided by default and displayed in the lower part of a panel within the wizard. Text is defined via the property WizardDescriptor.PROP_ERROR_MESSAGE. Additionally, if the property is set and the isValid() method returns false, an error symbol is shown. If the isValid() method returns true, only a warning symbol is displayed. No symbol is shown if null is returned. You can also use the properties PROP_WARNING_MESSAGE or PROP_INFO_ MESSAGE to display warning or normal (info) messages.

public String getName() {
      return bundle.getString("Panel1.Name");
   }
   public HelpCtx getHelp() {
      return HelpCtx.DEFAULT_HELP;
   }
   public boolean isValid() {
      return isValid;
   }
   private void setMessage(String message) {
      model.putProperty(WizardDescriptor.PROP_ERROR_MESSAGE, message);
   }

The DataModel is accessed via the readSettings() and storeSettings() methods. The type of DataModel depends on the template provided, which is defined via the interface specified in the class signature. In this case, the class in question is WizardDescriptor.

The readSettings() method is called when the panel is opened. Here, values are read into panels in the wizard. Register a PropertyChangeListener in the visual panel, informing of user activities in the panel. Register it here to make sure the WizardDescriptor is available.

The storeSettings() method is called when panels are exited. Save the values defined by the user in the WizardDescriptor via the property names provided by the visual panel. In this way, the values are immediately passed from panel to panel until they are read from the WizardDescriptor as the wizard closes.

public void readSettings(WizardDescriptor model) {
      this.model = model;
      getComponent().addPropertyChangeListener(this);
   }
   public void storeSettings(WizardDescriptor model) {
      model.putProperty(PlaylistVisualPanel1.PROP_PLAYLIST_NAME,
              getComponent().getPlaylistName());
      model.putProperty(PlaylistVisualPanel1.PROP_GENRE,
              getComponent().getGenre());
      model.putProperty(PlaylistVisualPanel1.PROP_DESCRIPTION,
              getComponent().getDescription());
      model.putProperty(PlaylistVisualPanel1.PROP_IMAGE_PATH,
              getComponent().getImagePath());
   }

When discussing the visual panel, it was pointed out that values entered by the user must be tested. More specifically, make sure the user has entered a name consisting of at least three characters and that the chosen image is 128×128 pixels in size.

To be informed about changes made to the visual panel—that is, when the user enters a name or chooses an image—register a PropertyChangeListener in the readSettings() method within the visual panel. Implement the propertyChange() method. There, the values entered in the wizard can be tested via the checkValidity() method. The checkValidity() method verifies criteria, displays a message, and returns relevant values. Via these changes, inform the WizardDescriptor so that relevant buttons can be activated or deactivated. The user may only proceed to the next step when the entered data is validated and the WizardDescriptor is notified of that fact. Achieve this via the fireChangeEvent() method.

public void propertyChange(PropertyChangeEvent event) {
      boolean oldState = isValid;
      isValid = checkValidity();
      fireChangeEvent(this, oldState, isValid);
   }
   private boolean checkValidity() {
      if(getComponent().getPlaylistName().trim().length() < 3) {
         setMessage(bundle.getString("Panel1.Error1"));
         return false;
      } else if(getComponent().getImagePath().length() != 0) {
         ImageIcon img = new ImageIcon(getComponent().getImagePath());
         if(img.getIconHeight()>128 || img.getIconWidth()>128) {
            setMessage(bundle.getString("Panel1.Error2"));
            return false;
         }
      } else if(getComponent().getImagePath().length() == 0) {
         setMessage(bundle.getString("Panel1.Warning1"));
         return true;
      }
      setMessage(null);
      return true;
   }

To register a WizardDescriptor with a wizard panel, the WizardDescriptor.Panel interface provides the addChangeListener() and removeChangeListener() methods. Implement these in the class. Use the fireChangeEvent() method to inform all registered listeners. To be efficient, first verify whether the status of panels has changed, so that the WizardDescriptor is notified only when changes occur. If the isValid() method returns true, indicating that the panel has valid status, implement empty methods. The fireChangeEvent() method is not called in this case. This scenario applies to the second panel of the example, which always returns true.

private final Set<ChangeListener> listeners = new HashSet<ChangeListener>(1);
   public void addChangeListener(ChangeListener l) {
      synchronized(listeners) {
         listeners.add(l);
      }
   }
   public void removeChangeListener(ChangeListener l) {
      synchronized(listeners) {

listeners.remove(l);
      }
   }
   protected final void fireChangeEvent(
      Object source, boolean oldState, boolean newState) {
      if(oldState != newState) {
         Iterator<ChangeListener> it;
         synchronized (listeners) {
            it = new HashSet<ChangeListener>(listeners).
                     iterator();
         }
         ChangeEvent ev = new ChangeEvent(source);
         while (it.hasNext()) {
            it.next().stateChanged(ev);
         }
      }
   }
}

So far, you've learned about constructing panels that represent steps in a wizard. You saw how a panel consists of a view and a controller, as well as how these work together.

Only one small detail remains to round out your understanding of wizard panels. A wizard is represented by its WizardDescriptor class. The WizardDescriptor class manages the individual panels. Optionally, one may instantiate the panels and then pass them in to the WizardDescriptor. For example, that's how the action class works that is created automatically when using the IDE to create a wizard skeleton. In the interest of encapsulation, composition, and reusability, it is a good idea to create an individual wizard descriptor, extending the WizardDescriptor class. Thus, this class itself creates the panels and sets their properties. As done with the action class that starts the wizard, create an instance of the WizardDescriptor, which is immediately passed to the DialogDisplayer. In this way, a wizard can be called transparently.

For example, create the PlaylistWizardDescriptor class, extending the WizardDescriptor class (see Listing 8-3). Use the setPanelsAndSettings() method to pass in the Descriptor for both panels, which are declared as private variables. The panels must be passed via an iterator. One such iterator class is responsible for whole ranges of panels. Use the default ArrayIterator. The second parameter for setPanelsAndSettings() is a DataModel, which the panel receives via the readSettings() and storeSettings() methods. Here, use data obtained from the wizard for loading and storing purposes. Pass this as a reference to the PlaylistWizardDescriptor, which is used as a DataModel. Finally, carry out a few configuration tasks.

public class PlaylistWizardDescriptor extends WizardDescriptor {
   private PlaylistWizardPanel1 p1 = new PlaylistWizardPanel1();
   private PlaylistWizardPanel2 p2 = new PlaylistWizardPanel2();
   public PlaylistWizardDescriptor() {
      List<Panel<WizardDescriptor>> panels =
              new ArrayList<Panel<WizardDescriptor>>();
      panels.add(p1);
      panels.add(p2);
      this.setPanelsAndSettings(new ArrayIterator<WizardDescriptor>(panels), this);
      this.setTitleFormat(new MessageFormat("{0}"));
      this.setTitle(
              NbBundle.getMessage(PlaylistWizardDescriptor.class, "Wizard.Name"));
      putProperty(WizardDescriptor.PROP_AUTO_WIZARD_STYLE, Boolean.TRUE);
      putProperty(WizardDescriptor.PROP_CONTENT_DISPLAYED, Boolean.TRUE);
      putProperty(WizardDescriptor.PROP_CONTENT_NUMBERED, Boolean.TRUE);
      putProperty(WizardDescriptor.PROP_CONTENT_DATA,
              new String[]{p1.getName(), p2.getName()});
   }
}

Simpler than the WizardDescriptor is the action class that starts the wizard. Create a simple instance of the PlaylistWizardDescriptor class and immediately pass it to the createDialog() method, as illustrated in the "Custom Dialogs" section earlier in the chapter. This creates a Dialog object, which contains a wizard displayed as usual, via the setVisible() method (see Listing 8-4).

As the wizard ends, information is gleaned from the button clicked by the user, via the getValue() method. The most important point here is how the data is managed. Since the WizardDescriptor itself manages data, we can read it directly from the WizardDescriptor. The best approach is to use the getProperties() method, providing a Map with all the properties that have been saved.

public final class PlaylistWizardAction implements ActionListener {
   public void actionPerformed(ActionEvent evt) {
      PlaylistWizardDescriptor descriptor = new PlaylistWizardDescriptor();
      Dialog dialog = DialogDisplayer.getDefault().createDialog(descriptor);
      dialog.setVisible(true);
      dialog.toFront();
      if(descriptor.getValue() == WizardDescriptor.FINISH_OPTION) {
         Map<String, Object> props = descriptor.getProperties();
         // Create the playlist with the data stored in props
      }
   }
}

In this section, the relationship between the WizardDescriptor, wizard panel, and visual panel is revised, focusing on how events and notifications are handled. In the sequence diagram in Figure 8-8, observe the initialization of a wizard and the interaction between the various parts of the wizard as the user enters data.

Figure 8.8. Interaction between the WizardDescriptor, wizard panel, and visual panel

In the actionPerformed() method of the action class that initialized the wizard, an instance of the PlaylistWizardDescriptor is created. This WizardDescriptor generates its panels and registers a ChangeListener for each, so that a notification is fired whenever the status of the panel changes. The visual panel is then obtained via the getComponent() method of the wizard panel. This method creates the visual panel on demand and registers a PropertyChangeListener, informing of changes made by the user. The WizardDescriptor observes the status of its panels via a ChangeListener, which in turn observes the status of visual panels via a PropertyChangeListener.

When the user types data into a field to which a listener is attached, a PropertyChangeEvent is fired, notifying the wizard panel that data has changed. The wizard panel retrieves the data via the getters and then verifies received data. Depending on the result of the verification, status of the panel is set.

If the status changes, a ChangeEvent is fired, notifying the WizardDescriptor, which verifies the panel status, calling the isValid() method. Depending on the value of the isValid() method, the WizardDescriptor enables or disables the buttons in the wizard.

Depending on the business scenario, it may be useful to allow the user to end the wizard prematurely. Normally, the wizard ends when the Finish button is clicked in the last panel. To allow the user to end the wizard in an earlier panel, implement the interface WizardDescriptor. FinishablePanel. The WizardDescriptor.FinishablePanel interface provides the method isFinishPanel(), which uses the return value true when the wizard can be ended. In the example, it is conceivable to implement this interface in the first panel, allowing the user to end the wizard without adding playlist tracks.

Confirming the validity of a panel is provided by the WizardDescriptor 's isValid() method. The method is called via the ChangeListener, as the panel is closed and when notifications are sent. Should additional verifications be required when the user clicks Next or ends the wizard, implement the WizardDescriptor.ValidatingPanel interface. The WizardDescriptor. ValidatingPanel interface specifies the validate() method, in which additional verifications can be performed.

Errors identified in this way are made available as a WizardValidationException. The constructor of this exception class receives a JComponent, which obtains the focus, so that the user can be shown related error messages. In addition, a failure message can be added, which is then shown in the wizard.

Rather than using the validate() method of the WizardDescriptor.ValdiatingPanel interface, which is executed asynchronously in the event dispatch thread (EDT) (where no long-running tasks should be performed), use the WizardDescriptor.AsynchronousValidatingPanel interface to asynchronously handle verification. Using this interface, the validate() method is automatically performed in a separate thread. As a result, the user interface is available to the user, enabling use of the Cancel button to end the process.

Since the asynchronous method is not carried out in the EDT, no access is provided to GUI components in order to read data from them. To that end, the interface provides the prepareValidation() method, which is called in the EDT, allowing access to data in the GUI components, while disallowing further change. Using the data retrieved this way, the validate() method carries out verification.

An iterator within the WizardDescriptor creates the whole range of panels. The interface of an iterator of this kind is described by the WizardDescriptor.Iterator class. A standard implementation of this interface provides the WizardDescriptor.ArrayIterator class, providing panels in a sequential order. The class is also used when passing panels as an array to the WizardDescriptor class. However, when giving the user the choice to skip one or more panels based on entered data, provide your own iterator implementation in the WizardDescriptor. The iterator will then handle dynamic creation of panels.

The infrastructure of a dynamic wizard can be created via a wizard in the NetBeans IDE. Returning to the first step of the Wizard wizard, use the Wizard Step Sequence to set the Dynamic option, letting the IDE create an iterator class.

Based on the WizardDescriptor.Iterator interface, additional classes are provided. Use the WizardDescriptor.InstantiatingIterator interface and its instantiate() method to create a set of objects. Alternatively, use the WizardDescriptor.AsynchronousInstantiatingIterator with its instantiate() method, which is performed asynchronously outside the EDT, when the user clicks the Finish button. Finally, use the WizardDescriptor.ProgressInstantiatingIterator interface to show the user a progress bar when the wizard ends, while the instantiate() method is processing. In this case, the instantiate() method is called in a separate thread, receiving a ProgressHandle. Via this class, the status is shown, as is done with the standard progress bar (see Chapter 5).

Dependencies can be defined between individual widgets. You are thereby able to respond to changes in position or size of other widgets. This dependency is realized by a listener registered on the widget. In addition, the Widget class makes available two methods, addDependency() and removeDependency(), in order that a listener can be added or removed. A listener is specified by the interface Widget.Dependency. The listener must implement the method revalidateDependency(), which is called by the respective widget on a change of position or size. By this method, you call the revalidate() method of widgets that are dependent on other widgets.

Each widget has border. By default, this is an empty border, represented by the class EmptyBorder. Another border can be specified with the setBorder() method. A border is specified by the interface Border. And this interface is implemented by numerous Border classes. In addition to the EmptyBorder class, there are also LineBorder, BevelBorder, DashedBorder, ImageBorder, ResizeBorder, RoundedBorder, and SwingBorder classes. A ResizeBorder adds eight points to the edges of your widget, which are used to change its size. Furthermore, the SwingBorder class allows you to use any Swing javax.swing.border.Border implementation. Last at your disposal is the CompositeBorder class, with which you can combine any number of the Border instances mentioned.

The borders, however, are not created directly, but via a factory. This is the BorderFactory class that provides you with numerous methods with which you can create various border types. Instances produced by the factory can be simultaneously shared by several widgets. If you wish to use the same border between several widgets, you need only create one instance of it.

A widget (like a Swing container) has a special layout, managed and specified by a Layout Manager. A layout is defined by the interface Layout and is responsible for arrangement of the child widgets. Four different variants of layouts are available, produced by the LayoutFactory class and added to a widget with the setLayout() method.

Layout al = LayoutFactory.createAbsoluteLayout();

Layout hfl = LayoutFactory.createHorizontalFlowLayout();
Layout vfl = LayoutFactory.createVerticalFlowLayout();

Layout cl = LayoutFactory.createCardLayout();

LayoutFactory.setActiveCard(Widget parent, Widget activate);

Layout ol = LayoutFactory.createOverlayLayout();

This action is for the treatment of drag-and-drop operations. An AcceptProvider implementation must be provided to create the action. The AcceptProvider interface specifies the method isAcceptable(), which allows specifying whether a drop operation on this widget is allowed, as well as the method accept(), with which you accomplish the drop operation.

ActionFactory.createAcceptAction(AcceptProvider p);

This action provides a context menu, displayed by right-clicking the widget. You create the action using the default method without parameters, whereby actions for the menu are inferred from the ActionMap of the scene view. Additionally, there is an option to supply the method with an InputMap and ActionMap used for production of the menu.

ActionFactory.createActionMapAction();
ActionFactory.createActionMapAction(InputMap i, ActionMap a);

This action can only be used by FreeConnectionWidget widgets. With it, you add or remove control points by double-clicking them. You also indicate the sensitivity used.

ActionFactory.createAddRemoveControlPointAction();

ActionFactory.createAddRemoveControlPointAction(
   double createSensitivity,
   double deleteSensitivity);

With the MoveAction, a widget can be moved by drag-and-drop. Please note that this action only functions if the parent widget has an AbsoluteLayout. Similarly, the AlignWithMoveAction behaves like the MoveAction. In contrast, however, additional "snapping" with other widgets occurs. All widgets against which alignment is checked are gathered using an AlignWithWidgetCollector instance or set through a LayerWidget. In the second case, the alignment of all child widgets within each layer is checked.

ActionFactory.createMoveAction();

ActionFactory.createMoveAction(
   MoveStrategy             strategy,
   MoveProvider             provider);

ActionFactory.createAlignWithMoveAction(
   AlignWithWidgetCollector collector,

LayerWidget              interactionLayer,
   AlignWithMoveDecorator   decorator);

ActionFactory.createAlignWithMoveAction(
   LayerWidget              collectionLayer,
   LayerWidget              interactionLayer,
   AlignWithMoveDecorator   decorator);

With the ResizeAction, you change the size of widgets, while AlignWithResizeAction reviews snapping against other widgets. With widgets needing their alignment checked against others, provide either an AlignWithWidgetCollector instance or a LayerWidget.

ActionFactory.createResizeAction();

ActionFactory.createResizeAction(
   ResizeStrategy             strategy,
   ResizeProvider             provider);

ActionFactory.createResizeAction(
   ResizeStrategy             strategy,
   ResizeControlPointResolver resolver,
   ResizeProvider             provider);

ActionFactory.createAlignWithResizeAction(
   AlignWithWidgetCollector   collector,
   LayerWidget                interactionLayer,
   AlignWithMoveDecorator     decorator);

ActionFactory.createAlignWithResizeAction(
   LayerWidget                collectionLayer,
   LayerWidget                interactionLayer,
   AlignWithMoveDecorator     decorator);

With these actions, the zoom of the whole scene is changed with the mouse wheel. These actions are not added to a widget, but directly to a scene.

ActionFactory.createZoomAction();
ActionFactory.createZoomAction(double zoom, boolean animated);
ActionFactory.createCenteredZoomAction(double zoomMultiplier);

With the ConnectAction, you can connect, with the assistance of ConnectionWidgets, two widgets. This action is added to the widget from which the connection is to be made. Only with a ConnectProvider instance, following a check of the source and target widgets for the desired connection, can a connection be made. Optionally, supply a specific graphic for the connecting line using a ConnectDecorator. With the ExtendedConnectAction, a connection can be made only as long as the Ctrl key pressed. This action is meant for cases where conflicts with other actions occur—for example, if you want to use the ConnectAction and the MoveAction at the same time. In these cases, use the ExtendedConnectAction.

ActionFactory.createConnectAction(
   LayerWidget interactionLayer,
   ConnectProvider provider);

ActionFactory.createConnectAction(
   ConnectDecorator decorator,
   LayerWidget interactionLayer,
   ConnectProvider provider);

ActionFactory.createExtendedConnectAction(
   LayerWidget interactionLayer,
   ConnectProvider provider);

ActionFactory.createExtendedConnectAction(
   ConnectDecorator decorator,
   LayerWidget interactionLayer,
   ConnectProvider provider);

ActionFactory.createReconnectAction(
   ReconnectProvider provider);

ActionFactory.createReconnectAction(
   ReconnectDecorator decorator,
   ReconnectProvider provider);

You shift the focus between the widgets of a scene using the Tab key, either forward or backward. With the CycleFocusAction, you specify the behavior with which the preceding or following widget is focused using a CycleFocusProvider. In the case of the CycleObjectSceneFocusAction, which is applied to an ObjectScene, the order of the focusing is determined by the return value of getIdentityCode().

ActionFactory.createCycleFocusAction(CycleFocusProvider p);
ActionFactory.createCycleObjectSceneFocusAction();

In order to edit a widget by double-clicking, add an EditAction. The triggered behavior is implemented by an EditProvider. A further option supplies an in-place editor that is displayed upon double-clicking. For this, use the InplaceEditorAction, whereby the editor can be any JComponent subclass. For example, with an IconNodeWidget or a LabelWidget, this would typically be a JTextField.

ActionFactory.createEditAction(
   EditProvider provider);

ActionFactory.createInplaceEditorAction(
   InplaceEditorProvider provider);

ActionFactory.createInplaceEditorAction(
   TextFieldInplaceEditor editor);

ActionFactory.createInplaceEditorAction(
   TextFieldInplaceEditor editor,
   EnumSet expansionDirections);

With this action, you can forward keyboard events to other widgets.

ActionFactory.createForwardKeyEventsAction(
   Widget forwardToWidget,
   String forwardToTool);

With the HoverAction, you can react to a mouse pointer that is hovering over a widget. How the widget behaves is specified by a HoverProvider or a TwoStateHoverProvider.

ActionFactory.createHoverAction(HoverProvider p);
ActionFactory.createHoverAction(TwoStateHoverProvider p);

These actions move the control points of the connecting line of a ConnectionWidget. The OrthogonalMoveControlPointAction is used when a ConnectionWidget has an OrthogonalSearchRouter. The FreeMoveControlPointAction has no restrictions on positioning the points.

ActionFactory.createMoveControlPointAction(MoveControlPointProvider provider);
ActionFactory.createFreeMoveControlPointAction();
ActionFactory.createOrthogonalMoveControlPointAction();

If the view of a scene is contained within a JScrollPane, the PanAction allows scrolling the view by moving the mouse while the middle button is pressed. This action is usually added to a scene.

ActionFactory.createPanAction();

Use the PopupMenuAction to provide a widget with a context menu. This requires implementing a PopupMenuProvider within which you provide a JPopupMenu instance.

ActionFactory.createPopupMenuAction(
   PopupMenuProvider more provider);

The SelectAction is similar to the EditAction; however, this event is the result of a single click. The logic is implemented within a SelectProvider, inside which you also specify whether a widget is selected. The RectangularSelectAction is usually added to an ObjectScene or a LayerWidget with which you select widgets by drawing rectangles around them.

ActionFactory.createSelectAction(SelectProvider provider);

ActionFactory.createRectangularSelectAction(
   ObjectScene scene,
   LayerWidget interactionLayer);

ActionFactory.createRectangularSelectAction(
   RectangularSelectDecorator decorator,
   LayerWidget interactionLayer,
   RectangularSelectProvider provider);

This action is required for switching between widgets that are in a CardLayout.

ActionFactory.createSwitchCardAction(Widget cardLayoutWidget);

In order to establish fast navigation within larger scenes, a scene offers us an overview in the form of an interactive JComponent. This is a satellite view created using the createSatelliteView() method. If the view of your scene is embedded in a JScrollPane and the scene is larger than that of the displayed area, navigate the scene by moving the gray frame present in the overview to update the view (see Figure 8-12).

Figure 8.12. An overview for a scene can be created and also used for navigation.

In few steps and with the assistance of some Java utilities, you can export a scene generated with the Visual Library API into an image contained within a PNG file. To this end, first produce a BufferedImage object, into which is written the graphic data. Specify the size of this Image instance using the current size of the view of the respective scene, to assure the complete contents are stored. From this object, we avail ourselves of the Graphics2D context with which we feed data into the buffer of the BufferedImage object. This context is then supplied to the paint() method of the Scene object so that content is written to the buffer of the BufferedImage instance rather than the screen (see Listing 8-7). Following this, dispose of the context so that the resources can be released. With a JFileChooser, request a file name and, if necessary, append the appropriate suffix. Once this is done, utilize the ImageIO class that looks for an ImageWriter for PNG files, using it to write the data of the BufferedImage object into the selected file.

private Scene sc = new Scene();

public void exportScene() {
   BufferedImage img = new BufferedImage(
      sc.getView().getWidth(),

sc.getView().getHeight(),
      BufferedImage.TYPE_4BYTE_ABGR);

   Graphics2D graphics = img.createGraphics();
   sc.paint(graphics);
   graphics.dispose();

   JFileChooser chooser = new JFileChooser();
   chooser.setFileFilter(new FileNameExtensionFilter(
      "Portable Network Graphics (.png)", "png"));

   if(chooser.showSaveDialog(sc.getView()) == JFileChooser.APPROVE_OPTION) {
      File f = chooser.getSelectedFile();
      if (!f.getName().toLowerCase().endsWith(".png")) {
         f = new File(f.getParentFile(), f.getName() + ".png");
      }

      try {
         ImageIO.write(img, "png", file);
      } catch (IOException e) {
         Logger.getLogger(getName()).warning(e.toString());
      }
   }
}