Building .NET Document API Layouts Using Flat Element Hierarchy

When we draw text, graphics, and other elements on a PDF page (or JPEG, SVG, and so on), we need to specify their coordinates. If there are multiple elements on the page and the size or position of some elements depends on the size or position of other elements, this task is not easy. If we associate a rectangle with each element, our task is to calculate the coordinates of each of these rectangles. We can then fit and draw the elements into the target rectangles. In computer graphics and user interfaces, most frameworks are based on the container model, where elements are contained within the parent elements and have their own children. For example, in XAML, a ComboBox can be placed in a StackPanel, and that panel is added to a DockPanel, which is a child of the main Window. An alternative approach was suggested in Android with its ConstraintLayout and the Auto Layout of iOS/macOS. They offer a layout model with a flat view hierarchy (no nested view groups). That model is more flexible and customizable than the container model. The GrapeCity.Documents.Imaging library contains the GrapeCity.Documents.Layout namespace with a few classes implementing the flat layout model based on constraints. Instead of setting the exact position of an element, constraints define rules for how that position depends on the positions of other elements. The main distinction from the container model is that each parameter is configured separately and might rely on any other rectangle in the same view or even multiple rectangles if there are several constraints for the same parameter. For example: using System.Drawing; using GrapeCity.Documents.Drawing; using GrapeCity.Documents.Layout; using GrapeCity.Documents.Pdf;

const float pageWidth = 600; const float pageHeight = 400;

var doc = new GcPdfDocument(); var page = doc.NewPage(); page.Size = new SizeF(pageWidth, pageHeight); var g = page.Graphics; var baseTransform = g.Transform;

var host = new LayoutHost(); var view = host.CreateView(pageWidth, pageHeight);

var marginRect = view.CreateRect(); // marginRect.SetLeft(null, AnchorParam.Left, 36); // marginRect.SetTop(null, AnchorParam.Top, 36); // marginRect.SetRight(null, AnchorParam.Right, -36); // marginRect.SetBottom(null, AnchorParam.Bottom, -36); marginRect.AnchorDeflate(null, 36);

var redRect = view.CreateRect(); redRect.SetLeft(marginRect, AnchorParam.Left, 60); redRect.SetTop(marginRect, AnchorParam.Top, 40); redRect.SetWidth(180); redRect.SetHeight(70);

host.PerformLayout();

DrawRect(marginRect, Color.Green); DrawRect(redRect, Color.Red);

void DrawRect(LayoutRect rect, Color color) { g.Transform = rect.Transform.Multiply(baseTransform); g.DrawRectangle(rect.AsRectF(), new Pen(color)); }

g.Transform = baseTransform; doc.Save("doc1.pdf"); The resulting document in doc1.pdf looks like this: There is nothing special here, just two rectangles on a PDF page. But this code can be considered as the base for creating much more complex layouts. Let’s describe the main aspects. Initially, we create a PDF document with a page of the given size. Then we initialize a LayoutHost: var host = new LayoutHost(); LayoutHost is the root of the whole infrastructure of layout objects. It is used for creating views and defining the origin of the coordinate system. LayoutHost performs layout when other objects are prepared and linked. We always need a host to instantiate views and calculate the layout. var view = host.CreateView(pageWidth, pageHeight); LayoutView defines a root rectangle with fixed width and height. For example, in this simple case, the view dimensions are equal to the corresponding dimensions of the PDF page. Each view has the associated transformation matrix (the identity matrix by default). A LayoutView is used for hosting LayoutRect objects, rectangles whose sides are always parallel to either the X-axis or Y-axis of the view. The root rectangle of a LayoutView is not a clipping area. LayoutRects can be placed inside and outside the bounds of the view. It just defines the base dimensions to be referenced from constraints assigned to LayoutRect parameters. var marginRect = view.CreateRect(); We create a LayoutRect for the page margin. LayoutRect is a rectangle defined by four points: It can be rotated by a multiple of 90 degrees relative to the owner LayoutView. The main task of the layout engine is to calculate the position of the points P0, P1, and P2 for each LayoutRect within a LayoutHost. To make that possible, we need to define constraints that unambiguously determine the position and size of each rectangle, for example: marginRect.SetLeft(null, AnchorParam.Left, 36); marginRect.SetTop(null, AnchorParam.Top, 36); marginRect.SetRight(null, AnchorParam.Right, -36); marginRect.SetBottom(null, AnchorParam.Bottom, -36); Constraints can be defined relative to the owner LayoutView (if we pass the null value in the first parameter) or relative to any other LayoutRect that belongs to the same LayoutView. In the above code, we specify a 36-point padding for each side of the margin rectangle relative to the corresponding sides of the LayoutView. As you can see, the previous code is rather verbose. The LayoutRect class has several methods whose names start with “Anchor“, such as AnchorTopLeft, AnchorDeflate, and others. Those methods add multiple constraints at once. For example, all the above constraints can be set with a single line of code: marginRect.AnchorDeflate(null, 36); In the next step, we create another rectangle and specify constraints relative to the first one: var redRect = view.CreateRect(); redRect.SetLeft(marginRect, AnchorParam.Left, 60); redRect.SetTop(marginRect, AnchorParam.Top, 40); redRect.SetWidth(180); redRect.SetHeight(70); The width and height are defined with absolute values. Please note that we don’t set the Width and Height properties directly. Instead, we add the proper constraints to be resolved together with other constraints when we execute the following command: host.PerformLayout(); The LayoutHost calculates all rectangle coordinates based on the constraints provided. At this point, you can observe a LayoutException if some inconsistent combination of constraints was set. An interesting part of the drawing code: void DrawRect(LayoutRect rect, Color color) { g.Transform = rect.Transform.Multiply(baseTransform); g.DrawRectangle(rect.AsRectF(), new Pen(color)); } The local method accepts a LayoutRect and a color to draw the rectangle. After performing the layout, each LayoutRect has the associated transformation matrix. If we multiply that matrix by the transformation matrix of GcGraphics, the origin of the coordinate system is moved to the P0 point of the rectangle. The X-axis direction is P0P1, and the Y-axis direction is P0P2. The AsRectF method of a LayoutRect works like executing “new RectangleF(0, 0, rect.Width, rect.Height)“. Types of Constraints To make the layout consistent, we have to associate constraints with LayoutRects. The possible target parameters of a LayoutRect and the corresponding constraint classes are in the following table: To create a constraint, you can execute one of the following methods of the LayoutRect class: All constraints created with the Set… methods are unique. In other words, you must not assign two such constraints to the same parameter. Constraints created with the Append… methods don’t have to be unique. A problem might occur if you append inconsistent constraints, for example, if you add the MinWidth and MaxWidth constraints so that MaxWidth < MinWidth. One important thing. If you create a constraint for a rotated rectangle, move yourself to that rectangle’s point of view. For example, if the AngleConstraint is set to 270 degrees, the left side of a LayoutRect will be at the bottom, and the top side is actually at the left. But if you move yourself to that rectangle’s point of view, the left and top sides will correspondingly be at the left and top. Let’s modify the previous sample to display the red rectangle rotated: var redRect = view.CreateRect(); redRect.SetAngle(null, 270); redRect.SetTop(marginRect, AnchorParam.Left, 60); redRect.SetRight(marginRect, AnchorParam.Top, -30); redRect.SetWidth(180); redRect.SetHeight(70); The resulting document looks like this: The position of the red rectangle’s top side is set relative to the marginRect’s left side. The red’s right side is set relative to the marginRect’s top side. The right side has a negative offset because, from the rectangle’s point of view, we should move to the left from the top side of the marginRect. The left and up directions are negative, and the right and down directions correspond to a positive offset. Chains and Star Constraints Let’s assume we want to fill the whole width of some area with multiple rectangles having different proportional widths (weights). For example, we draw a table with four columns. The first column width is 20% of the second column width. The third column has a fixed width of 70 points. The fourth column width is 35% of the second column width. Star width constraints are handy for such cases: A star width specifies the proportion of the current column width in the sum of all star column widths. In the image above, if the full width is 300pt and the spacing between columns is 10pt, the sum width of all star columns is W = 300 - 70 - 10 * 3 = 200pt. The overall number of stars is S = 20 + 100 + 35 = 155. Individual column widths: W1 = 200 * 20 / 155, W2 = 200 * 100 / 155, W4 = 200 * 35 / 155. The full sample: using System.Drawing; using GrapeCity.Documents.Drawing; using GrapeCity.Documents.Layout; using GrapeCity.Documents.Pdf; using GrapeCity.Documents.Text;

const float pageWidth = 600; const float pageHeight = 400;

var doc = new GcPdfDocument(); var page = doc.NewPage(); page.Size = new SizeF(pageWidth, pageHeight); var g = page.Graphics; var baseTransform = g.Transform; var fmt = new TextFormat { FontName = "Calibri", FontSize = 16 };

var host = new LayoutHost(); var view = host.CreateView(pageWidth, pageHeight);

var marginRect = view.CreateRect("margin"); marginRect.AnchorDeflate(null, 36);

var redRect = view.CreateRect("red"); redRect.AnchorLeftTopBottom(marginRect, 10, 50, 150); redRect.SetStarWidth(20);

var blueRect = view.CreateRect("blue"); blueRect.AnchorTopBottom(marginRect, 50, 180); blueRect.SetStarWidth(100);

var orangeRect = view.CreateRect("orange"); orangeRect.AnchorTopBottom(marginRect, 50, 120); orangeRect.SetWidth(70);

var purpleRect = view.CreateRect("purple"); purpleRect.AnchorRightTopBottom(marginRect, 10, 50, 150); purpleRect.SetStarWidth(35);

blueRect.SetLeftAndOpposite(redRect, AnchorParam.Right, 10); orangeRect.SetLeftAndOpposite(blueRect, AnchorParam.Right, 10); purpleRect.SetLeftAndOpposite(orangeRect, AnchorParam.Right, 10);

host.PerformLayout();

DrawRect(marginRect, Color.Green); DrawRect(redRect, Color.Red); DrawRect(blueRect, Color.Blue); DrawRect(orangeRect, Color.Orange); DrawRect(purpleRect, Color.Purple);

void DrawRect(LayoutRect rect, Color color) { g.Transform = rect.Transform.Multiply(baseTransform); g.DrawRectangle(rect.AsRectF(), new Pen(color)); g.DrawString((string)rect.Tag, fmt, new PointF(3, 0)); }

g.Transform = baseTransform; doc.Save("doc3.pdf"); It saves a PDF document like this: This sample uses the helper methods to set multiple constraints at once. For example: redRect.AnchorLeftTopBottom(marginRect, 10, 50, 150); That's a short call to the following commands: redRect.SetAngle(marginRect, 0); redRect.SetLeft(marginRect, AnchorParam.Left, 10); redRect.SetTop(marginRect, AnchorParam.Top, 50); redRect.SetBottom(marginRect, AnchorParam.Bottom, -150); All available helper methods are listed below: Anchors a LayoutRect to the top and bottom sides and rotation angle of another LayoutRect or the owner LayoutView and sets zero width. Another thing to note in the previous example is using chained constraints: blueRect.SetLeftAndOpposite(redRect, AnchorParam.Right, 10); orangeRect.SetLeftAndOpposite(blueRect, AnchorParam.Right, 10); purpleRect.SetLeftAndOpposite(orangeRect, AnchorParam.Right, 10); We don’t need chained constraints when we create an explicit dependency between two parameters. For example, since the marginRect fully depends on the owner LayoutView, we can add a simple constraint based on marginRect for the left side of redRect: redRect.SetLeft(marginRect, AnchorParam.Left, 10); We cannot do the same with the left side of blueRect because the width of redRect is set in stars; that’s not a fixed width. The left sides of blue, orange, and purple rectangles, as well as the right sides of red, blue, and orange rectangles, are floating. For example, the position of the border between redRect and blueRect depends on both rectangle widths. We have to bind the left side of blueRect to the right side of redRect without specifying who depends on whom. The following constraint: blueRect.SetLeftAndOpposite(redRect, AnchorParam.Right, 10); It works as a couple of simple constraints: redRect.SetRight(blueRect, AnchorParam.Left, -10); blueRect.SetLeft(redRect, AnchorParam.Right, 10); Actually, we cannot use the simple constraints in that case because they imply the explicit dependencies. The chained constraints in the above sample can be replaced with their mirrored variants: redRect.SetRightAndOpposite(blueRect, AnchorParam.Left, -10); blueRect.SetRightAndOpposite(orangeRect, AnchorParam.Left, -10); orangeRect.SetRightAndOpposite(purpleRect, AnchorParam.Left, -10); Using SetRightAndOpposite for the left rectangle is equivalent to SetLeftAndOpposite for the right rectangle (the offset parameter changes its sign). Similar SetTopAndOpposite and SetBottomAndOpposite methods exist for assigned chained constraints in the vertical direction. Min and Max Position Constraints In the previous sample, we drew a series of rectangles with different levels of bottom sides. Now let’s draw another series at the 20 points below the first one. To make this task more interesting, the new series will consist of 5 rectangles placed between the horizontal centers of the red and purple rectangles. Each next rectangle in the new chain will be rotated 90 degrees relative to the previous one. All have the same star width (1) in the horizontal direction and a fixed distance (40 points) from the bottom of the marginRect. The full source code is below: using System.Drawing; using GrapeCity.Documents.Drawing; using GrapeCity.Documents.Layout; using GrapeCity.Documents.Pdf; using GrapeCity.Documents.Text;