Module org.snapfx
Package org.snapfx.model

Class DockGraph

java.lang.Object
org.snapfx.model.DockGraph
public class DockGraph extends Object
Central data structure of the docking system.

DockGraph owns the logical dock tree, independent from JavaFX rendering. It manages root assignment, docking/undocking/move operations, split/tab structures, and sidebar pin/restore state.

Example (model-level composition):


 DockGraph graph = new DockGraph();
 DockNode editor = new DockNode("editor", new TextArea(), "Editor");
 DockNode console = new DockNode("console", new TextArea(), "Console");

 graph.setRoot(editor);
 graph.dock(console, editor, DockPosition.BOTTOM);

  • Property Summary

    Properties
    Type
    Property
    Description
    javafx.beans.property.BooleanProperty
    locked
    Returns the locked property.
    javafx.beans.property.LongProperty
    revision
    Returns the observable structural revision counter.
    javafx.beans.property.ObjectProperty<DockElement>
    root
    Returns the root property of the dock graph.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    DEFAULT_SIDE_BAR_PANEL_WIDTH
    Default preferred width (in pixels) for sidebar panels.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DockGraph()
    Creates an empty dock graph with default sidebar state.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clearSideBars()
    Removes all pinned sidebar nodes and resets pinned-open sidebar state.
    void
    collapsePinnedSideBar(javafx.geometry.Side side)
    Convenience method to collapse a pinned sidebar back to strip mode.
    void
    dock(DockNode node, DockElement target, DockPosition position)
    Docks a node at a specific position relative to a target element.
    void
    dock(DockNode node, DockElement target, DockPosition position, Integer tabIndex)
    Docks a node at a specific position relative to a target element with optional tab index.
    DockElement
    findElementByLayoutId(String layoutId)
    Finds a dock element by layout ID across the main layout and pinned sidebars.
    int
    getDockNodeCount(String dockNodeId)
    Counts dock nodes by logical dock-node ID across main layout and sidebars.
    long
    getLayoutIdCounter()
    Returns the current layout ID counter value.
    javafx.geometry.Side
    getPinnedSide(DockNode node)
    Returns the sidebar side the node is pinned to, or null if it is not pinned.
    long
    getRevision()
    Gets the value of the revision property.
    DockElement
    getRoot()
    Returns the root element of the dock graph, or null if the graph is empty.
    javafx.collections.ObservableList<DockNode>
    getSideBarNodes(javafx.geometry.Side side)
    Returns the read-only list of pinned nodes for a sidebar side.
    double
    getSideBarPanelWidth(javafx.geometry.Side side)
    Returns the preferred sidebar panel width for the given side.
    boolean
    isLocked()
    Returns true if the graph is currently locked.
    boolean
    isPinnedToSideBar(DockNode node)
    Returns whether a node is currently pinned in any sidebar.
    boolean
    isSideBarPinnedOpen(javafx.geometry.Side side)
    Returns whether the sidebar for the given side is pinned-open (layout-consuming).
    javafx.beans.property.BooleanProperty
    lockedProperty()
    Returns the locked property.
    void
    move(DockNode node, DockElement target, DockPosition position)
    Moves a DockNode from one position to another.
    void
    move(DockNode node, DockElement target, DockPosition position, Integer tabIndex)
    Moves a DockNode from one position to another with optional tab index.
    void
    pinOpenSideBar(javafx.geometry.Side side)
    Convenience method to pin-open a sidebar.
    void
    pinToSideBar(DockNode node, javafx.geometry.Side side)
    Pins a node to a sidebar, removing it from the main layout if necessary.
    void
    pinToSideBar(DockNode node, javafx.geometry.Side side, int index)
    Pins a node to a sidebar and inserts it at the requested sidebar index.
    void
    restoreFromSideBar(DockNode node)
    Restores a pinned sidebar node back to the main layout using remembered placement or a root fallback.
    javafx.beans.property.LongProperty
    revisionProperty()
    Returns the observable structural revision counter.
    javafx.beans.property.ObjectProperty<DockElement>
    rootProperty()
    Returns the root property of the dock graph.
    void
    setLayoutIdCounter(long counter)
    Resets the layout ID counter to a specific value.
    void
    setLocked(boolean locked)
    Locks or unlocks the graph.
    void
    setRoot(DockElement newRoot)
    Sets the root of the dock graph.
    void
    setSideBarPanelWidth(javafx.geometry.Side side, double width)
    Sets the preferred sidebar panel width for the given side.
    void
    setSideBarPinnedOpen(javafx.geometry.Side side, boolean pinnedOpen)
    Sets whether a sidebar is pinned-open (layout-consuming) or collapsed to the icon strip.
    javafx.beans.property.DoubleProperty
    sideBarPanelWidthProperty(javafx.geometry.Side side)
    Returns the preferred sidebar panel width property for the given side.
    javafx.beans.property.BooleanProperty
    sideBarPinnedOpenProperty(javafx.geometry.Side side)
    Returns the pinned-open state property for a sidebar side.
    void
    undock(DockNode node)
    Removes a DockNode from the graph.
    boolean
    unpinFromSideBar(DockNode node)
    Removes a node from its sidebar without restoring it to the main layout.

    Methods inherited from class java.lang.Object

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

  • Property Details

    • revision

      public javafx.beans.property.LongProperty revisionProperty
      Returns the observable structural revision counter.
      See Also:

    • root

      public javafx.beans.property.ObjectProperty<DockElement> rootProperty
      Returns the root property of the dock graph.
      See Also:

    • locked

      public javafx.beans.property.BooleanProperty lockedProperty
      Returns the locked property. When locked, all mutating operations (dock, undock, move) are no-ops. This can be used to temporarily disable updates while performing batch modifications or during layout loading.
      See Also:

  • Field Details

    • DEFAULT_SIDE_BAR_PANEL_WIDTH

      public static final double DEFAULT_SIDE_BAR_PANEL_WIDTH
      Default preferred width (in pixels) for sidebar panels.
      See Also:

  • Constructor Details

    • DockGraph

      public DockGraph()
      Creates an empty dock graph with default sidebar state.

  • Method Details

    • revisionProperty

      public javafx.beans.property.LongProperty revisionProperty()
      Returns the observable structural revision counter.
      Returns:
      revision property incremented on structural updates
      See Also:

    • getRevision

      public long getRevision()
      Gets the value of the revision property.
      Property description:
      Returns the observable structural revision counter.
      Returns:
      the value of the revision property
      See Also:

    • getRoot

      public DockElement getRoot()
      Returns the root element of the dock graph, or null if the graph is empty.
      Returns:
      root element, or null

    • rootProperty

      public javafx.beans.property.ObjectProperty<DockElement> rootProperty()
      Returns the root property of the dock graph.
      Returns:
      root property
      See Also:

    • setRoot

      public void setRoot(DockElement newRoot)
      Sets the root of the dock graph. This will replace the entire layout tree. All nodes in the new tree will be assigned unique layout IDs if they don't have one already.
      Parameters:
      newRoot - The new root element, or null to clear the graph

    • setLayoutIdCounter

      public void setLayoutIdCounter(long counter)
      Resets the layout ID counter to a specific value. Used during deserialization to continue from the highest ID in the loaded layout.
      Parameters:
      counter - new layout ID counter value

    • getLayoutIdCounter

      public long getLayoutIdCounter()
      Returns the current layout ID counter value.
      Returns:
      current layout ID counter

    • isLocked

      public boolean isLocked()
      Returns true if the graph is currently locked. When locked, all mutating operations (dock, undock, move) are no-ops. This can be used to temporarily disable updates while performing batch modifications or during layout loading.
      Returns:
      true when structural mutations are locked

    • lockedProperty

      public javafx.beans.property.BooleanProperty lockedProperty()
      Returns the locked property. When locked, all mutating operations (dock, undock, move) are no-ops. This can be used to temporarily disable updates while performing batch modifications or during layout loading.
      Returns:
      locked-state property
      See Also:

    • setLocked

      public void setLocked(boolean locked)
      Locks or unlocks the graph. When locked, all mutating operations (dock, undock, move) are no-ops. This can be used to temporarily disable updates while performing batch modifications or during layout loading.
      Parameters:
      locked - true to lock structural mutations

    • getSideBarNodes

      public javafx.collections.ObservableList<DockNode> getSideBarNodes(javafx.geometry.Side side)
      Returns the read-only list of pinned nodes for a sidebar side.
      Parameters:
      side - sidebar side
      Returns:
      read-only pinned-node list for the side

    • isSideBarPinnedOpen

      public boolean isSideBarPinnedOpen(javafx.geometry.Side side)
      Returns whether the sidebar for the given side is pinned-open (layout-consuming).
      Parameters:
      side - sidebar side
      Returns:
      true when the sidebar is pinned-open

    • sideBarPinnedOpenProperty

      public javafx.beans.property.BooleanProperty sideBarPinnedOpenProperty(javafx.geometry.Side side)
      Returns the pinned-open state property for a sidebar side.
      Parameters:
      side - sidebar side
      Returns:
      pinned-open state property for the side

    • setSideBarPinnedOpen

      public void setSideBarPinnedOpen(javafx.geometry.Side side, boolean pinnedOpen)
      Sets whether a sidebar is pinned-open (layout-consuming) or collapsed to the icon strip.
      Parameters:
      side - sidebar side
      pinnedOpen - pinned-open state

    • pinOpenSideBar

      public void pinOpenSideBar(javafx.geometry.Side side)
      Convenience method to pin-open a sidebar.
      Parameters:
      side - sidebar side

    • collapsePinnedSideBar

      public void collapsePinnedSideBar(javafx.geometry.Side side)
      Convenience method to collapse a pinned sidebar back to strip mode.
      Parameters:
      side - sidebar side

    • getSideBarPanelWidth

      public double getSideBarPanelWidth(javafx.geometry.Side side)
      Returns the preferred sidebar panel width for the given side.

      This is a persisted preference value. View hosts (for example SnapFX) may apply additional runtime clamping depending on scene size and resize policies.

      Parameters:
      side - sidebar side
      Returns:
      preferred panel width in pixels

    • sideBarPanelWidthProperty

      public javafx.beans.property.DoubleProperty sideBarPanelWidthProperty(javafx.geometry.Side side)
      Returns the preferred sidebar panel width property for the given side.

      The property stores the persisted preferred width. Consumers should clamp it at render time as needed.

      Parameters:
      side - sidebar side
      Returns:
      preferred panel-width property for the side

    • setSideBarPanelWidth

      public void setSideBarPanelWidth(javafx.geometry.Side side, double width)
      Sets the preferred sidebar panel width for the given side.

      This updates a persisted view preference and is intentionally allowed while the graph is locked because it does not mutate the docking structure.

      Parameters:
      side - sidebar side
      width - preferred panel width in pixels

    • pinToSideBar

      public void pinToSideBar(DockNode node, javafx.geometry.Side side)
      Pins a node to a sidebar, removing it from the main layout if necessary. The last main-layout placement is captured for deterministic restore behavior.

      Pinning preserves the sidebar's current pinned-open/collapsed state. Newly pinned nodes therefore stay collapsed by default unless callers explicitly open the sidebar via pinOpenSideBar(Side).

      Parameters:
      node - node to pin
      side - target sidebar side

    • pinToSideBar

      public void pinToSideBar(DockNode node, javafx.geometry.Side side, int index)
      Pins a node to a sidebar and inserts it at the requested sidebar index.

      If the node is already pinned on the same side, this reorders the sidebar entry. The index is clamped into the valid insertion range [0..size].

      Parameters:
      node - node to pin
      side - target sidebar side
      index - desired insertion index

    • restoreFromSideBar

      public void restoreFromSideBar(DockNode node)
      Restores a pinned sidebar node back to the main layout using remembered placement or a root fallback.
      Parameters:
      node - pinned sidebar node to restore

    • isPinnedToSideBar

      public boolean isPinnedToSideBar(DockNode node)
      Returns whether a node is currently pinned in any sidebar.
      Parameters:
      node - node to check
      Returns:
      true when the node is pinned

    • getPinnedSide

      public javafx.geometry.Side getPinnedSide(DockNode node)
      Returns the sidebar side the node is pinned to, or null if it is not pinned.
      Parameters:
      node - node to check
      Returns:
      pinned side, or null

    • unpinFromSideBar

      public boolean unpinFromSideBar(DockNode node)
      Removes a node from its sidebar without restoring it to the main layout.

      This is primarily used by higher-level hosts (for example SnapFX) that apply a custom restore strategy after removing the node from the sidebar.

      Parameters:
      node - node to unpin
      Returns:
      true if the node was removed from a sidebar; otherwise false

    • clearSideBars

      public void clearSideBars()
      Removes all pinned sidebar nodes and resets pinned-open sidebar state. Nodes are not restored to the main layout.

    • dock

      public void dock(DockNode node, DockElement target, DockPosition position)
      Docks a node at a specific position relative to a target element.
      Parameters:
      node - The node to dock
      target - The target element to dock relative to (can be null if docking the first node)
      position - The position relative to the target to dock at

    • dock

      public void dock(DockNode node, DockElement target, DockPosition position, Integer tabIndex)
      Docks a node at a specific position relative to a target element with optional tab index. The tab index is only applicable when docking as a tab (position = CENTER) and will be ignored otherwise. If position is CENTER and the target is not already a TabPane, a new TabPane will be created to hold both the target and the new node. If position is CENTER and the target is already a TabPane, the new node will be added to that TabPane at the specified index (or right after the target if index is null). If position is not CENTER, the node will be docked to the edge of the target as specified.
      Parameters:
      node - The node to dock
      target - The target element to dock relative to (can be null if docking the first node)
      position - The position relative to the target to dock at
      tabIndex - Optional index to insert the new tab at (only applies if position is CENTER and target is a TabPane or already in a TabPane). If null, the new tab will be added right after the target tab (or at the end if target is not a tab itself).

    • undock

      public void undock(DockNode node)
      Removes a DockNode from the graph.
      Parameters:
      node - node to remove

    • move

      public void move(DockNode node, DockElement target, DockPosition position)
      Moves a DockNode from one position to another.
      Parameters:
      node - node to move
      target - target element
      position - target dock position

    • move

      public void move(DockNode node, DockElement target, DockPosition position, Integer tabIndex)
      Moves a DockNode from one position to another with optional tab index.
      Parameters:
      node - node to move
      target - target element
      position - target dock position
      tabIndex - target tab insertion index, or null

    • findElementByLayoutId

      public DockElement findElementByLayoutId(String layoutId)
      Finds a dock element by layout ID across the main layout and pinned sidebars.
      Parameters:
      layoutId - layout ID to search
      Returns:
      matching element, or null

    • getDockNodeCount

      public int getDockNodeCount(String dockNodeId)
      Counts dock nodes by logical dock-node ID across main layout and sidebars.
      Parameters:
      dockNodeId - logical dock-node ID to count
      Returns:
      total count across all containers