ARTICLE UNDER CONSTRUCTION

Borders & line format

Version 6.1.0

In this article

This article describes, how the format of borders and lines is changed.

Introduction

Depending on the object type, a Borders or a LineFormat object is used to manage the border or line characteristics.

The Borders object can be set at the Borders property in ParagraphFormat objects (see Paragraph) as well as in Table, Column, Row and Cell objects (see Contents / Tables).

A line format can be set at the LineFormat property in objects derived from Shape. This includes TextFrame (see Contents / TextFrames) and Image (see Contents / Images) objects. Also, Chart objects and parts of it like TextArea, PlotArea, Series and Point, as well as Axis, GridLines and Legend objects provide that property (see Contents / Charts).

The LineFormat and Borders classes provide quite the same functionality and are therefore introduced together in this article. Additionally the Borders class allows to access single Border objects, that represent the edges of the border (see Single borders for more information).

Width & color

You can set the border or line width of an object using the Width property of its Borders or LineFormat object.

For objects using borders, like Table, it’s done like this:

// Set Borders width for all cells.
table.Borders.Width = Unit.FromPoint(5);

For objects using line format, like TextFrame, it’s done like this:

// Set LineFormat width.
textFrame.LineFormat.Width = Unit.FromPoint(5);

See full WidthAndColor sample in PDFsharp.Sample repository. Show resulting PDF

Width is a property of the type Unit (see Formats / Unit for more information).

You can set the border or line color of an object using the Color property of its Borders or LineFormat object.

For objects using borders, like Table, it’s done like this:

// Set Borders color for all cells.
table.Borders.Color = Colors.Blue;

For objects using line format, like TextFrame, it’s done like this:

// Set LineFormat color.
textFrame.LineFormat.Color = Colors.Blue;

See full WidthAndColor sample in PDFsharp.Sample repository. Show resulting PDF

Color is a property of the type Color (see Colors for more information).

Styles

When it comes to the border or line style, borders and line format are a bit different. They use different enums, which specify their own set of patterns.

For a border, the style is specified by the BorderStyle enum. This provides the patterns Single, Dot, DashSmallGap, DashLargeGap, DashDot and DashDotDot. You can additionally choose None to draw no border. The BorderStyle is set at the Style property.

// Set Borders style for all cells.
table.Borders.Style = BorderStyle.Dot;

See full Styles sample in PDFsharp.Sample repository. Show resulting PDF

For a line format, the style is specified by the DashStyle enum. This provides the patterns Solid, Dash, DashDot, DashDotDot and SquareDot. The DashStyle is set at the DashStyle property. The Style property of the LineFormat class is of the type LineStyle, which provides the value Single only. Setting this has no impact than changing the actual visibility of the line. Contrary to the Width, Color or Style properties, setting DashStyle has no impact on the actual visibility (see Visibility for more information).

// Set LineFormat style.
textFrame.LineFormat.DashStyle = DashStyle.Solid;

See full Styles sample in PDFsharp.Sample repository. Show resulting PDF

Visibility

As long as the Visible property is not set to false, the border or line format will be rendered, if at least the Width, Color or Style property is set. Due to this, you usually don’t have to set Visible to true. However, if setting only the DashStyle property of a line format, you have to.

If the Color value of a border or line format is missing, the line is considered as black. If the Style value is missing, the line is considered as single / solid. If the Width value is missing, borders defined with Borders objects will be 0.5 point and borders and lines defined with LineFormat will be 1 point thick.

When it comes to inheritance (see Document / Formatting for more information), you may want an object not to inherit the borders or line format of another one. In that case, you can simply set the Visible property to false for the object that inherits the borders:

// Set borders for all cells.
table.Borders.Width = Unit.FromPoint(3);
…
// Set borders visibility to false for cellA2.
cellA2.Borders.Visible = false;

See full Visibility sample in PDFsharp.Sample repository. Show resulting PDF

Width is a property of the type Unit (see Formats / Unit for more information).

Nesting

As a document is a tree of objects, you can nest objects with different borders or line formats. Especially when working with tables or text frames you should keep in mind that the Borders object you set on a ParagraphFormat instance, for example directly on the table or text frame, defines not the borders of the table or text frame itself. As the name states, the ParagraphFormat class is used to format paragraphs. So, the borders set on the ParagraphFormat instance are inherited to the contained paragraphs. The table, however, has its own borders and the text frame its own line format.

The following example demonstrates the difference:

// Set cell borders for cellA1.
cellA1.Borders.Width = Unit.FromPoint(5);

// Set paragraph borders for cellA1.
cellA1.Format.Borders.Width = Unit.FromPoint(1);

// Add paragraph to cellA1.
cellA1.AddParagraph("Text A1");

See full Nesting sample in PDFsharp.Sample repository. Show resulting PDF

Width is a property of the type Unit (see Formats / Unit for more information).

Border distance

Note

The distance properties are only considered for borders of paragraphs. For other objects, there are other concepts to achieve a distance to a border, like padding in tables (see Contents / Tables for more information).

To change the distance from a paragraph’s text to its borders, you can set a the distance properties. Those are DistanceFromTop, DistanceFromRight, DistanceFromBottom, DistanceFromLeft and Distance.

// Set border and distances for paragraph.
format.Borders.Width = Unit.FromPoint(1);
format.Borders.DistanceFromTop = Unit.FromCentimeter(0.5);
format.Borders.DistanceFromRight = Unit.FromCentimeter(1);
format.Borders.DistanceFromBottom = Unit.FromCentimeter(1.5);
format.Borders.DistanceFromLeft = Unit.FromCentimeter(2);

See full BorderDistance sample in PDFsharp.Sample repository. Show resulting PDF

Width and the distance properties are of the type Unit (see Unit for more information).

Using the Distance property, you can set the value for all the other distance properties.

// Set border and distance for paragraph.
format.Borders.Width = Unit.FromPoint(1);
format.Borders.Distance = Unit.FromCentimeter(2);

See full BorderDistance sample in PDFsharp.Sample repository. Show resulting PDF

Width and Distance are properties of the type Unit (see Formats / Unit for more information).

When the left or right distance is set, the border moves by that value. To compensate this growth of the border, you can set the indent properties for the paragraph to the appropriate values (see Paragraph for more information):

// Set border and distance for paragraph.
format.Borders.Width = Unit.FromPoint(1);
format.Borders.Distance = Unit.FromCentimeter(2);

// Set left and right indent to compensate growth.
format.LeftIndent = Unit.FromCentimeter(2);
format.RightIndent = Unit.FromCentimeter(2);

See full BorderDistance sample in PDFsharp.Sample repository. Show resulting PDF

Width and Distance are properties of the type Unit (see Formats / Unit for more information).

Single borders

With line formats you can just specify one format that is used for the whole line or border. For objects using a Borders object, you can control every single edge of the border separately.

You can access those Border objects using the Top, Right, Bottom and Left properties of the Borders object. Additionally, DiagonalDown and DiagonalUp can be used for diagonal borders.

The Border objects have basically the the same properties as the Borders object, so you can do quite the same with a single border like with the Borders object:

// Set single borders for cell.
cell.Borders.Top.Color = Colors.Cyan;
cell.Borders.Right.Color = Colors.Magenta;
cell.Borders.Bottom.Color = Colors.Yellow;
cell.Borders.Left.Color = Colors.Red;
cell.Borders.DiagonalDown.Color = Colors.Blue;
cell.Borders.DiagonalUp.Color = Colors.Lime;

See full SingleBorders sample in PDFsharp.Sample repository. Show resulting PDF

When rendering a border, MigraDoc will first take a look at the specific Border object. If a property is set, its value will be taken. If not, the property at the Borders object is asked. This way you can set general border formats at the Borders object and specific formats at the Border objects, while inheriting not set values from Borders:

// Set general borders for cell.
cell.Borders.Style = BorderStyle.Dot;

// Set a single border for cell.
cell.Borders.Right.Color = Colors.Magenta;

See full SingleBorders sample in PDFsharp.Sample repository. Show resulting PDF

Only for Border objects of diagonal borders, the Width of the Borders object will not be considered. It must be set explicitly at the Border object, as you surely don’t want diagonal borders to appear, when setting up a general border at the Borders object.

Borders in tables

If you want to set the borders of an area inside of a table, you may use the SetEdge method of the Table class. With this function, you just have to pass the indexes of the start column and row, the count of the columns and rows, as well as the desired Edge enum value and the border style, width and color:

// Set a border surrounding B2 to C3.
table.SetEdge(1, 1, 2, 2, Edge.Box, BorderStyle.Dot, Unit.FromPoint(3), Colors.Red);

See full SetEdgeMethod sample in PDFsharp.Sample repository. Show resulting PDF

The Edge enum values define, which borders of the given area shall be drawn:

Top, Right, Bottom and Left include only the respective borders at the edge of the area.

Horizontal and Vertical include only the respective inner borders of the area.

DiagonalDown and DiagonalUp include only the respective borders in all cells of the area.

Box includes only the borders surrounding the area.

Interior includes only the horizontal and vertical inner borders of the area.

Cross includes only both diagonal borders in all cells of the area.

If you define different borders for neighboring cells, you get the problem of colliding cell borders. In a table, the right border of a cell is the same border as the left border of its right neighbor. And the bottom border is the same as the top border of its bottom neighbor. But when formatting the table, you can set formats for all borders for each cell of a table. So how is the border format chosen, if different border formats collide? If one border is thicker than the other, this border with all it specified formats will be chosen. When two borders of the same width collide, the right border of the left cell is chosen for vertical borders and the bottom border of the upper cell chosen for horizontal borders.

The following example clarifies, how the actual used border format is chosen. For each cell, a format is specified for all borders.

// Add paragraph to first cell of row2.
var cellA2 = row2[0];
cellA2.AddParagraph("Text A2");

// Set cellA2 to a thin border.
cellA2.Borders.Width = Unit.FromPoint(1);
cellA2.Borders.Color = Colors.DarkGray;

// Add paragraph to second cell of row2.
var cellB2 = row2[1];
cellB2.AddParagraph("Text B2");

// Set cellB2 to a thin dotted light border.
cellB2.Borders.Width = Unit.FromPoint(1);
cellB2.Borders.Color = Colors.LightGray;
cellB2.Borders.Style = BorderStyle.Dot;

// Add paragraph to third cell of row2.
var cellC2 = row2[2];
cellC2.AddParagraph("Text C2");

// Set cellC2 to a thin border.
cellC2.Borders.Width = Unit.FromPoint(1);
cellC2.Borders.Color = Colors.DarkGray;

// Add paragraph to fourth cell of row2.
var cellD2 = row2[3];
cellD2.AddParagraph("Text D2");

// Set cellD2 to a thick dotted light border.
cellD2.Borders.Width = Unit.FromPoint(3);
cellD2.Borders.Color = Colors.LightGray;
cellD2.Borders.Style = BorderStyle.Dot;

See full CollidingBorders sample in PDFsharp.Sample repository. Show resulting PDF