Support a caption for a table. Add some new tests.

DEVSIX-982

Author: ars18wrw

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

@@ -44,12 +44,14 @@ This file is part of the iText (R) project.
 package com.itextpdf.layout.element;
 
 import com.itextpdf.kernel.PdfException;
+import com.itextpdf.kernel.colors.ColorConstants;
 import com.itextpdf.kernel.pdf.tagging.StandardRoles;
 import com.itextpdf.kernel.pdf.tagutils.AccessibilityProperties;
 import com.itextpdf.kernel.pdf.tagutils.DefaultAccessibilityProperties;
 import com.itextpdf.layout.Document;
 import com.itextpdf.layout.borders.Border;
 import com.itextpdf.layout.property.BorderCollapsePropertyValue;
+import com.itextpdf.layout.property.CaptionSide;
 import com.itextpdf.layout.property.Property;
 import com.itextpdf.layout.property.UnitValue;
 import com.itextpdf.layout.renderer.IRenderer;
@@ -87,6 +89,7 @@ public class Table extends BlockElement<Table> implements ILargeElement {
     private int rowWindowStart = 0;
     private Document document;
     private Cell[] lastAddedRow;
+    private Div caption;
 
     /**
      * Constructs a {@code Table} with the preferable column widths.
@@ -513,6 +516,54 @@ public Table setSkipLastFooter(boolean skipLastFooter) {
         return this;
     }
 
+     /** Sets the table's caption.
+      *
+      * If there is no {@link Property#CAPTION_SIDE} set (note that it's an inheritable property),
+      * {@link CaptionSide#TOP} will be used.
+      * Also the {@link StandardRoles#CAPTION} will be set on the element.
+      *
+      * @param caption The element to be set as a caption.
+      * @return this element
+      */
+
+    public Table setCaption(Div caption) {
+        this.caption = caption;
+        if (null != caption) {
+            ensureCaptionPropertiesAreSet();
+        }
+        return this;
+    }
+
+    /**
+     * Sets the table's caption and its caption side.
+     *
+     * Also the {@link StandardRoles#CAPTION} will be set on the element.
+     *
+     * @param caption The element to be set as a caption.
+     * @param side The caption side to be set on the caption.
+     ** @return this element
+     */
+    public Table setCaption(Div caption, CaptionSide side) {
+        if (null != caption) {
+            caption.setProperty(Property.CAPTION_SIDE, side);
+        }
+        setCaption(caption);
+        return this;
+    }
+
+    private void ensureCaptionPropertiesAreSet() {
+        this.caption.getAccessibilityProperties().setRole(StandardRoles.CAPTION);
+    }
+
+    /**
+     * Gets the table's caption.
+     *
+     * @return the table's caption.
+     */
+    public Div getCaption() {
+        return caption;
+    }
+
     /**
      * Starts new row. This mean that next cell will be added at the beginning of next line.
      *
@@ -798,7 +849,7 @@ public Table setBorderCollapse(BorderCollapsePropertyValue collapsePropertyValue
         }
         return this;
     }
-    
+
     public Table setHorizontalBorderSpacing(float spacing) {
         setProperty(Property.HORIZONTAL_BORDER_SPACING, spacing);
         if (null != header) {
@@ -820,7 +871,7 @@ public Table setVerticalBorderSpacing(float spacing) {
         }
         return this;
     }
-    
+
     @Override
     public AccessibilityProperties getAccessibilityProperties() {
         if (tagProperties == null) {
@@ -915,10 +966,10 @@ private void ensureHeaderIsInitialized() {
                 header.setBorderCollapse((BorderCollapsePropertyValue) this.<BorderCollapsePropertyValue>getProperty(Property.BORDER_COLLAPSE));
             }
             if (hasOwnProperty(Property.HORIZONTAL_BORDER_SPACING)) {
-                header.setHorizontalBorderSpacing((float)this.<Float>getProperty(Property.HORIZONTAL_BORDER_SPACING));
+                header.setHorizontalBorderSpacing((float) this.<Float>getProperty(Property.HORIZONTAL_BORDER_SPACING));
             }
             if (hasOwnProperty(Property.VERTICAL_BORDER_SPACING)) {
-                header.setVerticalBorderSpacing((float)this.<Float>getProperty(Property.VERTICAL_BORDER_SPACING));
+                header.setVerticalBorderSpacing((float) this.<Float>getProperty(Property.VERTICAL_BORDER_SPACING));
             }
         }
     }
@@ -933,10 +984,10 @@ private void ensureFooterIsInitialized() {
                 footer.setBorderCollapse((BorderCollapsePropertyValue) this.<BorderCollapsePropertyValue>getProperty(Property.BORDER_COLLAPSE));
             }
             if (hasOwnProperty(Property.HORIZONTAL_BORDER_SPACING)) {
-                footer.setHorizontalBorderSpacing((float)this.<Float>getProperty(Property.HORIZONTAL_BORDER_SPACING));
+                footer.setHorizontalBorderSpacing((float) this.<Float>getProperty(Property.HORIZONTAL_BORDER_SPACING));
             }
             if (hasOwnProperty(Property.VERTICAL_BORDER_SPACING)) {
-                footer.setVerticalBorderSpacing((float)this.<Float>getProperty(Property.VERTICAL_BORDER_SPACING));
+                footer.setVerticalBorderSpacing((float) this.<Float>getProperty(Property.VERTICAL_BORDER_SPACING));
             }
         }
     }

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

@@ -0,0 +1,52 @@
+/*
+    This file is part of the iText (R) project.
+    Copyright (c) 1998-2018 iText Group NV
+    Authors: iText Software.
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License version 3
+    as published by the Free Software Foundation with the addition of the
+    following permission added to Section 15 as permitted in Section 7(a):
+    FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+    ITEXT GROUP. ITEXT GROUP DISCLAIMS THE WARRANTY OF NON INFRINGEMENT
+    OF THIRD PARTY RIGHTS
+
+    This program is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+    or FITNESS FOR A PARTICULAR PURPOSE.
+    See the GNU Affero General Public License for more details.
+    You should have received a copy of the GNU Affero General Public License
+    along with this program; if not, see http://www.gnu.org/licenses or write to
+    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+    Boston, MA, 02110-1301 USA, or download the license from the following URL:
+    http://itextpdf.com/terms-of-use/
+
+    The interactive user interfaces in modified source and object code versions
+    of this program must display Appropriate Legal Notices, as required under
+    Section 5 of the GNU Affero General Public License.
+
+    In accordance with Section 7(b) of the GNU Affero General Public License,
+    a covered work must retain the producer line in every PDF that is created
+    or manipulated using iText.
+
+    You can be released from the requirements of the license by purchasing
+    a commercial license. Buying such a license is mandatory as soon as you
+    develop commercial activities involving the iText software without
+    disclosing the source code of your own applications.
+    These activities include: offering paid services to customers as an ASP,
+    serving PDFs on the fly in a web application, shipping iText with a closed
+    source product.
+
+    For more information, please contact iText Software Corp. at this
+    address: [email protected]
+ */
+package com.itextpdf.layout.property;
+
+/**
+ * A specialized enum containing the potential caption side values for a {@link
+ * com.itextpdf.layout.element.Table}'s caption.
+ */
+public enum CaptionSide {
+    BOTTOM,
+    TOP
+}

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

@@ -78,6 +78,7 @@ private Property() {
     public static final int BORDER_TOP_RIGHT_RADIUS = 111;
     public static final int BOTTOM = 14;
     public static final int BOX_SIZING = 105;
+    public static final int CAPTION_SIDE = 119;
     public static final int CHARACTER_SPACING = 15;
     public static final int CLEAR = 100;
     public static final int COLLAPSING_MARGINS = 89;
@@ -213,14 +214,15 @@ 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 = 118;
+    private static final int MAX_INHERITED_PROPERTY_ID = 119;
 
     static {
         INHERITED_PROPERTIES = new boolean[MAX_INHERITED_PROPERTY_ID + 1];
 
         INHERITED_PROPERTIES[Property.APPEARANCE_STREAM_LAYOUT] = true;
         INHERITED_PROPERTIES[Property.BASE_DIRECTION] = true;
         INHERITED_PROPERTIES[Property.BOLD_SIMULATION] = true;
+        INHERITED_PROPERTIES[Property.CAPTION_SIDE] = true;
         INHERITED_PROPERTIES[Property.CHARACTER_SPACING] = true;
         INHERITED_PROPERTIES[Property.COLLAPSING_MARGINS] = true;
         INHERITED_PROPERTIES[Property.FIRST_LINE_INDENT] = true;

layout/src/main/java/com/itextpdf/layout/renderer/BlockFormattingContextUtil.java

@@ -74,6 +74,7 @@ public static boolean isRendererCreateBfc(IRenderer renderer) {
                 || FloatingHelper.isRendererFloating(renderer)
                 || isAbsolutePosition(renderer)
                 || isFixedPosition(renderer)
+                || isCaption(renderer)
                 || AbstractRenderer.isOverflowProperty(OverflowPropertyValue.HIDDEN, renderer, Property.OVERFLOW_X)
                 || AbstractRenderer.isOverflowProperty(OverflowPropertyValue.HIDDEN, renderer, Property.OVERFLOW_Y);
     }
@@ -92,4 +93,9 @@ private static boolean isFixedPosition(IRenderer renderer) {
         Integer positioning = NumberUtil.asInteger(renderer.<Object>getProperty(Property.POSITION));
         return Integer.valueOf(LayoutPosition.FIXED).equals(positioning);
     }
+
+    private static boolean isCaption(IRenderer renderer) {
+        return renderer.getParent() instanceof TableRenderer
+                && (renderer instanceof DivRenderer);
+    }
 }