Add scrollToIfNeeded method

Author: pcastornii

toolkit-fx/src/main/java/com/techsenger/toolkit/fx/utils/ListViewUtils.java

@@ -26,7 +26,7 @@
 public final class ListViewUtils {
 
     /**
-     * Scrolls the list view only when the given index is outside the visible range, mimicking natural keyboard
+     * Scrolls the list view only when the given index is outside the fully visible range, mimicking natural keyboard
      * navigation behavior.
      *
      * @param listView the list view to scroll
@@ -37,15 +37,7 @@ public static void scrollToIfNeeded(ListView<?> listView, int index) {
         if (flow == null) {
             return;
         }
-
-        int first = flow.getFirstVisibleCell().getIndex();
-        int last = flow.getLastVisibleCell().getIndex();
-
-        if (index < first) {
-            listView.scrollTo(index);
-        } else if (index > last) {
-            listView.scrollTo(index - (last - first));
-        }
+        NodeUtils.scrollToIfNeeded(flow, listView::scrollTo, index);
     }
 
     private ListViewUtils() {

toolkit-fx/src/main/java/com/techsenger/toolkit/fx/utils/NodeUtils.java

@@ -18,10 +18,12 @@
 
 import java.util.ArrayList;
 import java.util.Objects;
+import java.util.function.IntConsumer;
 import javafx.animation.KeyFrame;
 import javafx.animation.Timeline;
 import javafx.scene.Node;
 import javafx.scene.Parent;
+import javafx.scene.control.skin.VirtualFlow;
 import javafx.util.Duration;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -96,6 +98,39 @@ public static ArrayList<Node> getAllNodes(final Parent parent) {
         return nodes;
     }
 
+    /**
+     * Scrolls the control only when the given index is outside the fully visible range,
+     * mimicking natural keyboard navigation behavior. A partially visible cell at the
+     * bottom is not considered visible.
+     *
+     * @param flow   the virtual flow of the control
+     * @param scroll the scroll action to perform
+     * @param index  the index that should be visible
+     */
+    static void scrollToIfNeeded(VirtualFlow<?> flow, IntConsumer scroll, int index) {
+        var firstCell = flow.getFirstVisibleCell();
+        var lastCell = flow.getLastVisibleCell();
+        if (firstCell == null || lastCell == null) {
+            return;
+        }
+        int first = firstCell.getIndex();
+        int last = lastCell.getBoundsInParent().getMaxY() > flow.getHeight()
+                ? lastCell.getIndex() - 1
+                : lastCell.getIndex();
+        int visibleCount = last - first;
+        if (index <= first) {
+            scroll.accept(index);
+        } else if (index > last) {
+            if (index - last > 1) {
+                // Jump - scroll so that index is the last visible item
+                scroll.accept(index - visibleCount);
+            } else {
+                // Single step down - shift by one
+                scroll.accept(first + 1);
+            }
+        }
+    }
+
     private static void doRequestFocus(Node node, Runnable onSuccess, int maxAttempts) {
         Timeline[] holder = new Timeline[1];
         holder[0] = new Timeline(

toolkit-fx/src/main/java/com/techsenger/toolkit/fx/utils/TableUtils.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2016-2025 Pavel Castornii.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.techsenger.toolkit.fx.utils;
+
+import javafx.scene.control.TableView;
+import javafx.scene.control.TreeTableView;
+import javafx.scene.control.skin.VirtualFlow;
+
+/**
+ *
+ * @author Pavel Castornii
+ */
+public final class TableUtils {
+
+    /**
+     * Scrolls the table view only when the given index is outside the visible range, mimicking natural keyboard
+     * navigation behavior.
+     *
+     * @param tableView the table view to scroll
+     * @param index     the index that should be visible
+     */
+    public static void scrollToIfNeeded(TableView<?> tableView, int index) {
+        VirtualFlow<?> flow = (VirtualFlow<?>) tableView.lookup(".virtual-flow");
+        if (flow == null) {
+            return;
+        }
+        NodeUtils.scrollToIfNeeded(flow, tableView::scrollTo, index);
+    }
+
+    /**
+     * Scrolls the tree table view only when the given index is outside the visible range, mimicking natural keyboard
+     * navigation behavior.
+     *
+     * @param treeTableView the tree table view to scroll
+     * @param index         the index that should be visible
+     */
+    public static void scrollToIfNeeded(TreeTableView<?> treeTableView, int index) {
+        VirtualFlow<?> flow = (VirtualFlow<?>) treeTableView.lookup(".virtual-flow");
+        if (flow == null) {
+            return;
+        }
+        NodeUtils.scrollToIfNeeded(flow, treeTableView::scrollTo, index);
+    }
+
+    private TableUtils() {
+        // empty
+    }
+}

toolkit-fx/src/main/java/com/techsenger/toolkit/fx/utils/TreeViewUtils.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2016-2025 Pavel Castornii.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.techsenger.toolkit.fx.utils;
+
+import javafx.scene.control.TreeView;
+import javafx.scene.control.skin.VirtualFlow;
+
+/**
+ *
+ * @author Pavel Castornii
+ */
+public final class TreeViewUtils {
+
+    /**
+     * Scrolls the tree view only when the given index is outside the fully visible range, mimicking natural keyboard
+     * navigation behavior. Partially visible cells are not considered visible.
+     *
+     * @param treeView the tree view to scroll
+     * @param index    the index that should be visible
+     */
+    public static void scrollToIfNeeded(TreeView<?> treeView, int index) {
+        VirtualFlow<?> flow = (VirtualFlow<?>) treeView.lookup(".virtual-flow");
+        if (flow == null) {
+            return;
+        }
+        NodeUtils.scrollToIfNeeded(flow, treeView::scrollTo, index);
+    }
+
+    private TreeViewUtils() {
+        // empty
+    }
+}