Package org.flexdock.docking.defaults

Class DefaultDockingPort

  • All Implemented Interfaces:
    java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, DockingConstants, DockingPort, DockingListener, DockingMonitor
    Direct Known Subclasses:
    FloatingDockingPort, Viewport
    public class DefaultDockingPort
extends javax.swing.JPanel
implements DockingPort, DockingConstants
    This is a Container that implements the DockingPort interface. It provides a default implementation of DockingPort to allow ease of development within docking-enabled applications.

    The DefaultDockingPort handles docking in one of three ways. If the port is empty, then all incoming Dockables are docked to the CENTER region. If the port is not empty, then all incoming Dockables docked to the CENTER region are embedded within a JTabbedPane. All incoming Dockables docked to an outer region (NORTH, SOUTH, EAST, and WEST) of a non-empty port are placed into a split layout using a JSplitPane.

    For centrally docked Components, the immediate child of the DefaultDockingPort may or may not be a JTabbedPane. If isSingleTabAllowed() returns true for the current DefaultDockingPort, then the immediate child returned by getDockedComponent() will return a JTabbedPane instance even if there is only one Dockable embedded within the port. If there is a single Dockable in the port, but isSingleTabAllowed() returns false, then getDockedComponent() will return the Component that backs the currently docked Dockable, returned by the Dockable's getComponent() method. isSingleTabAllowed() is a scoped property that may apply to this port, all ports across the JVM, or all ports within a user defined scope. getDockedComponent() will return a JTabbedPane at all times if there is more than one centrally docked Dockable within the port, and all docked Components will reside within the tabbed pane.

    Components that are docked in the NORTH, SOUTH, EAST, or WEST regions are placed in a JSplitPane splitting the layout of the DockingPort between child components. Each region of the JSplitPane contains a new DefaultDockingPort, which, in turn, contains the docked components. In this situation, getDockedComponent() will return a JSplitPane reference.

    A key concept that drives the DefaultDockingPort, then, is the notion that this DockingPort implementation may only ever have one single child component, which may or may not be a wrapper for other child components. Because JSplitPane contains child DefaultDockingPorts, each of those DefaultDockingPorts is available for further sub-docking operations.

    Since a 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 DefaultDockingPort within a JSplitPane renders the child DefaultDockingPort unnecessary, which, in turn, renders the notion of splitting the layout with a JSplitPane unnecessary (since there are no longer two components to split the layout between). Likewise, removing a child component from a JTabbedPane such that there is only one child left within the JTabbedPane removes the need for a tabbed interface to begin with.

    When the DockingManager removes a component from a DockingPort via DockingManager.undock(Dockable dockable) it uses a call to undock() on the current DockingPort. undock() automatically handles the reevaluation of the container hierarchy to keep wrapper-container usage at a minimum. Since DockingManager makes this callback automatic, developers normally will not need to call this method explicitly. However, when removing a component from a DefaultDockingPort using application code, developers should keep in mind to use undock() instead of remove(). Border management after docking and undocking operations are accomplished using a BorderManager. setBorderManager() may be used to set the border manager instance and customize border management.

    Author:
    Christopher Butler
    See Also:
    Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected class  DefaultDockingPort.PortLayout  

      • Nested classes/interfaces inherited from class javax.swing.JPanel

        javax.swing.JPanel.AccessibleJPanel

      • Nested classes/interfaces inherited from class javax.swing.JComponent

        javax.swing.JComponent.AccessibleJComponent

      • Nested classes/interfaces inherited from class java.awt.Container

        java.awt.Container.AccessibleAWTContainer

      • Nested classes/interfaces inherited from class java.awt.Component

        java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

    • Constructor Summary

      Constructors 
      Constructor Description
      DefaultDockingPort()
      Creates a new DefaultDockingPort with a persistent ID equal to the String value of this a random UUID.
      DefaultDockingPort​(java.lang.String id)
      Creates a new DefaultDockingPort with the specified persistent ID.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.awt.Component add​(java.awt.Component comp)
      Overridden to set the currently docked component.
      java.awt.Component add​(java.awt.Component comp, int index)
      Overridden to set the currently docked component.
      void add​(java.awt.Component comp, java.lang.Object constraints)
      Overridden to set the currently docked component.
      void add​(java.awt.Component comp, java.lang.Object constraints, int index)
      Overridden to set the currently docked component.
      java.awt.Component add​(java.lang.String name, java.awt.Component comp)
      Overridden to set the currently docked component.
      void addDockingListener​(DockingListener listener)
      Adds a DockingListener to observe docking events for this DockingPort.
      void clear()
      Removes all Dockables from this DockingPort.
      protected BorderManager createBorderManager()
      Creates a standard border manager for this docking port.
      protected java.awt.LayoutManager createLayout()  
      protected javax.swing.JTabbedPane createTabbedPane()
      If this method returns null, implementations may throw NullPointerExceptions.
      boolean dock​(java.awt.Component comp, java.lang.String region)
      Docks the specified component within the specified region.
      boolean dock​(Dockable dockable, java.lang.String region)
      Docks the specified Dockable within the specified region.
      void dockingCanceled​(DockingEvent evt)
      No operation.
      void dockingComplete​(DockingEvent evt)
      Requests activation for the newly docked Dockable.
      void dragStarted​(DockingEvent evt)
      No operation.
      void dropStarted​(DockingEvent evt)
      No operation.
      LayoutNode exportLayout()
      Returns a LayoutNode containing metadata that describes the current layout contained within this DefaultDockingPort.
      BorderManager getBorderManager()
      Returns the currently intalled BorderManager.
      protected Dockable getCenterDockable()  
      java.awt.Component getComponent​(java.lang.String region)
      Returns the Component currently docked within the specified region.
      Dockable getDockable​(java.lang.String region)
      Returns the Dockable currently docked within the specified region.
      Dockable getDockableAt​(java.awt.Point location)
      Returns the direct child Dockable located at the specified Point.
      java.util.Set getDockables()
      Returns all Dockables docked within this DockingPort and all sub-DockingPorts.
      protected java.util.Set getDockableSet​(int depth, int level, java.lang.Class desiredClass)  
      java.awt.Component getDockedComponent()
      Returns the child Component currently embedded within with DockingPort.
      DockingListener[] getDockingListeners()
      Returns an array of all DockingListeners added to this DockingPort.
      DockingPortPropertySet getDockingProperties()
      Returns a DockingPortPropertySet instance associated with this DockingPort.
      DockingStrategy getDockingStrategy()
      Returns the DockingStrategy used by this DockingPort.
      protected int getInitTabPlacement()  
      java.lang.String getPersistentId()
      Returns a String identifier that is unique to DockingPorts within a JVM instance, but persistent across JVM instances.
      java.lang.String getRegion​(java.awt.Point location)
      Returns the docking region within this DockingPort that contains the specified Point.
      RegionChecker getRegionChecker()
      Returns the RegionChecker currently used by this DockingPort.
      void importLayout​(LayoutNode node)
      Clears out the existing layout within this DockingPort and reconstructs a new layout based upon the specified LayoutNode.
      void installMaximizedDockable​(Dockable dockable)
      Asks this DockingPort to temporarily install the specified Dockable and maximize its component.
      boolean isDockingAllowed​(java.awt.Component comp, java.lang.String region)
      Returns true if docking is allowed for the specified Component within the supplied region, false otherwise.
      boolean isParentDockingPort​(java.awt.Component comp)
      Indicates whether or not the specified component is docked somewhere within this DefaultDockingPort.
      boolean isRoot()
      Returns a boolean indicating whether or not this DockingPort is nested within another DockingPort.
      boolean isSingleTabAllowed()
      Returns true if single tabs are allowed within this DockingPort, false otherwise.
      boolean isTabsAsDragSource()
      Returns true if drag-to-dock support is enabled for tabs and their associated Dockables, false otherwise.
      protected boolean isValidDockableChild​(java.awt.Component c, java.lang.Class desiredClass)  
      protected boolean isValidDockingRegion​(java.lang.String region)  
      void paint​(java.awt.Graphics g)
      Overridden to provide enhancements during drag operations.
      void releaseForMaximization​(Dockable dockable)
      Asks this DockingPort to temporarily release its child Dockable for use by another DockingPort to achieve maximization.
      void remove​(int index)
      Overridden to decorate superclass method, keeping track of internal docked-component reference.
      void removeAll()
      Overridden to decorate superclass method, keeping track of internal docked-component reference.
      void removeDockingListener​(DockingListener listener)
      Removes the specified DockingListener from this DockingPort.
      void returnFromMaximization()
      Notifies this DockingPort that the Dockable previously released for maximization via a call to DockingPort.releaseForMaximization(Dockable) is now ready to be returned to its original state inside this DockingPort.
      void setBorderManager​(BorderManager mgr)
      Sets the currently installed BorderManager.
      void setDragInProgress​(boolean inProgress)
      This method is used internally by the framework to notify DefaultDockingPorts whether a drag operation is or is not currently in progress and should not be called by application-level developers.
      void setPersistentId​(java.lang.String id)
      Sets the persisent ID to be used for this DockingPort.
      void setRoot​(boolean root)
      This method is used internally by the framework to notify DefaultDockingPorts whether they are "root" DockingPorts according to the rules specified by isRoot() on the DockingPort interface.
      void setSingleTabAllowed​(boolean allowed)
      Sets the "single tab" property for this DockingPort, allowing or disallowing a single Dockable within the DockingPort to appear within a tabbed layout.
      void setTabsAsDragSource​(boolean enabled)
      Enables or disables drag support for docking operations on the tabs used within an embedded tabbed layout.
      boolean undock​(java.awt.Component comp)
      Undocks the specified Component and returns a boolean indicating the success of the operation.
      void undockingComplete​(DockingEvent evt)
      No operation.
      void undockingStarted​(DockingEvent evt)
      No operation.
      void uninstallMaximizedDockable()
      Notifies this DockingPort that the Dockable previously installed for maximization via a call to DockingPort.installMaximizedDockable(Dockable) should now be returned to its original DockingPort and that this DockingPort should return to its original state from before the call to DockingPort.installMaximizedDockable(Dockable).
      protected void updateTab​(Dockable dockable)  

      • Methods inherited from class javax.swing.JPanel

        getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

      • Methods inherited from class javax.swing.JComponent

        addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

      • Methods inherited from class java.awt.Container

        addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree

      • Methods inherited from class java.awt.Component

        action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • dockingListeners

        protected java.util.ArrayList dockingListeners

    • Constructor Detail

      • DefaultDockingPort

        public DefaultDockingPort()
        Creates a new DefaultDockingPort with a persistent ID equal to the String value of this a random UUID.
        See Also:
        UUID

      • DefaultDockingPort

        public DefaultDockingPort​(java.lang.String id)
        Creates a new DefaultDockingPort with the specified persistent ID. If id is null, then the String value of this Object's hash code is used. The persistent ID will be the same value returned by invoking getPersistentId() for this DefaultDockingPort.
        Parameters:
        id - the persistent ID for the new DefaultDockingPort instance.

    • Method Detail

      • createLayout

        protected java.awt.LayoutManager createLayout()

      • createBorderManager

        protected BorderManager createBorderManager()
        Creates a standard border manager for this docking port.

        This method is called from the constructor.

        Returns:
        the border manager for this docking port.

      • add

        public java.awt.Component add​(java.awt.Component comp)
        Overridden to set the currently docked component. Should not be called by application code.
        Overrides:
        add in class java.awt.Container
        Parameters:
        comp - the component to be added

      • add

        public java.awt.Component add​(java.awt.Component comp,
                              int index)
        Overridden to set the currently docked component. Should not be called by application code.
        Overrides:
        add in class java.awt.Container
        Parameters:
        comp - the component to be added
        index - the position at which to insert the component, or -1 to append the component to the end

      • add

        public void add​(java.awt.Component comp,
                java.lang.Object constraints)
        Overridden to set the currently docked component. Should not be called by application code.
        Overrides:
        add in class java.awt.Container
        Parameters:
        comp - the component to be added
        constraints - an object expressing layout contraints for this component

      • add

        public void add​(java.awt.Component comp,
                java.lang.Object constraints,
                int index)
        Overridden to set the currently docked component. Should not be called by application code.
        Overrides:
        add in class java.awt.Container
        Parameters:
        comp - the component to be added
        constraints - an object expressing layout contraints for this
        index - the position in the container's list at which to insert the component; -1 means insert at the end

      • add

        public java.awt.Component add​(java.lang.String name,
                              java.awt.Component comp)
        Overridden to set the currently docked component. Should not be called by application code.
        Overrides:
        add in class java.awt.Container
        Parameters:
        name - the name of the Component to be added.
        comp - the Component to add.

      • isDockingAllowed

        public boolean isDockingAllowed​(java.awt.Component comp,
                                java.lang.String region)
        Returns true if docking is allowed for the specified Component within the supplied region, false otherwise. It is important to note that success of a docking operation relies on many factors and a return value of true from this method does not necessarily guarantee that a call to dock() will succeed. This method merely indicates that the current DockingPort does not have any outstanding reason to block a docking operation with respect to the specified Component and region.

        If comp is null or region is invalid according to DockingManager.isValidDockingRegion(String region), then this method returns false.

        If this DockingPort is not already the parent DockingPort for the specified Component, then this method returns true.

        If this DockingPort is already the parent DockingPort for the specified Component, then a check is performed to see if there is a tabbed layout. Tabbed layouts may contain multiple Dockables, and thus the tab ordering may be rearranged, or shifted into a split layout. If comp is the only docked Component within this DockingPort, then this method returns false since the layout cannot be rearranged. Otherwise, this method returns true.

        Specified by:
        isDockingAllowed in interface DockingPort
        Parameters:
        comp - the Component whose docking availability is to be checked
        region - the region to be checked for docking availability for the specified Component.
        Returns:
        true if docking is allowed for the specified Component within the supplied region, false otherwise.
        See Also:
        DockingPort.isDockingAllowed(Component, String), DockingManager.isValidDockingRegion(String), isParentDockingPort(Component)

      • getRegion

        public java.lang.String getRegion​(java.awt.Point location)
        Returns the docking region within this DockingPort that contains the specified Point. Valid return values are those regions defined in DockingConstants and include NORTH_REGION, SOUTH_REGION, EAST_REGION, WEST_REGION, CENTER_REGION, and UNKNOWN_REGION.

        If location is null, then UNKNOWN_REGION is returned.

        This method gets the RegionChecker for this DockingPort by calling getRegionChecker(). It then attempts to locate the Dockable at the specified location by calling getDockableAt(Point location).

        This method defers processing to getRegion(Component c, Point p) for the current RegionChecker. If a Dockable was found at the specified Point, then the location of the Point is translated to the coordinate system of the Component for the embedded Dockable and that Component and modified Point are passed into getRegion(Component c, Point p)} for the current RegionChecker. If no Dockable was found, then the specified Point is left unmodified and this DockingPort and the supplied Point are passed to getRegion(Component c, Point p)} for the current RegionChecker.

        Specified by:
        getRegion in interface DockingPort
        Parameters:
        location - the location within this DockingPort to examine for a docking region.
        Returns:
        the docking region within this DockingPort that contains the specified Point
        See Also:
        getRegionChecker(), getDockableAt(Point), Dockable.getComponent(), RegionChecker.getRegion(Component, Point)

      • getRegionChecker

        public RegionChecker getRegionChecker()
        Returns the RegionChecker currently used by this DockingPort. This method retrieves the DockingPortPropertySet instance for this DockingPort by calling getDockingProperties(). It then returns by invoking getRegionChecker() on the resolved DockingPortPropertySet.
        Returns:
        the RegionChecker currently used by this DockingPort.
        See Also:
        getDockingProperties(), DockingPortPropertySet.getRegionChecker()

      • getDockableAt

        public Dockable getDockableAt​(java.awt.Point location)
        Returns the direct child Dockable located at the specified Point. If location is null, or this DockingPort is empty, then a null reference is returned.

        If this DockingPort contains a split layout, then any nested Dockables will be within a sub-DockingPort and not a direct child of this DockingPort. Therefore, if getDockedComponent() returns a JSplitPane, then this method will return a null reference.

        If this DockingPort contains a tabbed layout, then the JTabbedPane returned by getDockedComponent() will be checked for a Dockable at the specified Point.

        Parameters:
        location - the location within the DockingPort to test for a Dockable.
        Returns:
        the direct child Dockable located at the specified Point.
        See Also:
        getDockedComponent(), DockingManager.getDockable(Component), Container.getComponentAt(int x, int y)

      • getComponent

        public java.awt.Component getComponent​(java.lang.String region)
        Returns the Component currently docked within the specified region.

        If this DockingPort has either a single child Dockable or a tabbed layout, then the supplied region must be CENTER_REGION or this method will return a null reference. If there is a single child Dockable, then this method will return the same Component as returned by getDockedComponent(). If there is a tabbed layout, then this method will return the Component in the currently selected tab.

        If this DockingPort has a split layout, then a check for CENTER_REGION will return a null reference. For outer regions (NORTH_REGION, SOUTH_REGION, EAST_REGION, or WEST_REGION), the supplied region parameter must match the orientation of the embedded JSplitPane. Thus for a vertically oriented split pane, checks for EAST_REGION and WEST_REGION will return a null reference. Likewise, for a horizontally oriented split pane, checks for NORTH_REGION and SOUTH_REGION will return a null reference.

        Outer regions are mapped to corresponding split pane regions. NORTH_REGION maps to the split pane's top component, SOUTH_REGION maps to the bottom, EAST_REGION maps to the right, and WEST_REGION maps to the left. The sub-DockingPort for the split pane region that corresponds to the specified region parameter will be resolved and this method will return that Component retrieved by calling its getDockedComponent() method. Note that the getDockedComponent() call to a sub- DockingPort implies that the JTabbedPane or JSplitPane for the sub-port may be returned if the sub-port contains multiple Dockables.

        If this DockingPort is empty, then this method returns a null reference.

        Specified by:
        getComponent in interface DockingPort
        Parameters:
        region - the region to be checked for a docked Component
        Returns:
        the Component docked within the specified region.
        See Also:
        DockingPort.getComponent(String), getDockedComponent()

      • getDockable

        public Dockable getDockable​(java.lang.String region)
        Returns the Dockable currently docked within the specified region. This method dispatches to getComponent(String region) to retrieve the Component docked within the specified region and returns its associated Dockable via DockingManager.getDockable(Component comp).

        There are somewhat strict semantics associated with retrieving the Component in a particular docking region. API documentation for getComponent(String region) should be referenced for a listing of the rule set. If region is invalid according to DockingManager.isValidDockingRegion(String region), then this method returns a null reference.

        Specified by:
        getDockable in interface DockingPort
        Parameters:
        region - the region to be checked for a docked Dockable
        Returns:
        the Dockable docked within the specified region.
        See Also:
        DockingPort.getDockable(String), getComponent(String), getDockedComponent(), DockingManager.getDockable(Component), DockingManager.isValidDockingRegion(String)

      • createTabbedPane

        protected javax.swing.JTabbedPane createTabbedPane()
        If this method returns null, implementations may throw NullPointerExceptions. Do not expect NPE checking.
        Returns:
        a valid JTabbedPane.

      • updateTab

        protected void updateTab​(Dockable dockable)

      • clear

        public void clear()
        Removes all Dockables from this DockingPort. Internally, this method dispatches to removeAll(). This ensures that not only docked Components are removed, that that all wrapper containers such as JTabbedPanes, JSplitPanes, and sub-DockingPorts are removed as well.
        Specified by:
        clear in interface DockingPort
        See Also:
        DockingPort.clear(), removeAll()

      • dock

        public boolean dock​(java.awt.Component comp,
                    java.lang.String region)
        Docks the specified component within the specified region. This method attempts to resolve the Dockable associated with the specified Component by invoking DockingManager.getDockable(Component comp). Processing is then dispatched to dock(Dockable dockable, String region).

        If no Dockable is resolved for the specified Component, then this method attempts to register the Component as a Dockable automatically by calling DockingManager.registerDockable(Component comp).

        If either comp or region region are null, then this method returns false. Otherwise, this method returns a boolean indicating the success of the docking operation based upon dock(Dockable dockable, String region).

        Specified by:
        dock in interface DockingPort
        Parameters:
        comp - the Component to be docked within this DockingPort
        region - the region within this DockingPort to dock the specified Component
        Returns:
        true if the docking operation was successful, false otherwise.
        See Also:
        DockingPort.dock(Component, String), dock(Dockable, String), DockingManager.getDockable(Component), DockingManager.registerDockable(Component)

      • dock

        public boolean dock​(Dockable dockable,
                    java.lang.String region)
        Docks the specified Dockable within the specified region. The Component used for docking is returned by calling getComponent() on the specified Dockable. This method returns false immediately if the specified Dockable is null or if isDockingAllowed(Component comp, String region) returns false.

        If this DockingPort is currently empty, then the Dockable is docked into the CENTER_REGION, regardless of the supplied region parameter's value.

        If isSingleTabAllowed() returns false and the DockingPort is emtpy, then the Dockable will be added directly to the DockingPort and will take up all available space within the DockingPort. In this case, subsequent calls to getDockedComponent() will return the dockable Component.

        If isSingleTabAllowed() returns true and the DockingPort is emtpy, then a JTabbedPane will be added directly to the DockingPort and will take up all available space within the DockingPort. The dockable Component will be added as a tab within the tabbed pane. In this case, subsequent calls to getDockedComponent() will return the JTabbedPane.

        If the DockingPort is not empty, and the specified region is CENTER_REGION, then the dockable Component will be added to the JTabbedPane returned by getDockedComponent(). If this DockingPort only contained a single dockable Component without a tabbed pane, then the currently docked Component is removed, a JTabbedPane is created and added, and both the old Component and the new one are added to the JTabbedPane. In this case, subsequent calls to getDockedComponent() will return the JTabbedPane.

        If the DockingPort is not empty, and the specified region is NORTH_REGION, SOUTH_REGION, EAST_REGION, or WEST_REGION, then the currently docked Component is removed and replaced with a JSplitPane. Two new DefaultDockingPorts are created as sub-ports and are added to each side of the JSplitPane. The previously docked Component is docked to the CENTER_REGION of one of the sub-ports and the new Component is added to the other. In this case, subsequent calls to getDockedComponent() will return the JSplitPane. In this fasion, the sub-ports will now be capable of handling further sub-docking within the layout.

        JSplitPane and sub-DockingPort creation are delegated to the DockingStrategy returned by getDockingStrategy(). Initial splitpane divider location is also controlled by this DockingStrategy.

        Specified by:
        dock in interface DockingPort
        Parameters:
        dockable - the Dockable to be docked within this DockingPort
        region - the region within this DockingPort to dock the specified Dockable
        Returns:
        true if the docking operation was successful, false otherwise.
        See Also:
        DockingPort.dock(Dockable, String), isDockingAllowed(Component, String), getDockedComponent(), getDockingStrategy(), DockingStrategy.createDockingPort(DockingPort), DockingStrategy.createSplitPane(DockingPort, String), DockingStrategy.getInitialDividerLocation(DockingPort, JSplitPane), DockingStrategy.getDividerProportion(DockingPort, JSplitPane)

      • getDockedComponent

        public java.awt.Component getDockedComponent()
        Returns the child Component currently embedded within with DockingPort. If the DockingPort is empty, then this method returns a null reference. If there is a single Dockable docked within it with no tabbed layout, then the Component for that Dockable is returned per its getComponent() method. If there is a tabbed layout present, then a JTabbedPane is returned. If there is a split layout present, then a JSplitPane is returned.
        Specified by:
        getDockedComponent in interface DockingPort
        See Also:
        DockingPort.getDockedComponent()

      • getPersistentId

        public java.lang.String getPersistentId()
        Returns a String identifier that is unique to DockingPorts within a JVM instance, but persistent across JVM instances. This is used for configuration mangement, allowing the JVM to recognize a DockingPort instance within an application instance, persist the ID, and recall it in later application instances. The ID should be unique within an appliation instance so that there are no collisions with other DockingPort instances, but it should also be consistent from JVM to JVM so that the association between a DockingPort instance and its ID can be remembered from session to session.

        The value returned by this method will come from the most recent call to setPersistentId(String id). If setPersistentId(String id) was invoked with a null argument, then the String verion of this DockingPort's hash code is used. Therefore, this method will never return a null reference.

        Specified by:
        getPersistentId in interface DockingPort
        Returns:
        the persistent ID for this DockingPort
        See Also:
        DockingPort.getPersistentId(), setPersistentId(String), DockingManager.getDockingPort(String)

      • setPersistentId

        public void setPersistentId​(java.lang.String id)
        Sets the persisent ID to be used for this DockingPort. If id is null, then the String value of this DockingPort's hash code is used.

        DockingPorts are tracked by persistent ID within DockingManager. Whenever this method is called, the DockingManager's tracking mechanism is automatically upated for this DockingPort.

        Specified by:
        setPersistentId in interface DockingPort
        Parameters:
        id - the persistent ID to be used for this DockingPort
        See Also:
        getPersistentId(), DockingManager.getDockingPort(String), DockingPortTracker.updateIndex(DockingPort)

      • isSingleTabAllowed

        public boolean isSingleTabAllowed()
        Returns true if single tabs are allowed within this DockingPort, false otherwise.

        Generally the tabbed interface does not appear until two or more Dockables are docked to the CENTER_REGION of the DockingPort and tabs are required to switch between them. When there is only a single Dockable within the DockingPort, the default behavior for the dockable Component to take up all of the space within the DockingPort.

        If this method returns true, then a single Dockable within this DockingPort will reside within a tabbed layout that contains only one tab.

        The value returned by this method is a scoped property. This means there may be many different "scopes" at which the single-tab property may be set. For instance, a "global" setting may override the individual setting for this DockingPort, and this DockingPort's particular setting may override the global default setting. org.flexdock.docking.props.PropertyManager should be referenced for further information on scoped properties.

        Returns:
        true if single tabs are allowed within this DockingPort, false otherwise.
        See Also:
        setSingleTabAllowed(boolean), DockingManager.isSingleTabsAllowed(), DockingManager.setSingleTabsAllowed(boolean), PropertyManager, DockingPortPropertySet.isSingleTabsAllowed(), DockingPortPropertySet.setSingleTabsAllowed(boolean)

      • setSingleTabAllowed

        public void setSingleTabAllowed​(boolean allowed)
        Sets the "single tab" property for this DockingPort, allowing or disallowing a single Dockable within the DockingPort to appear within a tabbed layout.

        Generally the tabbed interface does not appear until two or more Dockables are docked to the CENTER_REGION of the DockingPort and tabs are required to switch between them. When there is only a single Dockable within the DockingPort, the default behavior for the dockable Component to take up all of the space within the DockingPort.

        If the single tab property is set to true, then a single Dockable within this DockingPort will reside within a tabbed layout that contains only one tab.

        The single tab property is a scoped property. This means there may be many different "scopes" at which the single-tab property may be set. For instance, a "global" setting may override the individual setting for this DockingPort, and this DockingPort's particular setting may override the global default setting. This method applied a value only to the local scope for this particular DockingPort. org.flexdock.docking.props.PropertyManager should be referenced for further information on scoped properties.

        Parameters:
        allowed - true if a single-tabbed layout should be allowed, false otherwise
        See Also:
        isSingleTabAllowed(), DockingManager.setSingleTabsAllowed(boolean), DockingManager.isSingleTabsAllowed(), PropertyManager, DockingPortPropertySet.setSingleTabsAllowed(boolean), DockingPortPropertySet.isSingleTabsAllowed()

      • isParentDockingPort

        public boolean isParentDockingPort​(java.awt.Component comp)
        Indicates whether or not the specified component is docked somewhere within this DefaultDockingPort. This method returns true if the specified Component is a direct child of the DefaultDockingPort or is a direct child of a JTabbedPane or JSplitPanethat is currently the DefaultDockingPort'sdocked component. Otherwise, this method returns false. If comp is null, then then this method return false
        Specified by:
        isParentDockingPort in interface DockingPort
        Parameters:
        comp - the Component to be tested.
        Returns:
        a boolean indicating whether or not the specified component is docked somewhere within this DefaultDockingPort.
        See Also:
        DockingPort.isParentDockingPort(java.awt.Component), Component.getParent(), getDockedComponent()

      • isValidDockingRegion

        protected boolean isValidDockingRegion​(java.lang.String region)

      • getCenterDockable

        protected Dockable getCenterDockable()

      • remove

        public void remove​(int index)
        Overridden to decorate superclass method, keeping track of internal docked-component reference.
        Overrides:
        remove in class java.awt.Container
        Parameters:
        index - the index of the component to be removed.
        See Also:
        Container.remove(int)

      • removeAll

        public void removeAll()
        Overridden to decorate superclass method, keeping track of internal docked-component reference.
        Overrides:
        removeAll in class java.awt.Container
        See Also:
        Container.removeAll()

      • setBorderManager

        public void setBorderManager​(BorderManager mgr)
        Sets the currently installed BorderManager. This method provides a means of customizing border managment following any successful call to dock(Dockable dockable, String region) or undock(Component comp), allowing cleanup of borders for nested Components within the docking layout. null values are allowed.
        Parameters:
        mgr - the BorderManager assigned to to manage docked component borders.
        See Also:
        getBorderManager(), BorderManager

      • getBorderManager

        public BorderManager getBorderManager()
        Returns the currently intalled BorderManager. The BorderManager is used any time a successful call to dock(Dockable dockable, String region) or undock(Component comp) has been issued to clean up borders for nested Components within the docking layout. This method will return a null reference if there is no BorderManager installed.
        Returns:
        the currently installed BorderManager.
        See Also:
        setBorderManager(BorderManager), BorderManager

      • undock

        public boolean undock​(java.awt.Component comp)
        Undocks the specified Component and returns a boolean indicating the success of the operation.

        Since DefaultDockingPort may only contain one child component, there i s 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 JSplitPane renders the child DefaultDockingPort unnecessary, which, in turn, renders the notion of splitting the layout with a JSplitPane unnecessary (since there are no longer two components to split the layout between). Likewise, removing a child component from a JTabbedPane such that there is only one child left within the JTabbedPane removes the need for a tabbed interface to begin with.

        This method automatically handles the reevaluation of the container hierarchy to keep wrapper-container usage at a minimum. Since DockingManager makes this callback automatic, developers normally will not need to call this method explicitly. However, when removing a component from a DefaultDockingPort using application code, developers should keep in mind to use this method instead of remove().

        Specified by:
        undock in interface DockingPort
        Parameters:
        comp - the Component to be undocked.
        Returns:
        a boolean indicating the success of the operation
        See Also:
        DockingPort.undock(Component comp), DockingManager.undock(Dockable)

      • getDockables

        public java.util.Set getDockables()
        Returns all Dockables docked within this DockingPort and all sub-DockingPorts. The returned Set will contain Dockable instances. If there are no Dockables present, an empty Set will be returned. This method will never return a null reference.
        Specified by:
        getDockables in interface DockingPort
        Returns:
        all Dockables docked within this DockingPort and all sub-DockingPorts.
        See Also:
        DockingPort.getDockables()

      • getDockableSet

        protected java.util.Set getDockableSet​(int depth,
                                       int level,
                                       java.lang.Class desiredClass)

      • isValidDockableChild

        protected boolean isValidDockableChild​(java.awt.Component c,
                                       java.lang.Class desiredClass)

      • setTabsAsDragSource

        public void setTabsAsDragSource​(boolean enabled)
        Enables or disables drag support for docking operations on the tabs used within an embedded tabbed layout. If tab-drag-source is enabled, then the tab that corresponds to a Dockable within an embedded tabbed layout will respond to drag events as if the tab were a component included within the List returned by calling getDragSources() on the Dockable. This allows dragging a tab to initiate drag-to-dock operations.
        Parameters:
        enabled - true if drag-to-dock support should be enabled for tabs and their associated Dockables, false otherwise.
        See Also:
        isTabsAsDragSource(), Dockable.getDragSources()

      • isTabsAsDragSource

        public boolean isTabsAsDragSource()
        Returns true if drag-to-dock support is enabled for tabs and their associated Dockables, false otherwise. If tab-drag-source is enabled, then the tab that corresponds to a Dockable within an embedded tabbed layout will respond to drag events as if the tab were a component included within the List returned by calling getDragSources() on the Dockable. This allows dragging a tab to initiate drag-to-dock operations.
        Returns:
        true if drag-to-dock support is enabled for tabs and their associated Dockables, false otherwise.
        See Also:
        setTabsAsDragSource(boolean), Dockable.getDragSources()

      • getInitTabPlacement

        protected int getInitTabPlacement()

      • isRoot

        public boolean isRoot()
        Returns a boolean indicating whether or not this DockingPort is nested within another DockingPort. If there are no other DockingPorts within this DockingPort's container ancestor hierarchy, then this method will return true. Otherwise, this method will return false. If the this DockingPort is not validated and/or is not part of a container hierarchy, this method should return true.
        Specified by:
        isRoot in interface DockingPort
        Returns:
        false if this DockingPort is nested within another DockingPort, true otherwise.
        See Also:
        DockingPort.isRoot()

      • setRoot

        public void setRoot​(boolean root)
        This method is used internally by the framework to notify DefaultDockingPorts whether they are "root" DockingPorts according to the rules specified by isRoot() on the DockingPort interface. This method should not be called by application-level developers. It will most likely be removed in future versions and the logic contained herein will be managed by some type of change listener.
        Parameters:
        root - true if this is a "root" DockingPort, false otherwise.
        See Also:
        isRoot(), DockingPort.isRoot()

      • setDragInProgress

        public void setDragInProgress​(boolean inProgress)
        This method is used internally by the framework to notify DefaultDockingPorts whether a drag operation is or is not currently in progress and should not be called by application-level developers. It will most likely be removed in future versions and the logic contained herein will be managed by some type of change listener.
        Parameters:
        inProgress - true if a drag operation involving this DockingPort is currently in progress, false otherwise.

      • paint

        public void paint​(java.awt.Graphics g)
        Overridden to provide enhancements during drag operations. Some DragPreview implementations may by able to supply a BufferedImage for this DockingPort to use for painting operations. This may be useful for cases in which the dimensions of docked Components are altered in realtime during the drag operation to provide a "ghost" image for the DragPreview. In this case, visual feedback for altered subcomponents within this DockingPort may be blocked in favor of a temporary BufferedImage for the life of the drag operation.
        Overrides:
        paint in class javax.swing.JComponent
        Parameters:
        g - the Graphics context in which to paint
        See Also:
        JComponent.paint(java.awt.Graphics)

      • importLayout

        public void importLayout​(LayoutNode node)
        Clears out the existing layout within this DockingPort and reconstructs a new layout based upon the specified LayoutNode.

        At present, this method can only handle LayoutNodes that have been generated by DefaultDockingPort's exportLayout() method. If the specified LayoutNode is null or is otherwise not an instance of DockingPortNode, then this method returns immediately with no action taken.

        Otherwise, the necessary Dockables are docked within this DockingPort and all subsequently generated sub-DockingPorts in a visual configuration mandated by the tree structure modeled by the specified LayoutNode.

        Specified by:
        importLayout in interface DockingPort
        Parameters:
        node - the LayoutNode whose layout is to be instantiated within this DockingPort
        See Also:
        DockingPort.importLayout(LayoutNode), exportLayout(), LayoutNode, DockingNode, DockingPortNode, SplitNode, DockableNode

      • installMaximizedDockable

        public void installMaximizedDockable​(Dockable dockable)
        Description copied from interface: DockingPort
        Asks this DockingPort to temporarily install the specified Dockable and maximize its component. This method is called by DockingManager in the course of maximizing a Dockable. Client code should not call this method directly.

        This DockingPort is expected to display the specified dockable's component such that it occupies all (or the majority) of its screen resources. Also, this DockingPort is expected to internally store enough information to restore its current state after a subsequent call to DockingPort.uninstallMaximizedDockable().

        Specified by:
        installMaximizedDockable in interface DockingPort
        Parameters:
        dockable - the Dockable that is requested to be maximized
        See Also:
        DockingManager.toggleMaximized(Component), DockingManager.toggleMaximized(Dockable)

      • releaseForMaximization

        public void releaseForMaximization​(Dockable dockable)
        Description copied from interface: DockingPort
        Asks this DockingPort to temporarily release its child Dockable for use by another DockingPort to achieve maximization. This method is called by DockingManager in the course of maximizing a Dockable. Client code should not call this method directly.

        This DockingPort is expected to remove the specified dockable's component from its swing container hierarchy. Also, this DockingPort is expected to internally store enough information to restore its current state after a subsequent call to DockingPort.returnFromMaximization().

        Specified by:
        releaseForMaximization in interface DockingPort
        Parameters:
        dockable - the Dockable that is requested to be maximized
        See Also:
        DockingManager.toggleMaximized(Component), DockingManager.toggleMaximized(Dockable)