Initial documentation skeleton

Refactor text models to track the identifiers of text sections
and allow for efficient re-measuring.

.gitignore

@@ -11,3 +11,4 @@ bin
 out
 pom.xml.versionsBackup
 target
+*.dia~

com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/text/SyFontType.java

@@ -17,6 +17,8 @@
 package com.io7m.jsycamore.api.text;
 
 import java.util.List;
+import java.util.SortedMap;
+import java.util.TreeMap;
 
 /**
  * A font.
@@ -62,6 +64,7 @@ public interface SyFontType
    * Split the given text into lines based on the given page width; lines will
    * be broken in order to ensure that text fits within the page width.
    *
+   * @param textID The text identifier
    * @param text            The text
    * @param firstLineNumber The number of the first line
    * @param pageWidth       The page width
@@ -70,12 +73,15 @@ public interface SyFontType
    */
 
   default List<SyTextLineMeasuredType> textLayout(
+    final SyTextID textID,
     final SyText text,
-    final int firstLineNumber,
+    final SyTextLineNumber firstLineNumber,
     final int pageWidth)
   {
+    final var m = new TreeMap<SyTextID, SyText>();
+    m.put(textID, text);
     return this.textLayoutMultiple(
-      List.of(text),
+      m,
       firstLineNumber,
       pageWidth
     );
@@ -93,8 +99,8 @@ default List<SyTextLineMeasuredType> textLayout(
    */
 
   List<SyTextLineMeasuredType> textLayoutMultiple(
-    List<SyText> texts,
-    int firstLineNumber,
+    SortedMap<SyTextID, SyText> texts,
+    SyTextLineNumber firstLineNumber,
     int pageWidth
   );
 }

com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/text/SyTextID.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright © 2023 Mark Raynsford <[email protected]> https://www.io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+
+package com.io7m.jsycamore.api.text;
+
+import java.math.BigInteger;
+
+/**
+ * An identifier for a section of text.
+ *
+ * @param value The value
+ */
+
+public record SyTextID(BigInteger value)
+  implements Comparable<SyTextID>
+{
+  private static final SyTextID FIRST_ID =
+    new SyTextID(BigInteger.ZERO);
+
+  @Override
+  public int compareTo(
+    final SyTextID other)
+  {
+    return this.value.compareTo(other.value);
+  }
+
+  /**
+   * @return The next text ID
+   */
+
+  public SyTextID next()
+  {
+    return new SyTextID(this.value.add(BigInteger.ONE));
+  }
+
+  /**
+   * @return The first text ID
+   */
+
+  public static SyTextID first()
+  {
+    return FIRST_ID;
+  }
+}

com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/text/SyTextLineMeasuredType.java

@@ -23,7 +23,11 @@
 import com.io7m.jtensors.core.parameterized.vectors.PVector2I;
 
 /**
- * A line of text that has been analyzed/measured.
+ * <p>A line of text that has been analyzed/measured.</p>
+ * <p>Note that this line of text may have been produced as part of a text
+ * formatting operation, and therefore there is an 1:N relationship between
+ * the text given by {@link #textOriginal()} and {@link #textAsWrapped()}.
+ * All of the methods here work in terms of {@link #textAsWrapped()}.</p>
  */
 
 public interface SyTextLineMeasuredType
@@ -48,10 +52,16 @@ public interface SyTextLineMeasuredType
   PAreaSizeI<SySpaceParentRelativeType> textBounds();
 
   /**
-   * @return The actual text
+   * @return The original text that produced this line
    */
 
-  SyText text();
+  SyTextID textOriginal();
+
+  /**
+   * @return The actual text after analysis/wrapping
+   */
+
+  SyText textAsWrapped();
 
   /**
    * Inspect the text at the given position. The information returned includes
@@ -97,5 +107,5 @@ default SyTextLocationType inspectAtParentRelative(
    * @return The line number
    */
 
-  int lineNumber();
+  SyTextLineNumber lineNumber();
 }

com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/text/SyTextLineNumber.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright © 2023 Mark Raynsford <[email protected]> https://www.io7m.com
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+
+package com.io7m.jsycamore.api.text;
+
+/**
+ * A line number.
+ *
+ * @param value The line number
+ */
+
+public record SyTextLineNumber(int value)
+  implements Comparable<SyTextLineNumber>
+{
+  private static final SyTextLineNumber FIRST =
+    new SyTextLineNumber(0);
+
+  /**
+   * @return The first line number
+   */
+
+  public static SyTextLineNumber first()
+  {
+    return FIRST;
+  }
+
+  @Override
+  public String toString()
+  {
+    return Integer.toUnsignedString(this.value);
+  }
+
+  @Override
+  public int compareTo(
+    final SyTextLineNumber o)
+  {
+    return Integer.compareUnsigned(this.value, o.value);
+  }
+
+  /**
+   * @return The next line number
+   */
+
+  public SyTextLineNumber next()
+  {
+    return new SyTextLineNumber(this.value + 1);
+  }
+}

com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/text/SyTextLocationType.java

@@ -33,7 +33,7 @@ public interface SyTextLocationType
    * @return The line number of the text
    */
 
-  int lineNumber();
+  SyTextLineNumber lineNumber();
 
   /**
    * @return The character at the location

com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/text/SyTextMultiLineModelReadableType.java

@@ -41,6 +41,23 @@ public interface SyTextMultiLineModelReadableType
 
   int pageWidth();
 
+  /**
+   * @return The text sections present in the model
+   */
+
+  SortedMap<SyTextID, SyText> textSections();
+
+  /**
+   * The text section that contains the given line number.
+   *
+   * @param lineNumber The line number
+   *
+   * @return The text section, if any
+   */
+
+  Optional<SyText> textSectionContainingLine(
+    SyTextLineNumber lineNumber);
+
   /**
    * The set of measured lines with their associated Y coordinate.
    *

com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/windows/SyWindowCloseBehaviour.java

@@ -17,22 +17,20 @@
 
 package com.io7m.jsycamore.api.windows;
 
-import com.io7m.jsycamore.api.screens.SyScreenType;
-
 /**
  * The behaviour that will occur when a window's "Close" button is pressed.
  */
 
 public enum SyWindowCloseBehaviour
 {
   /**
-   * The window will be hidden, as per {@link SyScreenType#windowHide(SyWindowType)}.
+   * The window will be hidden, as per {@link SyWindowServiceType#windowHide(SyWindowType)}.
    */
 
   HIDE_ON_CLOSE_BUTTON,
 
   /**
-   * The window will be closed, as per {@link SyScreenType#windowClose(SyWindowType)}
+   * The window will be closed, as per {@link SyWindowServiceType#windowClose(SyWindowType)}
    * (SyWindowType)}.
    */
 

com.io7m.jsycamore.api/src/main/java/com/io7m/jsycamore/api/windows/SyWindowDeletionPolicy.java

@@ -16,16 +16,14 @@
 
 package com.io7m.jsycamore.api.windows;
 
-import com.io7m.jsycamore.api.screens.SyScreenType;
-
 /**
  * The deletion policy for a window.
  */
 
 public enum SyWindowDeletionPolicy
 {
   /**
-   * The window may be deleted with {@link SyScreenType#windowClose(SyWindowType)}.
+   * The window may be deleted with {@link SyWindowServiceType#windowClose(SyWindowType)}.
    */
 
   WINDOW_MAY_BE_DELETED,

com.io7m.jsycamore.awt/src/main/java/com/io7m/jsycamore/awt/internal/SyAWTFont.java

@@ -21,8 +21,9 @@
 import com.io7m.jsycamore.api.text.SyFontDescription;
 import com.io7m.jsycamore.api.text.SyFontType;
 import com.io7m.jsycamore.api.text.SyText;
-import com.io7m.jsycamore.api.text.SyTextDirection;
+import com.io7m.jsycamore.api.text.SyTextID;
 import com.io7m.jsycamore.api.text.SyTextLineMeasuredType;
+import com.io7m.jsycamore.api.text.SyTextLineNumber;
 
 import java.awt.Font;
 import java.awt.FontMetrics;
@@ -33,6 +34,7 @@
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Objects;
+import java.util.SortedMap;
 
 /**
  * A font loaded using AWT.
@@ -93,20 +95,30 @@ public SyFontDescription description()
 
   @Override
   public List<SyTextLineMeasuredType> textLayoutMultiple(
-    final List<SyText> texts,
-    final int firstLineNumber,
+    final SortedMap<SyTextID, SyText> texts,
+    final SyTextLineNumber firstLineNumber,
     final int pageWidth)
   {
     Objects.requireNonNull(texts, "texts");
 
+    if (texts.isEmpty()) {
+      return List.of();
+    }
+
     final var results =
       new LinkedList<SyTextLineMeasuredType>();
 
     var lineNumber = firstLineNumber;
-    for (final var text : texts) {
+
+    for (final var textEntry : texts.entrySet()) {
+      final var textID =
+        textEntry.getKey();
+      final var text =
+        textEntry.getValue();
+
       if (text.value().isEmpty()) {
-        results.add(this.emptySectionLine(pageWidth, lineNumber));
-        ++lineNumber;
+        results.add(this.emptySectionLine(pageWidth, textID, lineNumber));
+        lineNumber = lineNumber.next();
         continue;
       }
 
@@ -153,32 +165,31 @@ public List<SyTextLineMeasuredType> textLayoutMultiple(
             PAreaSizeI.of(textWidth, this.textHeight()),
             lineNumber,
             layout,
+            textID,
             new SyText(brokenText, text.direction())
           );
 
         results.add(line);
         indexThen = indexNow;
-        ++lineNumber;
+        lineNumber = lineNumber.next();
       }
     }
 
-    if (results.isEmpty()) {
-      return List.of(this.emptySectionLine(pageWidth, lineNumber));
-    }
-
     return results;
   }
 
   private SyTextLineMeasuredType emptySectionLine(
     final int pageWidth,
-    final int lineNumber)
+    final SyTextID textID,
+    final SyTextLineNumber lineNumber)
   {
       return new SyAWTTextAnalyzed(
         pageWidth,
         PAreaSizeI.of(0, this.textHeight()),
         lineNumber,
         new TextLayout(" ", this.font, this.metrics.getFontRenderContext()),
-        new SyText("", SyTextDirection.TEXT_DIRECTION_LEFT_TO_RIGHT)
+        textID,
+        SyText.empty()
       );
   }
 }