Support orphans/widows processing

DEVSIX-1858

Author: yulian-gaponenko

io/src/main/java/com/itextpdf/io/LogMessageConstant.java

@@ -150,6 +150,7 @@ public final class LogMessageConstant {
     public static final String ONE_OF_GROUPED_SOURCES_CLOSING_FAILED = "Closing of one of the grouped sources failed.";
     public static final String ONLY_ONE_OF_ARTBOX_OR_TRIMBOX_CAN_EXIST_IN_THE_PAGE = "Only one of artbox or trimbox can exist on the page. The trimbox will be deleted";
     public static final String OPENTYPE_GDEF_TABLE_ERROR = "OpenType GDEF table error: {0}";
+    public static final String ORPHANS_CONSTRAINT_VIOLATED = "Orphans constraint violated for paragraph split at page {0}. Min number of orphans: {1}; actual: {2}. \nComment: {3}";
     public static final String PAGE_TREE_IS_BROKEN_FAILED_TO_RETRIEVE_PAGE = "Page tree is broken. Failed to retrieve page number {0}. Null will be returned.";
     public static final String PASSED_PAGE_SHALL_BE_ON_WHICH_CANVAS_WILL_BE_RENDERED = "The page passed to Canvas#enableAutoTagging(PdfPage) method shall be the one on which this canvas will be rendered. However the actual passed PdfPage instance sets not such page. This might lead to creation of malformed PDF document.";
     public static final String PATH_KEY_IS_PRESENT_VERTICES_WILL_BE_IGNORED = "Path key is present. Vertices will be ignored";
@@ -159,6 +160,7 @@ public final class LogMessageConstant {
     public static final String PDF_WRITER_CLOSING_FAILED = "PdfWriter closing failed due to the error occurred!";
     public static final String PNG_IMAGE_HAS_ICC_PROFILE_WITH_INCOMPATIBLE_NUMBER_OF_COLOR_COMPONENTS = "Png image has color profile with incompatible number of color components.";
     public static final String POPUP_ENTRY_IS_NOT_POPUP_ANNOTATION = "Popup entry in the markup annotations refers not to the annotation with Popup subtype.";
+    public static final String PREMATURE_CALL_OF_HANDLE_VIOLATION_METHOD = "Premature call of handleViolation method.";
     public static final String PROPERTY_IN_PERCENTS_NOT_SUPPORTED = "Property {0} in percents is not supported";
     public static final String RECTANGLE_HAS_NEGATIVE_OR_ZERO_SIZES = "The {0} rectangle has negative or zero sizes. It will not be displayed.";
     public static final String RECTANGLE_HAS_NEGATIVE_SIZE = "The {0} rectangle has negative size. It will not be displayed.";
@@ -197,6 +199,7 @@ public final class LogMessageConstant {
     public static final String UNKNOWN_ERROR_WHILE_PROCESSING_CMAP = "Unknown error while processing CMap.";
     public static final String UNSUPPORTED_COLOR_IN_DA = "Unsupported color in FormField's DA";
     public static final String VERSION_INCOMPATIBILITY_FOR_DICTIONARY_ENTRY = "\"{0}\" entry in the \"{1}\" dictionary is a {2} and higher version feature. It is meaningless for the current {3} version.";
+    public static final String WIDOWS_CONSTRAINT_VIOLATED = "Widows constraint violated for paragraph split at page {0}. Min number of widows: {1}; actual: {2}.\nComment: {3}";
     public static final String WRITER_ENCRYPTION_IS_IGNORED_APPEND = "Writer encryption will be ignored, because append mode is used. Document will preserve the original encryption (or will stay unencrypted)";
     public static final String WRITER_ENCRYPTION_IS_IGNORED_PRESERVE = "Writer encryption will be ignored, because preservation of encryption is enabled. Document will preserve the original encryption (or will stay unencrypted)";
     public static final String WRONG_MEDIABOX_SIZE_TOO_MANY_ARGUMENTS = "Wrong media box size: {0}. The arguments beyond the 4th will be ignored";

layout/src/main/java/com/itextpdf/layout/element/Paragraph.java

@@ -47,6 +47,8 @@ This file is part of the iText (R) project.
 import com.itextpdf.kernel.pdf.tagutils.DefaultAccessibilityProperties;
 import com.itextpdf.kernel.pdf.tagutils.AccessibilityProperties;
 import com.itextpdf.layout.property.Leading;
+import com.itextpdf.layout.property.ParagraphOrphansControl;
+import com.itextpdf.layout.property.ParagraphWidowsControl;
 import com.itextpdf.layout.property.Property;
 import com.itextpdf.layout.property.UnitValue;
 import com.itextpdf.layout.renderer.IRenderer;
@@ -198,6 +200,28 @@ public Paragraph setFirstLineIndent(float indent) {
         return this;
     }
 
+    /**
+     * Sets orphans restriction on a {@link Paragraph}.
+     *
+     * @param orphansControl an instance of {@link ParagraphOrphansControl}.
+     * @return this {@link Paragraph} instance.
+     */
+    public Paragraph setOrphansControl(ParagraphOrphansControl orphansControl) {
+        setProperty(Property.ORPHANS_CONTROL, orphansControl);
+        return this;
+    }
+
+    /**
+     * Sets widows restriction on a {@link Paragraph}.
+     *
+     * @param widowsControl an instance of {@link ParagraphWidowsControl}.
+     * @return this {@link Paragraph} instance.
+     */
+    public Paragraph setWidowsControl(ParagraphWidowsControl widowsControl) {
+        setProperty(Property.WIDOWS_CONTROL, widowsControl);
+        return this;
+    }
+
     /**
      * Sets the leading value, using the {@link Leading#FIXED} strategy.
      *

layout/src/main/java/com/itextpdf/layout/property/ParagraphOrphansControl.java

@@ -0,0 +1,65 @@
+package com.itextpdf.layout.property;
+
+import com.itextpdf.io.LogMessageConstant;
+import com.itextpdf.io.util.MessageFormatUtil;
+import com.itextpdf.layout.renderer.ParagraphRenderer;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * A specialized class holding configurable parameters related to {@link com.itextpdf.layout.element.Paragraph}'s
+ * orphans restrictions. This class is meant to be used as the value for the {@link Property#ORPHANS_CONTROL} key.
+ */
+public class ParagraphOrphansControl {
+    private int minOrphans;
+
+    /**
+     * Creates a {@link ParagraphOrphansControl} instance with a specified orphans limitation.
+     *
+     * @param minOrphans minimal number of paragraph's lines to remain on an area before an area break.
+     */
+    public ParagraphOrphansControl(int minOrphans) {
+        this.minOrphans = minOrphans;
+    }
+
+    /**
+     * Sets parameter that defines orphans restrictions.
+     *
+     * @param minOrphans minimal number of paragraph's lines to remain on an area before an area break.
+     * @return this {@link ParagraphOrphansControl} instance
+     */
+    public ParagraphOrphansControl setMinAllowedOrphans(int minOrphans) {
+        this.minOrphans = minOrphans;
+        return this;
+    }
+
+    /**
+     * Gets minimal number of paragraph's lines to remain on an area before a split.
+     *
+     * @return minimal number of paragraph's lines to remain on an area before an area break.
+     */
+    public int getMinOrphans() {
+        return minOrphans;
+    }
+
+    /**
+     * Writes a log message reporting that orphans constraint is violated.
+     *
+     * This method is to be overridden if violation scenarios need to be handled in some other way.
+     *
+     * @param renderer a renderer processing orphans
+     * @param message  {@link String} explaining the reason for violation
+     */
+    public void handleViolatedOrphans(ParagraphRenderer renderer, String message) {
+        Logger logger = LoggerFactory.getLogger(ParagraphOrphansControl.class);
+        if (renderer.getOccupiedArea() != null && renderer.getLines() != null) {
+            int pageNumber = renderer.getOccupiedArea().getPageNumber();
+            String warnText = MessageFormatUtil.format(LogMessageConstant.ORPHANS_CONSTRAINT_VIOLATED, pageNumber,
+                    minOrphans, renderer.getLines().size(), message);
+            logger.warn(warnText);
+        } else {
+            logger.warn(LogMessageConstant.PREMATURE_CALL_OF_HANDLE_VIOLATION_METHOD);
+        }
+    }
+}

layout/src/main/java/com/itextpdf/layout/property/ParagraphWidowsControl.java

@@ -0,0 +1,101 @@
+package com.itextpdf.layout.property;
+
+import com.itextpdf.io.LogMessageConstant;
+import com.itextpdf.io.util.MessageFormatUtil;
+import com.itextpdf.layout.renderer.ParagraphRenderer;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * A specialized class holding configurable parameters related to {@link com.itextpdf.layout.element.Paragraph}'s
+ * widows restrictions. This class is meant to be used as the value for the {@link Property#WIDOWS_CONTROL} key.
+ */
+public class ParagraphWidowsControl {
+    private int minWidows;
+    private int maxLinesToMove;
+    private boolean overflowOnWidowsViolation;
+
+    /**
+     * Creates a {@link ParagraphWidowsControl} instance with specified widows restrictions.
+     *
+     * @param minWidows                    minimal number of paragraph's lines to be overflowed to the next area.
+     * @param maxLinesToMove               a number of lines that are allowed to be moved to the next area
+     *                                     in order to fix widows constraint violation.
+     * @param overflowParagraphOnViolation defines whether the entire paragraph should be pushed to the next area
+     *                                     if widows constraint is violated and cannot be automatically fixed.
+     */
+    public ParagraphWidowsControl(int minWidows, int maxLinesToMove, boolean overflowParagraphOnViolation) {
+        this.minWidows = minWidows;
+        this.maxLinesToMove = maxLinesToMove;
+        overflowOnWidowsViolation = overflowParagraphOnViolation;
+    }
+
+    /**
+     * Sets parameters that define widows restrictions and conditions of handling cases of widows constraint violation.
+     *
+     * @param minWidows                    minimal number of paragraph's lines to be overflowed to the next area.
+     * @param maxLinesToMove               a number of lines that are allowed to be moved to the next area
+     *                                     in order to fix widows constraint violation.
+     * @param overflowParagraphOnViolation defines whether paragraph should be completely pushed to the next area
+     *                                     if widows constraint is violated and cannot be automatically fixed.
+     * @return this {@link ParagraphWidowsControl} instance.
+     */
+    public ParagraphWidowsControl setMinAllowedWidows(int minWidows, int maxLinesToMove,
+            boolean overflowParagraphOnViolation) {
+        this.minWidows = minWidows;
+        this.maxLinesToMove = maxLinesToMove;
+        overflowOnWidowsViolation = overflowParagraphOnViolation;
+        return this;
+    }
+
+    /**
+     * Gets minimal number of paragraph's lines to be overflowed to the next area.
+     *
+     * @return minimal number of paragraph's lines to be overflowed to the next area
+     */
+    public int getMinWidows() {
+        return minWidows;
+    }
+
+    /**
+     * Gets a number of lines that are allowed to be moved to the next area in order to fix
+     * widows constraint violation.
+     *
+     * @return a number of lines that are allowed to be moved to the next are
+     */
+    public int getMaxLinesToMove() {
+        return maxLinesToMove;
+    }
+
+    /**
+     * Indicates whether paragraph should be completely pushed to the next area if widows constraint is violated and
+     * cannot be automatically fixed.
+     *
+     * @return true if paragraph should be completely pushed to the next area if widows constraint is violated and
+     * cannot be automatically fixed, otherwise - false
+     */
+    public boolean isOverflowOnWidowsViolation() {
+        return overflowOnWidowsViolation;
+    }
+
+    /**
+     * Writes a log message reporting that widows constraint is violated and cannot be automatically fixed.
+     *
+     * This method is to be overridden if violation scenarios need to be handled in some other way.
+     *
+     * @param widowsRenderer a renderer processing widows
+     * @param message        {@link String} explaining the reason for violation
+     */
+    public void handleViolatedWidows(ParagraphRenderer widowsRenderer, String message) {
+        Logger logger = LoggerFactory.getLogger(ParagraphWidowsControl.class);
+        if (widowsRenderer.getOccupiedArea() != null && widowsRenderer.getLines() != null) {
+            int pageNumber = widowsRenderer.getOccupiedArea().getPageNumber();
+            String warnText = MessageFormatUtil.format(LogMessageConstant.WIDOWS_CONSTRAINT_VIOLATED,
+                    pageNumber, minWidows, widowsRenderer.getLines().size(), message);
+            logger.warn(warnText);
+        } else {
+            logger.warn(LogMessageConstant.PREMATURE_CALL_OF_HANDLE_VIOLATION_METHOD);
+        }
+    }
+}

layout/src/main/java/com/itextpdf/layout/property/Property.java

@@ -157,6 +157,7 @@ private Property() {
     public static final int NO_SOFT_WRAP_INLINE = 118;
 
     public static final int OPACITY = 92;
+    public static final int ORPHANS_CONTROL = 121;
     public static final int OUTLINE = 106;
     public static final int OUTLINE_OFFSET = 107;
     /**
@@ -208,6 +209,7 @@ private Property() {
      * Value of 1 is equivalent to no scaling
      **/
     public static final int VERTICAL_SCALING = 76;
+    public static final int WIDOWS_CONTROL = 122;
     public static final int WIDTH = 77;
     public static final int WORD_SPACING = 78;
 
@@ -217,7 +219,7 @@ private Property() {
      * related to textual operations. Indicates whether or not this type of property is inheritable.
      */
     private static final boolean[] INHERITED_PROPERTIES;
-    private static final int MAX_INHERITED_PROPERTY_ID = 119;
+    private static final int MAX_INHERITED_PROPERTY_ID = 122;
 
     static {
         INHERITED_PROPERTIES = new boolean[MAX_INHERITED_PROPERTY_ID + 1];
@@ -244,6 +246,7 @@ private Property() {
         INHERITED_PROPERTIES[Property.KEEP_TOGETHER] = true;
         INHERITED_PROPERTIES[Property.LEADING] = true;
         INHERITED_PROPERTIES[Property.NO_SOFT_WRAP_INLINE] = true;
+        INHERITED_PROPERTIES[Property.ORPHANS_CONTROL] = true;
         INHERITED_PROPERTIES[Property.SPACING_RATIO] = true;
         INHERITED_PROPERTIES[Property.SPLIT_CHARACTERS] = true;
         INHERITED_PROPERTIES[Property.STROKE_COLOR] = true;
@@ -252,6 +255,7 @@ private Property() {
         INHERITED_PROPERTIES[Property.TEXT_RENDERING_MODE] = true;
         INHERITED_PROPERTIES[Property.TEXT_RISE] = true;
         INHERITED_PROPERTIES[Property.UNDERLINE] = true;
+        INHERITED_PROPERTIES[Property.WIDOWS_CONTROL] = true;
         INHERITED_PROPERTIES[Property.WORD_SPACING] = true;
         INHERITED_PROPERTIES[Property.TAGGING_HELPER] = true;
         INHERITED_PROPERTIES[Property.TYPOGRAPHY_CONFIG] = true;