This is a {@code Container} that implements the {@code DockingPort}interface. It provides a default implementation of {@code DockingPort} toallow ease of development within docking-enabled applications.
The {@code DefaultDockingPort} handles docking in one of three ways. If theport is empty, then all incoming {@code Dockables} are docked to the CENTERregion. If the port is not empty, then all incoming {@code Dockables} dockedto the CENTER region are embedded within a {@code JTabbedPane}. All incoming {@code Dockables} docked to an outer region (NORTH, SOUTH, EAST, and WEST) ofa non-empty port are placed into a split layout using a {@code JSplitPane}.
For centrally docked {@code Components}, the immediate child of the {@code DefaultDockingPort} may or may not be a {@code JTabbedPane}. If {@code isSingleTabAllowed()} returns {@code true} for the current{@code DefaultDockingPort}, then the immediate child returned by {@code getDockedComponent()} will return a {@code JTabbedPane} instance evenif there is only one {@code Dockable} embedded within the port. If there is asingle {@code Dockable} in the port, but {@code isSingleTabAllowed()} returns{@code false}, then {@code getDockedComponent()} will return the{@code Component} that backs the currently docked {@code Dockable}, returned by the {@code Dockable's} {@code getComponent()} method.{@code isSingleTabAllowed()} is a scoped property that may apply to thisport, all ports across the JVM, or all ports within a user defined scope. {@code getDockedComponent()} will return a {@code JTabbedPane} at all timesif there is more than one centrally docked {@code Dockable} within the port,and all docked {@code Components} will reside within the tabbed pane.
Components that are docked in the NORTH, SOUTH, EAST, or WEST regions are placed in a {@code JSplitPane} splitting the layout of the{@code DockingPort} between child components. Each region of the{@code JSplitPane} contains a new {@code DefaultDockingPort}, which, in turn, contains the docked components. In this situation, {@code getDockedComponent()} will return a {@code JSplitPane} reference.
A key concept that drives the {@code DefaultDockingPort}, then, is the notion that this {@code DockingPort} implementation may only ever have onesingle child component, which may or may not be a wrapper for other child components. Because {@code JSplitPane} contains child{@code DefaultDockingPorts}, each of those {@code DefaultDockingPorts} isavailable for further sub-docking operations.
Since a {@code DefaultDockingPort} may only contain one child component,there is a container hierarchy to manage tabbed interfaces, split layouts, and sub-docking. As components are removed from this hierarchy, the hierarchy itself must be reevaluated. Removing a component from a child {@code DefaultDockingPort} within a {@code JSplitPane} renders the child{@code DefaultDockingPort} unnecessary, which, in turn, renders the notion ofsplitting the layout with a {@code JSplitPane} unnecessary (since there areno longer two components to split the layout between). Likewise, removing a child component from a {@code JTabbedPane} such that there is only one childleft within the {@code JTabbedPane} removes the need for a tabbed interfaceto begin with.
When the {@code DockingManager} removes a component from a{@code DockingPort} via {@code DockingManager.undock(Dockable dockable)} ituses a call to {@code undock()} on the current {@code DockingPort}. {@code undock()} automatically handles the reevaluation of the containerhierarchy to keep wrapper-container usage at a minimum. Since {@code DockingManager} makes this callback automatic, developers normallywill not need to call this method explicitly. However, when removing a component from a {@code DefaultDockingPort} using application code,developers should keep in mind to use {@code undock()} instead of{@code remove()}. Border management after docking and undocking operations are accomplished using a {@code BorderManager}. {@code setBorderManager()} may be used to setthe border manager instance and customize border management.
@author Christopher Butler