Docking Tutorial: Working with Child Ports

Eleritec Docking Framework Tutorial

Table of Contents | Printer Friendly Version

Working with Child Ports

While createTabbedPane() and createSplitPane() are straightforward enough, createChildPort() requires a little added explanation. When two Dockable instances have been added to a DefaultDockingPort in a JSplitPane configuration, the container hierarchy for the DefaultDockingPort itself takes on more than a JSplitPane and the two Dockable components.

A DefaultDockingPort may only have one child component. For a split configuration, the getDockedComponent() method will return a reference to a JSplitPane. A JSplitPane, however, may only hold two child components. While this satisfies the need for docking two Components within a DefaultDockingPort, it places a restriction upon further docking within the DockingPort itself. This is best shown in an example. Let us assume that a DefaultDockingPort contains a single child component, and the DockingManager attempts to dock a second Dockable instance within the WEST region. The docking oepration completes successfully and the DefaultDockingPort now contains a JSplitPane, which contains both Dockable components. Subsequently, the DockingManager attempts to dock a third Dockable component in the EAST region of the DefaultDockingPort. Because a JSplitPane cannot hold more than two Components, the new Dockable cannot be added to the split pane itself. This issue is illustrated in Figure 3.

There are several ways to approach this problem within the DefaultDockingPort itself. One solution is to use the same technique used for a two-component configuration by creating a new JSplitPane, placing the Dockable within the right side, and placing the current JSplitPane in the left side. While this is a valid solution, it doesn't preserve the ordering of child components with respect to the point in time at which they were docked. Such information may be useful in the future when persisting a docking configuration out to disk for later use when an application has been restarted. In this scenario, components that have been docked earlier in time will be pushed further down the container hierarchy, rather than residing closer to the top, which would be more intuitive when analyzing the object graph. It would also cause unpredictability with respect to the DefaultDockingPort'sgetDockedComponent() method,

forcing it to return a new reference every time new components are added to the port.

Instead, the DefaultDockingPort uses sub-ports to manage multiple split configuration dockings as shown in Figure 4. When a DefaultDockingPort is split between two components, the JSplitPane returned by createSplitPane() does not contain each Dockable component directly. Rather, each side of the JSplitPane contains a new DockingPort instance, which in turn contain the Dockable components. Thus, sub-docking is achived by nesting a series of DefaultDockingPorts. The new component in the EAST region is not docked into the root DefaultDockingPort. Instead, it is docked into the EAST region of a child DefaultDockingPort within the top-level JSplitPane. The child DefaultDockingPort splits itself, and the container hierarchy deepens.

These child DefaultDockingPorts are generated by the createChildPort() method on the SubComponentProvider interface. In SplitPaneDemo.java, the createChildPort() is as follows:

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

For all child DockingPorts, the ComponentProvider in our example sets the ComponentProvider for each child port before returning. This is to ensure that each child port will retain the same component creation characteristics of the root DefaultDockingPort. While this isn't absolutely necessary, and is up to the individual developer's discretion, it is recommended from an asthetic point of view. Sub-docking should appear seamless to the end-user, and leaving different component generation behavior on sub-ports will more than likely add a level of asthetic inconsistency to the application, making for an unattractive end-user experience.

Working with the JSplitPane

Border Management