Module org.snapfx
Package org.snapfx

Class SnapFX

java.lang.Object
org.snapfx.SnapFX
public class SnapFX extends Object
Main API class for the SnapFX docking framework.

SnapFX coordinates the logical model (DockGraph), rendering layer, drag-and-drop integration, floating windows, sidebars, and layout persistence.

Typical usage:


 SnapFX snapFX = new SnapFX();
 snapFX.dock(new TextArea("Editor"), "Editor");
 snapFX.dock(new TextArea("Console"), "Console");

 Scene scene = new Scene(snapFX.buildLayout(), 1200, 800);
 stage.setScene(scene);
 snapFX.initialize(stage);
 stage.show();

  • Constructor Details

    • SnapFX

      public SnapFX()
      Creates a new SnapFX instance with default services, callbacks, and shortcut/theme configuration.

  • Method Details

    • initialize

      public void initialize(javafx.stage.Stage stage)
      Initializes SnapFX with the primary stage. Also applies the currently configured framework stylesheet to the primary and floating scenes.
      Parameters:
      stage - primary application stage

    • getDefaultThemeName

      public static String getDefaultThemeName()
      Returns the built-in default theme name.
      Returns:
      default theme name

    • getDefaultThemeStylesheetResourcePath

      public static String getDefaultThemeStylesheetResourcePath()
      Returns the default classpath stylesheet used by SnapFX.
      Returns:
      default stylesheet resource path

    • getAvailableThemeStylesheets

      public static Map<String,String> getAvailableThemeStylesheets()
      Returns all built-in themes as an ordered map of themeName -> stylesheetResourcePath.
      Returns:
      ordered theme name to stylesheet path map

    • getAvailableThemeNames

      public static List<String> getAvailableThemeNames()
      Returns all built-in theme names in deterministic order.
      Returns:
      ordered theme names

    • getThemeStylesheetResourcePath

      public String getThemeStylesheetResourcePath()
      Returns the currently configured stylesheet resource path or absolute URL.

      Classpath resources use paths like /snapfx.css; external stylesheets keep their original URL.

      Returns:
      configured stylesheet resource path or absolute URL

    • setThemeStylesheet

      public void setThemeStylesheet(String stylesheetResourcePath)
      Sets the stylesheet used by SnapFX and applies it immediately to the primary and floating window scenes.

      Passing null or blank restores the default stylesheet (/snapfx.css).

      Parameters:
      stylesheetResourcePath - classpath resource path (for example /snapfx-dark.css) or an absolute stylesheet URL
      Throws:
      IllegalArgumentException - when the classpath resource cannot be resolved

    • dock

      public DockNode dock(javafx.scene.Node content, String title)
      Simple API to dock a node with a title. Creates a DockNode and adds it to the root.
      Parameters:
      content - JavaFX node content
      title - dock-node title
      Returns:
      created and docked node

    • dock

      public DockNode dock(javafx.scene.Node content, String title, DockElement target, DockPosition position)
      Docks a node at a specific position relative to a target.
      Parameters:
      content - JavaFX node content
      title - dock-node title
      target - docking target element
      position - docking position relative to target
      Returns:
      created and docked node

    • dock

      public void dock(DockNode node, DockElement target, DockPosition position)
      Docks an existing DockNode at a specific position.
      Parameters:
      node - node to dock
      target - docking target element
      position - docking position relative to target

    • undock

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

    • buildLayout

      public javafx.scene.Parent buildLayout()
      Builds the visual representation of the current dock layout. The returned Parent will automatically update when the model changes.
      Returns:
      root layout container node

    • resetShortcutsToDefaults

      public void resetShortcutsToDefaults()
      Restores the default framework shortcut mapping.

      Default bindings:

    • setShortcut

      public void setShortcut(DockShortcutAction action, javafx.scene.input.KeyCombination keyCombination)
      Assigns or removes a key binding for a built-in shortcut action.
      Parameters:
      action - Shortcut action to configure
      keyCombination - Key combination to assign, or null to remove the binding

    • clearShortcut

      public void clearShortcut(DockShortcutAction action)
      Removes the key binding for a shortcut action.
      Parameters:
      action - shortcut action to clear

    • getShortcut

      public javafx.scene.input.KeyCombination getShortcut(DockShortcutAction action)
      Returns the configured key binding for a shortcut action.
      Parameters:
      action - shortcut action to query
      Returns:
      configured key combination, or null

    • getShortcuts

      public Map<DockShortcutAction,javafx.scene.input.KeyCombination> getShortcuts()
      Returns a snapshot of all currently configured shortcut bindings.
      Returns:
      immutable snapshot of shortcut bindings

    • setLocked

      public void setLocked(boolean locked)
      Locks or unlocks the layout (disables drag & drop when locked).
      Parameters:
      locked - true to lock layout interactions

    • isLocked

      public boolean isLocked()
      Returns whether layout mutations are currently locked.
      Returns:
      true when layout is locked

    • setNodeFactory

      public void setNodeFactory(DockNodeFactory factory)
      Sets the factory used to create DockNodes when loading layouts. This is required for proper persistence across application sessions.

      Example usage:

      
 snapFX.setNodeFactory(nodeId -> switch(nodeId) {
     case "projectExplorer" -> createProjectExplorer();
     case "mainEditor" -> createMainEditor();
     default -> null;
 });
      Parameters:
      factory - Factory that creates nodes from their IDs

    • saveLayout

      public String saveLayout()
      Saves the current layout as JSON.
      Returns:
      serialized layout snapshot JSON

    • loadLayout

      public void loadLayout(String json) throws DockLayoutLoadException
      Loads a layout from JSON.
      Parameters:
      json - serialized layout snapshot JSON
      Throws:
      DockLayoutLoadException - if layout JSON is invalid or cannot be deserialized

    • hide

      public void hide(DockNode node)
      Hides a DockNode (removes from layout but keeps in memory for restore).
      Parameters:
      node - node to hide

    • remove

      public void remove(DockNode node)
      Removes a DockNode from layout/floating windows without adding it to the hidden list.
      Parameters:
      node - node to remove

    • close

      public void close(DockNode node)
      Programmatically requests a close action for a DockNode. The request is processed using the configured close behavior and callbacks.
      Parameters:
      node - node to close

    • restore

      public void restore(DockNode node)
      Restores a hidden DockNode back to the layout.
      Parameters:
      node - node to restore

    • pinToSideBar

      public void pinToSideBar(DockNode node, javafx.geometry.Side side)
      Pins a dock node into a sidebar on the given side.

      If the node is currently hidden, it is removed from the hidden list first. If it is inside a floating window, it is detached from that floating host before pinning.

      Pinning keeps the target sidebar in its current pinned-open/collapsed state. New pinned entries are therefore collapsed by default unless the sidebar is explicitly opened with pinOpenSideBar(Side).

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

    • restoreFromSideBar

      public void restoreFromSideBar(DockNode node)
      Restores a pinned sidebar node back to the main layout.

      Restore reuses the same remembered placement strategy used for floating-window attach operations: preferred anchor, neighbor anchors, then fallback docking.

      Parameters:
      node - node to restore from sidebar

    • pinOpenSideBar

      public void pinOpenSideBar(javafx.geometry.Side side)
      Opens the sidebar panel for the given side in pinned (layout-consuming) mode.
      Parameters:
      side - sidebar side

    • collapsePinnedSideBar

      public void collapsePinnedSideBar(javafx.geometry.Side side)
      Collapses the sidebar panel for the given side back to icon-strip mode.
      Parameters:
      side - sidebar side

    • isSideBarPinnedOpen

      public boolean isSideBarPinnedOpen(javafx.geometry.Side side)
      Returns whether the sidebar panel for the given side is currently pinned-open (layout-consuming).

      When isCollapsePinnedSideBarOnActiveIconClick() is enabled, a pinned side panel can be temporarily collapsed via active-icon click while this method still returns true (pin mode preserved). The temporary collapsed/expanded state is managed as transient view state in SnapFX.

      Parameters:
      side - sidebar side
      Returns:
      true when sidebar is pinned-open

    • isCollapsePinnedSideBarOnActiveIconClick

      public boolean isCollapsePinnedSideBarOnActiveIconClick()
      Returns whether clicking the active side-bar icon collapses a pinned-open side panel.

      When enabled (default), clicking the icon of the currently open pinned panel collapses the panel back to icon-strip mode. When disabled, the click keeps the pinned panel open.

      Returns:
      true when active-icon click collapses pinned sidebars

    • setCollapsePinnedSideBarOnActiveIconClick

      public void setCollapsePinnedSideBarOnActiveIconClick(boolean collapsePinnedSideBarOnActiveIconClick)
      Controls whether clicking the active side-bar icon collapses a pinned-open side panel.

      Default is true.

      Parameters:
      collapsePinnedSideBarOnActiveIconClick - collapse policy flag

    • setSideBarMode

      public void setSideBarMode(DockSideBarMode mode)
      Controls framework sidebar rendering and sidebar move action availability.

      DockSideBarMode.AUTO is the default and renders sidebars only when they contain pinned nodes. DockSideBarMode.ALWAYS keeps empty left/right strips visible, while DockSideBarMode.NEVER disables framework sidebar UI and built-in sidebar move context-menu actions.

      Parameters:
      mode - sidebar mode, defaults to DockSideBarMode.AUTO when null

    • getSideBarMode

      public DockSideBarMode getSideBarMode()
      Returns the current framework sidebar rendering mode.
      Returns:
      current sidebar rendering mode

    • getSideBarPanelWidth

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

      The returned value is the persisted preference. Rendering may clamp the effective width depending on the current layout size.

      Parameters:
      side - sidebar side
      Returns:
      preferred panel width

    • setSideBarPanelWidth

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

      The value is validated and clamped to the current SnapFX sidebar width policy. The effective rendered width may still be smaller on narrow scenes due to runtime clamping.

      Parameters:
      side - sidebar side
      width - preferred panel width

    • getSideBarNodes

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

    • isPinnedToSideBar

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

    • getPinnedSide

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

    • floatNode

      public DockFloatingWindow floatNode(DockNode node)
      Moves an existing DockNode into an external floating window.
      Parameters:
      node - node to float
      Returns:
      created or reused floating window, or null when node is null

    • floatNode

      public DockFloatingWindow floatNode(DockNode node, Double screenX, Double screenY)
      Moves an existing DockNode into an external floating window at a screen position. The screen coordinates can be on any monitor.

      Before detaching a node from its current host (main layout or another floating window), SnapFX captures placement anchors so attachFloatingWindow(DockFloatingWindow) can restore the node as close as possible to its previous location later.

      Parameters:
      node - node to float
      screenX - optional preferred floating x-position
      screenY - optional preferred floating y-position
      Returns:
      created or reused floating window, or null when node is null

    • attachFloatingWindow

      public void attachFloatingWindow(DockFloatingWindow floatingWindow)
      Attaches a floating window back into the main layout.

      Attach uses a best-effort placement restore strategy per node:

      • Try remembered exact target/position/tab-index in the original host.
      • Try remembered previous/next-neighbor anchors from the original host.
      • If anchors are missing but the original floating host is still active, dock into that host.
      • If the original floating host no longer exists, skip it and continue with main-layout fallback.
      • If nothing is restorable, dock into the main layout without interruption.

      No dialogs are shown for restore failures; attach is always resolved via fallback.

      Parameters:
      floatingWindow - floating window to attach back

    • getFloatingWindows

      public javafx.collections.ObservableList<DockFloatingWindow> getFloatingWindows()
      Returns all currently open floating windows. (read-only)
      Returns:
      read-only list of floating windows

    • closeFloatingWindows

      public void closeFloatingWindows(boolean attachBack)
      Closes all currently open floating windows.
      Parameters:
      attachBack - whether floating nodes should be attached back to the main layout

    • getHiddenNodes

      public javafx.collections.ObservableList<DockNode> getHiddenNodes()
      Returns the observable list of currently hidden nodes.
      Returns:
      hidden-node list

    • getDockGraph

      public DockGraph getDockGraph()
      Returns the underlying dock graph model.
      Returns:
      dock graph

    • getLayoutEngine

      public DockLayoutEngine getLayoutEngine()
      Returns the layout engine used by this SnapFX instance.
      Returns:
      layout engine

    • getDragService

      public DockDragService getDragService()
      Returns the drag service used by this SnapFX instance.
      Returns:
      drag service

    • setDropVisualizationMode

      public void setDropVisualizationMode(DockDropVisualizationMode mode)
      Sets the drop-zone visualization mode during drag operations.
      Parameters:
      mode - visualization mode

    • getDropVisualizationMode

      public DockDropVisualizationMode getDropVisualizationMode()
      Returns the current drop-zone visualization mode.
      Returns:
      current drop visualization mode

    • setCloseButtonMode

      public void setCloseButtonMode(DockCloseButtonMode mode)
      Sets the close-button mode used by layout views.
      Parameters:
      mode - close-button mode

    • getCloseButtonMode

      public DockCloseButtonMode getCloseButtonMode()
      Returns the close-button mode used by layout views.
      Returns:
      close-button mode

    • setTitleBarMode

      public void setTitleBarMode(DockTitleBarMode mode)
      Sets the title-bar mode used by layout views.
      Parameters:
      mode - title-bar mode

    • getTitleBarMode

      public DockTitleBarMode getTitleBarMode()
      Returns the title-bar mode used by layout views.
      Returns:
      title-bar mode

    • getPrimaryStage

      public javafx.stage.Stage getPrimaryStage()
      Returns the primary stage last passed to initialize(Stage).
      Returns:
      primary stage, or null

    • setDefaultCloseBehavior

      public void setDefaultCloseBehavior(DockCloseBehavior defaultCloseBehavior)
      Sets the default close behavior for close requests.
      Parameters:
      defaultCloseBehavior - default close behavior

    • getDefaultCloseBehavior

      public DockCloseBehavior getDefaultCloseBehavior()
      Returns the configured default close behavior.
      Returns:
      default close behavior

    • setOnCloseRequest

      public void setOnCloseRequest(Function<DockCloseRequest,DockCloseDecision> handler)
      Sets the close-request decision callback.
      Parameters:
      handler - callback that decides close handling, or null

    • setOnCloseHandled

      public void setOnCloseHandled(Consumer<DockCloseResult> handler)
      Sets the callback invoked after close handling is resolved.
      Parameters:
      handler - close-handled callback, or null

    • setFloatingPinButtonMode

      public void setFloatingPinButtonMode(DockFloatingPinButtonMode mode)
      Controls pin-button visibility behavior for all floating windows.
      Parameters:
      mode - global pin-button mode, defaults to DockFloatingPinButtonMode.AUTO when null

    • getFloatingPinButtonMode

      public DockFloatingPinButtonMode getFloatingPinButtonMode()
      Returns the current global pin-button mode.
      Returns:
      current global pin-button mode

    • setDefaultFloatingAlwaysOnTop

      public void setDefaultFloatingAlwaysOnTop(boolean defaultAlwaysOnTop)
      Sets the default always-on-top state for newly created floating windows.
      Parameters:
      defaultAlwaysOnTop - default always-on-top state for newly created floating windows

    • isDefaultFloatingAlwaysOnTop

      public boolean isDefaultFloatingAlwaysOnTop()
      Returns the default always-on-top state for newly created floating windows.
      Returns:
      default always-on-top state for new floating windows

    • setAllowFloatingPinToggle

      public void setAllowFloatingPinToggle(boolean allowPinToggle)
      Enables or disables user pin toggling in floating title bars.
      Parameters:
      allowPinToggle - true to allow user pin toggling

    • isAllowFloatingPinToggle

      public boolean isAllowFloatingPinToggle()
      Returns whether user pin toggling is enabled in floating title bars.
      Returns:
      true when user pin toggling is enabled

    • setFloatingPinLockedBehavior

      public void setFloatingPinLockedBehavior(DockFloatingPinLockedBehavior behavior)
      Sets lock-mode behavior for pin controls in floating windows.
      Parameters:
      behavior - pin behavior while layout is locked

    • getFloatingPinLockedBehavior

      public DockFloatingPinLockedBehavior getFloatingPinLockedBehavior()
      Returns lock-mode behavior for floating pin controls.
      Returns:
      lock-mode behavior for floating pin controls

    • setFloatingWindowSnappingEnabled

      public void setFloatingWindowSnappingEnabled(boolean enabled)
      Enables or disables floating-window snapping while title bars are dragged.
      Parameters:
      enabled - true to enable snapping

    • isFloatingWindowSnappingEnabled

      public boolean isFloatingWindowSnappingEnabled()
      Returns whether floating-window snapping is enabled.
      Returns:
      true when floating-window snapping is enabled

    • setFloatingWindowSnapDistance

      public void setFloatingWindowSnapDistance(double pixels)
      Sets the snap distance in pixels used for floating-window drag snapping.
      Parameters:
      pixels - snap tolerance in pixels

    • getFloatingWindowSnapDistance

      public double getFloatingWindowSnapDistance()
      Returns the configured floating-window snap distance in pixels.
      Returns:
      floating-window snap distance in pixels

    • setFloatingWindowSnapTargets

      public void setFloatingWindowSnapTargets(Set<DockFloatingSnapTarget> targets)
      Configures which targets are used for floating-window snapping.
      Parameters:
      targets - snapping targets, null clears all targets

    • getFloatingWindowSnapTargets

      public Set<DockFloatingSnapTarget> getFloatingWindowSnapTargets()
      Returns the configured floating-window snap targets.
      Returns:
      immutable snapshot of configured snapping targets

    • setOnFloatingPinChanged

      public void setOnFloatingPinChanged(Consumer<DockFloatingPinChangeEvent> handler)
      Sets callback for floating pin-state changes.
      Parameters:
      handler - callback for floating pin-state changes, or null

    • setFloatingWindowAlwaysOnTop

      public void setFloatingWindowAlwaysOnTop(DockFloatingWindow floatingWindow, boolean alwaysOnTop)
      Sets always-on-top for an open floating window.
      Parameters:
      floatingWindow - floating window to update
      alwaysOnTop - target always-on-top state

    • getDockNodeCount

      public int getDockNodeCount(String id)
      Returns the number of dock nodes with the given logical dock-node ID.
      Parameters:
      id - logical dock-node ID
      Returns:
      number of matching nodes across layout and sidebars

    • setRootSplitRatios

      public boolean setRootSplitRatios(double... paneRatios)
      Sets the pane ratios of the root split pane.

      Ratios are normalized automatically, so both (0.25, 0.5, 0.25) and (25, 50, 25) are valid inputs.

      Parameters:
      paneRatios - Ratios for each pane of the root split pane
      Returns:
      true if ratios were applied; false if the root is not a split pane or if input validation failed

    • setSplitRatios

      public boolean setSplitRatios(DockSplitPane splitPane, double... paneRatios)
      Sets the pane ratios of a specific split pane.

      The number of ratios must match the number of split children.

      Parameters:
      splitPane - Split pane to configure
      paneRatios - Ratios for each pane in the split pane
      Returns:
      true if ratios were applied; false if validation failed