Docking Tutorial: Putting It All Together

Eleritec Docking Framework Tutorial

Table of Contents | Printer Friendly Version

Putting It All Together

It makes sense at a certain juncture to put all of this together into a workable demonstration to see how one might go about building a docking-enabled application. The example ElegantDemo.java is intended to be just such a demonstration. The enclosing frame constructs a series of ElegantPanels and a series of ElegantDockingPorts. A set of JSplitPanes are arranged to divide the frame's content pane into four sections, much like the J2EE Perspective in IBM's WSAD. Each section contains a ElegantDockingPort. ElegantPanels are then docked in such as fashion as to

simulate a the series of Views commonly shown in WSAD. A ShadowBorder has been used in conjunction with the StandardBorderManager to simulate Eclipse, and a gradient effect has been added to the titlebar for each ElegantPanel, again like Eclipse. Custom classes have been implemented as Dockable and SubComponentProvider. They reside at the top-level to maintain a sense of separation between the application code and the docking-related code.

The ElegantDemo class is responsible for representing the application frame and constructing the initial component layout. In a real world situation, this represents the application itself. Aside from making use of the ElegantPanel and ElegantDockingPort classes, there is nothing in this class in the way of docking-related code. Its sole purpose is to play the role of application code.

The class ElegantDockingPort.java is a relatively simple subclass of DefaultDockingPort. Its constructor automatically assigns a SubComponentProvider and BorderManager. It also provides an overloaded add(ElegantPanel panel) method to handle docking. There is nothing particularly special about this add() method as it merely wraps a call to dock(). Its only purpose is to provide a facade to the ElegantDemo class to hide from it the underlying concept of docking. Thus, ElegantDemo invokes add() on each ElegantDockingPort when constructing the GUI without knowledge of a dock() happening behind the scenes.

Toggle to Hide Example Code

public ElegantDockingPort() {
   setComponentProvider(new ChildComponentDelegate());
   setBorderManager(new StandardBorderManager(new ShadowBorder()));
}

public void add(ElegantPanel view) {
   dock(view.getDockable(), CENTER_REGION);
}

What is interesting to note within the ElegantDockingPort constructor is that we're making use of the StandardBorderManager to manage or border behavior for us at runtime during docking and undocking operations. There is no extra border management code involved throughout the rest of the application.

The ElegantDockingPort uses ChildComponentDelegate.java as its SubComponentProvider. The method implementations are straightforward.

Toggle to Hide Example Code

public DockingPort createChildPort() {
   ElegantDockingPort port = new ElegantDockingPort();
   port.setComponentProvider(this);
   return port;
}

public JSplitPane createSplitPane() {
   JSplitPane split = new JSplitPane();

   // remove the border from the split pane
   split.setBorder(null);

   // set the divider size for a more reasonable, less bulky look
   split.setDividerSize(3);

   // check the UI. If we can't work with the UI any further, then
   // exit here.
   if (!(split.getUI() instanceof BasicSplitPaneUI))
      return split;

   // grab the divider from the UI and remove the border from it
   BasicSplitPaneDivider divider =
      ((BasicSplitPaneUI) split.getUI()).getDivider();

   if (divider != null)
      divider.setBorder(null);

   return split;
}

public JTabbedPane createTabbedPane() {
   return new JTabbedPane(JTabbedPane.BOTTOM);
}

public double getInitialDividerLocation() {
   return 0.5d;
}

This SubComponentProvider creates a JTabbedPane with its tabs on the bottom, just like the standard Eclipse GUI. It also creates a JSplitPane without any borders and sets the initial divider location to be half of the available container size. Finally, it ensures that all child ports will share the same SubComponentProvider instance. This is nothing we haven't seen before.

Turning our attention to the ElegantPanel.java, we notice once again that the class has been largely shielded from docking-related code. The purpose of this class is to provide a visual representation of the View that is moved around the screen. The code within this class is geared toward drawing a gradient titlebar in the northern region of the panel. Our only inclination that this class may be docking-related is the dockable instance variable and the method getDockable(), which returns an instance of DockableImpl.java. As with the BorderDemo example, the ElegantPanel class contains no docking registration with the DockingManager.

Toggle to Hide Example Code

public Dockable getDockable() {
   if(dockable==null)
      dockable = new DockableImpl(this, getTitleLabel());
   return dockable;
}

Looking inside the DockableImpl class, we find it is an extension of DockableAdapter. In this example, there are only four Dockable methods that are of immediate use:

Toggle to Hide Example Code

public Component getDockable() {
   return panel;
}

public String getDockableDesc() {
   String desc = panel.getTitle();
   if (desc == null || desc.length() == 0)
      return "null";
   return desc;
}

public Component getInitiator() {
   return dragInitiator;
}

public void setDockableDesc(String desc) {
   desc = desc == null ? "" : desc.trim();
   panel.setTitle(desc);
}

Taking a look back at ElegantPanel, we remember that the DockableImpl was constructed by passing in the ElegantPanel and titlebar JLabel arguments As shown in DockableImpl, the ElegantPanel is returned by getDockable(), and the titlebar JLabel is returned by getInitiator(). This is enough for us to register with the DockingManager, and we do so at the very end of the DockableImpl constructor.

Toggle to Hide Example Code

public DockableImpl(ElegantPanel dockable, JComponent dragInit) {
   if (dockable == null)
      new IllegalArgumentException("Cannot create DockableImpl with a null DockablePanel.");
   if (dragInit == null)
      new IllegalArgumentException("Cannot create DockableImpl with a null drag initiator.");

   panel = dockable;
   dragInitiator = dragInit;
   DockingManager.registerDockable(this);
}

The final class involved in the ElegantDemo is the ShadowBorder. The source code for ShadowBorder.java is available. However, since it has little do do with docking, an explanation of is is outside the scope of this tutorial.

The StandardBorderManager

Conclusion