GH-513 text extraction and selection enhancements and keyboard support

core/core-awt/src/main/java/org/icepdf/core/pobjects/graphics/text/Bias.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2026 Patrick Corless
+ *
+ * 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 org.icepdf.core.pobjects.graphics.text;
+
+/**
+ * Caret bias used to disambiguate an offset that sits on a boundary shared by two
+ * positions (a line wrap, or the seam between two glyphs).  Mirrors the intent of
+ * {@code javax.swing.text.Position.Bias}.
+ *
+ * @see Caret
+ * @since 7.5
+ */
+public enum Bias {
+    /**
+     * The caret associates with the content that follows the offset.
+     */
+    FORWARD,
+    /**
+     * The caret associates with the content that precedes the offset.
+     */
+    BACKWARD
+}

core/core-awt/src/main/java/org/icepdf/core/pobjects/graphics/text/BreakType.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2026 Patrick Corless
+ *
+ * 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 org.icepdf.core.pobjects.graphics.text;
+
+/**
+ * Granularity of caret-boundary navigation used by {@link TextSequence#nextBoundary}.
+ *
+ * @since 7.5
+ */
+public enum BreakType {
+    /** A single glyph/character step. */
+    GLYPH,
+    /** A word boundary. */
+    WORD,
+    /** A line boundary. */
+    LINE
+}

core/core-awt/src/main/java/org/icepdf/core/pobjects/graphics/text/Caret.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2026 Patrick Corless
+ *
+ * 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 org.icepdf.core.pobjects.graphics.text;
+
+/**
+ * An immutable page-local caret: a character {@code offset} into a {@link TextSequence}
+ * plus a {@link Bias} used to disambiguate boundary positions.  The owning viewer is
+ * responsible for pairing this with a page index for document-level selection.
+ *
+ * @see TextSequence
+ * @since 7.5
+ */
+public final class Caret {
+
+    private final int offset;
+    private final Bias bias;
+
+    public Caret(int offset, Bias bias) {
+        this.offset = offset;
+        this.bias = bias;
+    }
+
+    public int getOffset() {
+        return offset;
+    }
+
+    public Bias getBias() {
+        return bias;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof Caret)) return false;
+        Caret caret = (Caret) o;
+        return offset == caret.offset && bias == caret.bias;
+    }
+
+    @Override
+    public int hashCode() {
+        return 31 * offset + (bias == null ? 0 : bias.hashCode());
+    }
+
+    @Override
+    public String toString() {
+        return "Caret[" + offset + ", " + bias + ']';
+    }
+}

core/core-awt/src/main/java/org/icepdf/core/pobjects/graphics/text/OffsetRange.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2026 Patrick Corless
+ *
+ * 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 org.icepdf.core.pobjects.graphics.text;
+
+/**
+ * An immutable, normalized half-open character-offset range {@code [start, end)} into a
+ * {@link TextSequence}.  {@code start} is always {@code <= end}.
+ *
+ * @see TextSequence
+ * @since 7.5
+ */
+public final class OffsetRange {
+
+    private final int start;
+    private final int end;
+
+    private OffsetRange(int start, int end) {
+        this.start = start;
+        this.end = end;
+    }
+
+    /**
+     * Creates a normalized range from two offsets in either order.
+     *
+     * @param a one endpoint
+     * @param b the other endpoint
+     * @return range with {@code start = min(a,b)}, {@code end = max(a,b)}
+     */
+    public static OffsetRange of(int a, int b) {
+        return a <= b ? new OffsetRange(a, b) : new OffsetRange(b, a);
+    }
+
+    public int getStart() {
+        return start;
+    }
+
+    public int getEnd() {
+        return end;
+    }
+
+    public int length() {
+        return end - start;
+    }
+
+    public boolean isEmpty() {
+        return end == start;
+    }
+
+    public boolean contains(int offset) {
+        return offset >= start && offset < end;
+    }
+
+    public OffsetRange union(OffsetRange other) {
+        return new OffsetRange(Math.min(start, other.start), Math.max(end, other.end));
+    }
+
+    /**
+     * Returns this range clamped so both endpoints fall within {@code [0, max]}.
+     *
+     * @param max upper bound (typically the sequence length)
+     * @return clamped range
+     */
+    public OffsetRange clamp(int max) {
+        int s = Math.max(0, Math.min(start, max));
+        int e = Math.max(0, Math.min(end, max));
+        return of(s, e);
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof OffsetRange)) return false;
+        OffsetRange that = (OffsetRange) o;
+        return start == that.start && end == that.end;
+    }
+
+    @Override
+    public int hashCode() {
+        return 31 * start + end;
+    }
+
+    @Override
+    public String toString() {
+        return "OffsetRange[" + start + ", " + end + ")";
+    }
+}

core/core-awt/src/main/java/org/icepdf/core/pobjects/graphics/text/PageText.java

@@ -46,14 +46,39 @@
 public class PageText implements TextSelect {
 
     private static final boolean checkForDuplicates;
-    private static final boolean preserveColumns;
+
+    /** Page reading-order strategy applied to the sorted line list. */
+    private enum ReadingOrder {PLOT, YSORT, XYCUT}
+
+    private static final ReadingOrder readingOrder;
 
     static {
         checkForDuplicates = Defs.booleanProperty(
                 "org.icepdf.core.views.page.text.trim.duplicates", false);
 
-        preserveColumns = Defs.booleanProperty(
+        // readingOrder supersedes the older boolean preserveColumns; when readingOrder is not set
+        // we derive the mode from preserveColumns so existing configurations behave unchanged.
+        //   plot  = preserveColumns=true  (default): keep content-stream plot order
+        //   ysort = preserveColumns=false          : global top-to-bottom y-sort
+        //   xycut =                                  geometry-driven column/band ordering
+        boolean preserveColumns = Defs.booleanProperty(
                 "org.icepdf.core.views.page.text.preserveColumns", true);
+        String mode = Defs.sysProperty("org.icepdf.core.views.page.text.readingOrder");
+        if (mode == null) {
+            readingOrder = preserveColumns ? ReadingOrder.PLOT : ReadingOrder.YSORT;
+        } else {
+            switch (mode.trim().toLowerCase()) {
+                case "ysort":
+                    readingOrder = ReadingOrder.YSORT;
+                    break;
+                case "xycut":
+                    readingOrder = ReadingOrder.XYCUT;
+                    break;
+                default:
+                    readingOrder = ReadingOrder.PLOT;
+                    break;
+            }
+        }
     }
 
     // pointer to current line during document parse, no other use.
@@ -63,6 +88,9 @@ public class PageText implements TextSelect {
     private final ArrayList<LineText> pageLines;
     private ArrayList<LineText> sortedPageLines;
 
+    // reading-order view over sortedPageLines; lazily built, invalidated on re-sort.
+    private TextSequence textSequence;
+
     private AffineTransform previousTextTransform;
     private AffineTransform previousXObjectTransform;
 
@@ -139,6 +167,21 @@ public ArrayList<LineText> getPageLines() {
         return sortedPageLines;
     }
 
+    /**
+     * Gets the reading-order {@link TextSequence} for this page, a flattened view over the
+     * sorted page lines that maps between page-space points, character offsets, and the
+     * underlying glyph/word/line structure.  The value is cached and rebuilt whenever the
+     * page re-sorts (see {@link #sortAndFormatText}).
+     *
+     * @return reading-order sequence for this page's visible text.
+     */
+    public TextSequence getTextSequence() {
+        if (textSequence == null) {
+            textSequence = new TextSequence(this);
+        }
+        return textSequence;
+    }
+
     /**
      * Gets all visible lines, checking the page text for any text that is
      * in an optional content group and that that group is flagged as visible.
@@ -567,9 +610,21 @@ public void sortAndFormatText() {
             }
         }
 
-        // sort the lines
-        if (sortedPageLines.size() > 0 && !preserveColumns) {
-            sortedPageLines.sort(new LinePositionComparator());
+        // order the lines according to the configured reading-order strategy.  PLOT keeps the
+        // content-stream order the slicing produced; YSORT is a global top-to-bottom sort; XYCUT
+        // applies geometry-driven column/band ordering (see XYCutReadingOrder).
+        if (sortedPageLines.size() > 0) {
+            switch (readingOrder) {
+                case YSORT:
+                    sortedPageLines.sort(new LinePositionComparator());
+                    break;
+                case XYCUT:
+                    sortedPageLines = XYCutReadingOrder.order(sortedPageLines);
+                    break;
+                case PLOT:
+                default:
+                    break;
+            }
         }
 
         // Round out the word bounds
@@ -594,6 +649,8 @@ public void sortAndFormatText() {
         // assign back the sorted lines.
         this.sortedPageLines = sortedPageLines;
 
+        // invalidate the reading-order view so it rebuilds from the new sort.
+        this.textSequence = null;
     }