move AutoLock to utility; code cleanup; Javadoc

meja-fx/src/main/java/com/dua3/meja/ui/fx/FxRow.java

@@ -32,9 +32,18 @@
 public class FxRow extends IndexedCell<FxRow.Index> {
     private static final Logger LOG = LogManager.getLogger(FxRow.class);
 
+    /**
+     * The {@code Index} class is a record representing the position of a row within a table
+     * or sheet-like structure. It encapsulates two distinct pieces of information:
+     *
+     * <ul>
+     *     <li><b>rowIndex:</b> The internal index of the row, used to access the row from the filtered list of rows.</li>
+     *     <li><b>rowNumber:</b> The row number as defined in the sheet.</li>
+     * </ul>
+     */
     public record Index(int rowIndex, int rowNumber) {}
 
-    public static final Affine IDENTITY_TRANSFORMATION = FxUtil.convert(AffineTransformation2f.IDENTITY);
+    private static final Affine IDENTITY_TRANSFORMATION = FxUtil.convert(AffineTransformation2f.IDENTITY);
 
     private final ObservableList<Row> rows;
 
@@ -198,7 +207,7 @@ public void dispose() {
 
     private void render() {
         PlatformHelper.checkApplicationThread();
-        try (var __ = sheetViewDelegate.readLock()) {
+        try (var __ = sheetViewDelegate.automaticReadLock()) {
             switch (getItem().rowIndex()) {
                 case ROW_INDEX_UNUSED -> renderEmpty();
                 case ROW_INDEX_COLUMN_LABELS -> renderColumnLabels();

meja-fx/src/main/java/com/dua3/meja/ui/fx/FxSegmentView.java

@@ -141,7 +141,7 @@ public FxSegmentView(FxSheetViewDelegate svDelegate, SheetView.Quadrant quadrant
 
         this.rows.addListener((ListChangeListener<? super Row>) change -> {
             PlatformHelper.runLater(() -> {
-                try (var __ = svDelegate.readLock()) {
+                try (var __ = svDelegate.automaticReadLock()) {
                     flow.setCellCount(rows.size());
                     flow.refresh();
                 }

meja-fx/src/main/java/com/dua3/meja/ui/fx/FxSheetView.java

@@ -240,7 +240,7 @@ public void scrollToCurrentCell() {
         LOG.trace("scrollToCurrentCell()");
 
         Platform.runLater(() -> delegate.getCurrentLogicalCell().ifPresent(cell -> {
-            try (var __ = delegate.readLock()) {
+            try (var __ = delegate.automaticReadLock()) {
                 Sheet sheet = delegate.getSheet();
                 int i = cell.getRowNumber();
                 int j = cell.getColumnNumber();
@@ -288,7 +288,7 @@ public void repaintCell(Cell cell) {
         LOG.trace("repaintCell({})", cell);
 
         PlatformHelper.runLater(() -> {
-            try (var __ = delegate.readLock()) {
+            try (var __ = delegate.automaticReadLock()) {
                 Cell lc = cell.getLogicalCell();
                 int startRow = lc.getRowNumber();
                 int endRow = startRow + lc.getVerticalSpan();
@@ -302,37 +302,56 @@ public void repaintCell(Cell cell) {
         });
     }
 
-    public void updateLayout() {
-        PlatformHelper.runAndWait(() -> {
-            try (var __ = delegate.writeLock()) {
-                updateDelegate(getSheet());
-                topLeftQuadrant.updateLayout();
-                topRightQuadrant.updateLayout();
-                bottomLeftQuadrant.updateLayout();
-                bottomRightQuadrant.updateLayout();
-            }
-        });
+    /**
+     * Updates the layout of the FxSheetView instance and its associated components.
+     *
+     * This method performs the following operations:
+     * <ul>
+     *   <li>Logs the start of the layout update process for debugging purposes.</li>
+     *   <li>Ensures that the logic executes on the UI application thread by invoking
+     *       {@code PlatformHelper.checkApplicationThread()}.</li>
+     *   <li>Acquires a write lock for thread-safe operations using the delegate's
+     *       {@code automaticWriteLock()} method.</li>
+     *   <li>Calls {@code updateDelegate()} to update the internal state of the
+     *       delegate with the current sheet's properties.</li>
+     *   <li>Updates the layout of all four quadrants of the view: top-left, top-right,
+     *       bottom-left, and bottom-right, by invoking their {@code updateLayout} methods.</li>
+     * </ul>
+     *
+     * This operation is vital for reflecting changes in layout, scaling, or other graphical
+     * attributes in the view, particularly after modifications to the underlying {@code Sheet}
+     * or its configurations.
+     */
+    private void updateLayout() {
+        LOG.debug("updateLayout()");
+        PlatformHelper.checkApplicationThread();
+        try (var __ = delegate.automaticWriteLock()) {
+            updateDelegate(getSheet());
+            topLeftQuadrant.updateLayout();
+            topRightQuadrant.updateLayout();
+            bottomLeftQuadrant.updateLayout();
+            bottomRightQuadrant.updateLayout();
+        }
     }
 
     @Override
     public void updateContent() {
         LOG.debug("updateContent()");
+        PlatformHelper.checkApplicationThread();
 
-        PlatformHelper.runAndWait(() -> {
-            try (var __ = delegate.readLock()) {
-                updateDelegate(getSheet());
+        try (var __ = delegate.automaticReadLock()) {
+            updateDelegate(getSheet());
 
-                topLeftQuadrant.updateLayout();
-                topRightQuadrant.updateLayout();
-                bottomLeftQuadrant.updateLayout();
-                bottomRightQuadrant.updateLayout();
+            topLeftQuadrant.updateLayout();
+            topRightQuadrant.updateLayout();
+            bottomLeftQuadrant.updateLayout();
+            bottomRightQuadrant.updateLayout();
 
-                topLeftQuadrant.refresh();
-                topRightQuadrant.refresh();
-                bottomLeftQuadrant.refresh();
-                bottomRightQuadrant.refresh();
-            }
-        });
+            topLeftQuadrant.refresh();
+            topRightQuadrant.refresh();
+            bottomLeftQuadrant.refresh();
+            bottomRightQuadrant.refresh();
+        }
     }
 
     private void updateDelegate(Sheet sheet) {

meja-fx/src/main/java/com/dua3/meja/ui/fx/FxSheetViewDelegate.java

@@ -1,6 +1,7 @@
 package com.dua3.meja.ui.fx;
 
 import com.dua3.meja.model.Sheet;
+import com.dua3.meja.model.SheetEvent;
 import com.dua3.meja.ui.SheetViewDelegate;
 import com.dua3.utility.fx.PlatformHelper;
 
@@ -32,4 +33,9 @@ public void updateLayout() {
         PlatformHelper.checkApplicationThread();
         super.updateLayout();
     }
+
+    @Override
+    public void onNext(SheetEvent item) {
+        PlatformHelper.runLater(() -> super.onNext(item));
+    }
 }

meja-fx/src/main/java/com/dua3/meja/ui/fx/ObservableSheet.java

@@ -51,6 +51,13 @@ public int size() {
         return sheet.getRowCount();
     }
 
+    /**
+     * Provides access to the zoom property of the observable sheet.
+     * The zoom property is a {@link FloatProperty} that allows
+     * for observing and modifying the zoom level of the underlying sheet.
+     *
+     * @return the zoom property of the observable sheet
+     */
     public FloatProperty zoomProperty() {
         return zoomProperty;
     }

meja-swing/src/main/java/com/dua3/meja/ui/swing/SwingSegmentView.java

@@ -163,7 +163,7 @@ public void mousePressed(MouseEvent e) {
     protected void paintComponent(Graphics g) {
         LOG.debug("paintComponent(): ({},{}) - ({},{})", ssvDelegate.getStartRow(), ssvDelegate.getStartColumn(), ssvDelegate.getEndRow(), ssvDelegate.getEndColumn());
 
-        try (var __ = svDelegate.readLock()) {
+        try (var __ = svDelegate.automaticReadLock()) {
             // clear background by calling super method
             super.paintComponent(g);
 
@@ -210,7 +210,7 @@ public void scrollIntoView(Cell cell) {
             return;
         }
 
-        try (var __ = svDelegate.readLock()) {
+        try (var __ = svDelegate.automaticReadLock()) {
             Rectangle2f r = svDelegate.getCellRect(cell);
             AffineTransformation2f t = ssvDelegate.getTransformation();
             Rectangle bounds = SwingGraphics.convert(Rectangle2f.withCorners(

meja-swing/src/main/java/com/dua3/meja/ui/swing/SwingSheetView.java

@@ -41,7 +41,6 @@
 import java.awt.event.InputEvent;
 import java.awt.event.KeyEvent;
 import java.util.Locale;
-import java.util.concurrent.locks.Lock;
 
 /**
  * Swing component for displaying instances of {@link Sheet}.
@@ -231,15 +230,11 @@ public void updateContent() {
         LOG.debug("updating content");
 
         Sheet sheet = getSheet();
-        Lock lock = delegate.writeLock();
-        lock.lock();
-        try {
+        try (var __ = delegate.automaticWriteLock()){
             int dpi = Toolkit.getDefaultToolkit().getScreenResolution();
             delegate.setDisplayScale(getDisplayScale());
             delegate.setScale(new Scale2f(sheet.getZoom() * dpi / 72.0f));
             delegate.updateLayout();
-        } finally {
-            lock.unlock();
         }
         SwingUtilities.invokeLater(() -> {
             delegate.getSheetPainter().update(sheet);