Package org.flexdock.docking

Interface DockingStrategy

  • All Known Implementing Classes:
    DefaultDockingStrategy
    public interface DockingStrategy
    This interface defines an API used by DockingManager and DockingPort to support customizable behaviors during docking operations. DockingManager will associate a DockingStrategy with a particular DockingPort or Dockable class type. Calls to DockingManager.dock() and DockingManager.undock() will be deferred to the DockingStrategy associated with the parameters supplied in the respective method calls. DockingStrategies are also responsible for creating sub-DockingPorts and split panes for nested DockingPorts Implementations of DockingStrategy are responsible for managing component relationships between Dockables and parent containers. This includes making determinations as to whether a particular docking operation will be allowed for the specified parameters and the specifics of how a particular Dockable may be removed from one parent Container or DockingPort and added to another. DockingStrategy may determine whether a call to dock() implies an attempt to float a Dockable in a separate window. Because of the potentially large scope of responsibilities associated with a DockingStrategy, implementations may range from being very simple to highly complex. Although custom implementations of DockingStrategy are not discouraged, the recommeded path is to subclass DefaultDockingStrategy for consistency of behavior. DockingStrategies are associated with a particular type of Dockable or DockingPort by calling DockingManager.setDockingStrategy(Class c, DockingStrategy strategy). DefaultDockingStrategy is the default implementation used for all classes that do not have a custom DockingStrategy registered.
    Author:
    Christopher Butler

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      DockingPort createDockingPort​(DockingPort base)
      Creates and returns a new DockingPort instance based upon the supplied DockingPort parameter.
      javax.swing.JSplitPane createSplitPane​(DockingPort base, java.lang.String region)
      Creates and returns a new JSplitPane instance based upon the supplied parameters.
      javax.swing.JSplitPane createSplitPane​(DockingPort base, java.lang.String region, float percent)
      Creates and returns a new JSplitPane instance based upon the supplied parameters.
      boolean dock​(Dockable dockable, DockingPort dockingPort, java.lang.String dockingRegion)
      Attempts to dock the specified Dockable into the supplied DockingPort in the specified region.
      boolean dock​(Dockable dockable, DockingPort dockingPort, java.lang.String dockingRegion, DragOperation operation)
      Attempts to dock the specified Dockable into the supplied DockingPort in the specified region based upon the semantics of the specified DragOperation.
      double getDividerProportion​(DockingPort dockingPort, javax.swing.JSplitPane splitPane)
      Returns the desired divider proportion of the specified JSplitPane after rendering.
      int getInitialDividerLocation​(DockingPort dockingPort, javax.swing.JSplitPane splitPane)
      Returns the initial divider location to be used by the specified JSplitPane.
      boolean undock​(Dockable dockable)
      Undocks the specified Dockable instance from its containing DockingPort.

    • Method Detail

      • dock

        boolean dock​(Dockable dockable,
             DockingPort dockingPort,
             java.lang.String dockingRegion)
        Attempts to dock the specified Dockable into the supplied DockingPort in the specified region. If docking is not possible for the specified parameters, then the method returns false and no action is taken. Since there is no DragOperation parameter present, this method implies programmatic docking as opposed to docking as a result of drag-events.
        Parameters:
        dockable - the Dockable we wish to dock
        dockingPort - the DockingPort into which we wish to dock
        dockingRegion - the region of the specified DockingPort into which we wish to dock.
        Returns:
        whether or not the docking operation was successful.

      • dock

        boolean dock​(Dockable dockable,
             DockingPort dockingPort,
             java.lang.String dockingRegion,
             DragOperation operation)
        Attempts to dock the specified Dockable into the supplied DockingPort in the specified region based upon the semantics of the specified DragOperation. If docking is not possible for the specified parameters, then the method returns false and no action is taken.
        Parameters:
        dockable - the Dockable we wish to dock
        dockingPort - the DockingPort into which we wish to dock
        dockingRegion - the region of the specified DockingPort into which we wish to dock.
        operation - the DragOperation describing the state of the application/mouse at the point in time in which we're attempting to dock.
        Returns:
        whether or not the docking operation was successful.

      • undock

        boolean undock​(Dockable dockable)
        Undocks the specified Dockable instance from its containing DockingPort.
        Parameters:
        dockable - the Dockable we wish to undock
        Returns:
        true if the Dockable was successfully undocked. Otherwise, returns false.

      • createDockingPort

        DockingPort createDockingPort​(DockingPort base)
        Creates and returns a new DockingPort instance based upon the supplied DockingPort parameter. For layouts that support nested DockingPorts, this method is useful for creating child DockingPorts suitable for embedding within the base DockingPort
        Parameters:
        base - the DockingPort off of which the returned instance will be based.
        Returns:
        a new DockingPort instance based upon the supplied parameter.

      • createSplitPane

        javax.swing.JSplitPane createSplitPane​(DockingPort base,
                                       java.lang.String region)
        Creates and returns a new JSplitPane instance based upon the supplied parameters. The returned JSplitPane should be suitable for embedding within the base DockingPort and its orientation should reflect the supplied region parameter.
        Parameters:
        base - the DockingPort off of which the returned JSplitPane will be based.
        region - the region within the base DockingPort used to determine the orientation of the returned JSplitPane.
        Returns:
        a new JSplitPane suitable for embedding within the base DockingPort parameter.

      • createSplitPane

        javax.swing.JSplitPane createSplitPane​(DockingPort base,
                                       java.lang.String region,
                                       float percent)
        Creates and returns a new JSplitPane instance based upon the supplied parameters. The returned JSplitPane should be suitable for embedding within the base DockingPort and its orientation should reflect the supplied region parameter.
        Parameters:
        base - the DockingPort off of which the returned JSplitPane will be based.
        region - the region within the base DockingPort used to determine the orientation of the returned JSplitPane.
        percent - the percentage used in the split.
        Returns:
        a new JSplitPane suitable for embedding within the base DockingPort parameter.

      • getInitialDividerLocation

        int getInitialDividerLocation​(DockingPort dockingPort,
                              javax.swing.JSplitPane splitPane)
        Returns the initial divider location to be used by the specified JSplitPane. This method assumes that the JSplitPane parameter is embedded within the specified DockingPort and that is has been validated and its current dimensions are non-zero.
        Parameters:
        dockingPort - the DockingPort that contains, or will contain the specified JSplitPane.
        splitPane - the JSplitPane whose initial divider location is to be determined.
        Returns:
        the desired divider location of the supplied JSplitPane.

      • getDividerProportion

        double getDividerProportion​(DockingPort dockingPort,
                            javax.swing.JSplitPane splitPane)
        Returns the desired divider proportion of the specified JSplitPane after rendering. This method assumes that the JSplitPane parameter is, or will be embedded within the specified DockingPort. This method does not assume that the JSplitPane has been validated and that it's current dimensions are non-zero.
        Parameters:
        dockingPort - the DockingPort that contains, or will contain the specified JSplitPane.
        splitPane - the JSplitPane whose initial divider location is to be determined.
        Returns:
        the desired divider proportion of the supplied JSplitPane.