PDF emitter VerticalTab user property (#2020)

Added support for a new UserProperty `PdfEmitter.VerticalTab` to the PDF emitter.
The property can be set for cells and text items/labels/data and is used to go down at least a given *fixed distance* measured from the top of the page body, independent from the height of already was written further above on the page.

UI/org.eclipse.birt.report.designer.samplereports/samplereports/Reporting Feature Examples/PDF Vertical Tab/.project

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>Vertical Tab</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.birt.report.designer.ui.reportprojectnature</nature>
+	</natures>
+</projectDescription>

engine/org.eclipse.birt.report.engine.emitter.pdf/src/org/eclipse/birt/report/engine/emitter/pdf/README.md

@@ -2,7 +2,7 @@
 Introduction to use the specialized user properties of the PdfEmitter.
 
 ## Reason
-The PdfEmitter provides a set of specialized user properties to optimize the pdf output according of the reporting based requirements.
+The PdfEmitter provides a set of specialized user properties to optimize the PDF output according of the reporting based requirements.
 
 Each of the user properties starts with the master prefix "PdfEmitter".
 
@@ -121,3 +121,19 @@ The following list get an overview of all supported user properties, the content
 	Default    	1.5
 	Since      	4.16
 	Designer  	4.17
+
+**PdfEmitter.VerticalTab**
+
+	Content    	Go down to an Y position this far from the top before starting the content.
+					If we are already down this far, this will not go further down.
+					This can be specified in cells of table or grids, or in text/data items.
+					The distance is measured from the top of the page body.
+					For example, a value of "20cm", when the master page has 1cm margin-top
+					and a page header of 15mm, results in the content starting at 225mm from
+					the top of the sheet.
+					This results in the content to be shown *at least* this far down from the top.
+	Location   	cell or text/data.
+	Data type  	string
+	Values     	An absolute length, e.g. "20cm"
+	Default    	empty (null)
+	Since      	4.19

engine/org.eclipse.birt.report.engine/src/org/eclipse/birt/report/engine/nLayout/area/impl/BlockContainerArea.java

@@ -32,6 +32,8 @@
 import org.eclipse.birt.report.engine.util.BidiAlignmentResolver;
 import org.w3c.dom.css.CSSValue;
 
+
+
 /**
  * Implementation of block container area
  *
@@ -69,6 +71,29 @@ public BlockContainerArea() {
 
 	@Override
 	public void add(AbstractArea area) {
+		if (area instanceof ContainerArea) {
+			ContainerArea c = (ContainerArea) area;
+			IContent containerContent = c.getContent();
+			if (containerContent != null && containerContent.getUserProperties() != null) {
+				// Variant 1: The property has to be set for a Label, a Dynamic Text Item or
+				// similar (not for a table row or cell).
+				// A possible structure:
+				// ...
+				// A dynamic Text Item with FixYPosition=20cm.
+				String fixYPosition = (String) containerContent.getUserProperties().get(PDF_VERTICAL_TAB);
+				if (fixYPosition != null) {
+					int limit = getDimensionValue(
+							content.getCSSEngine().parsePropertyValue(StyleConstants.STYLE_MARGIN_TOP, fixYPosition));
+					int absBP = getAbsoluteBP();
+					if (absBP > limit) {
+						// Page break required
+					} else if (absBP < limit) {
+						// Increment currentBP
+						currentBP += (limit - absBP);
+					}
+				}
+			}
+		}
 		children.add(area);
 		area.setAllocatedPosition(currentIP + getOffsetX(), currentBP + getOffsetY());
 

engine/org.eclipse.birt.report.engine/src/org/eclipse/birt/report/engine/nLayout/area/impl/ContainerArea.java

@@ -57,6 +57,12 @@
  */
 public abstract class ContainerArea extends AbstractArea implements IContainerArea {
 
+	/**
+	 * Can be used in the PdfEmitter to create an effect similar to a vertical tab
+	 * stop. See org/eclipse/birt/report/engine/emitter/pdf/README.md for details.
+	 */
+	public static final String PDF_VERTICAL_TAB = "PdfEmitter.VerticalTab";
+
 	protected transient LocalProperties localProperties = LocalProperties.DEFAULT;
 
 	protected BoxStyle boxStyle = BoxStyle.DEFAULT;

engine/org.eclipse.birt.report.engine/src/org/eclipse/birt/report/engine/nLayout/area/impl/RowArea.java

@@ -20,6 +20,7 @@
 import org.eclipse.birt.core.exception.BirtException;
 import org.eclipse.birt.report.engine.content.IContent;
 import org.eclipse.birt.report.engine.content.IStyle;
+import org.eclipse.birt.report.engine.css.engine.StyleConstants;
 import org.eclipse.birt.report.engine.css.engine.value.css.CSSConstants;
 import org.eclipse.birt.report.engine.css.engine.value.css.CSSValueConstants;
 import org.eclipse.birt.report.engine.nLayout.LayoutContext;
@@ -230,6 +231,28 @@ public void add(AbstractArea area) {
 		if (content != null && content.isRTL()) {
 			cArea.flipPositionForRtl();
 		}
+		// Variant 2 . The property must be set for a Cell.
+		// A possible structure:
+		// Table
+		// Header
+		// Details
+		// Footer-Row with Cell with VerticalTab=20cm.
+		// Footer-Row with information that should be shown starting with y=20cm.
+		IContent cellContent = cArea.getContent();
+		if (cellContent != null && cellContent.getUserProperties() != null) {
+			String verticalTab = (String) cellContent.getUserProperties().get(PDF_VERTICAL_TAB);
+			if (verticalTab != null) {
+				int limit = getDimensionValue(
+						content.getCSSEngine().parsePropertyValue(StyleConstants.STYLE_MARGIN_TOP, verticalTab));
+				int absBP = getAbsoluteBP();
+				if (absBP > limit) {
+					// Page break required
+				} else if (absBP < limit) {
+					cArea.localProperties.paddingTop += (limit - absBP);
+					cArea.setAllocatedHeight(cArea.getAllocatedHeight() + (limit - absBP));
+				}
+			}
+		}
 	}
 
 	@Override