Tab stops

Version 6.1.0

In this article

This article describes how to manage tab stops of a paragraph.

Introduction

With tab stops, you can easily align data in a consistent scheme. You can simply add tab stops to a ParagraphFormat object. This way you can define them directly for a paragraph or globally in a style (see Document / Formatting for more information).

To access a ParagraphFormat object, check Paragraph.

Using tab stops, you can also extend data alignment possibilities inside tables (see Contents / Tables for more information).

Position

When adding a tab stop to a ParagraphFormat object, you have to define at least the position:

format.AddTabStop(Unit.FromCentimeter(1));

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

The position parameter of AddTabStop is of type Unit (see Unit for more information).

Alignment

A tab stop created without a TabAlignment enum value defined will be Left aligned by default. You can also create Center, Right and Decimal aligned tab stops:

format.AddTabStop(Unit.FromCentimeter(6), TabAlignment.Right);
format.AddTabStop(Unit.FromCentimeter(8), TabAlignment.Decimal);
format.AddTabStop(Unit.FromCentimeter(11), TabAlignment.Center);

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

The position parameter of AddTabStop is of type Unit (see Unit for more information).

You can add a paragraph that contains tabs to move to the defined tab stops. Write \t or use the AddTab function to add tabs.

section.AddParagraph("1.\tJohn Doe\t183\t85.3\tUSA");

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

The text placed at a Decimal aligned tab stop will be aligned at the decimal separator. Beware that decimal separators vary between cultures. If the code creating your document may be executed on machines with different cultures, you should define a culture to be used for your document. That culture should match the decimal separators used in the values added by your code. To change the culture of your document, check Document / Document settings. Alternatively, you may ensure that all data is rendered using the decimal separator of the CurrentCulture object.

Leader

The leader defines if the space before a tab stop is filled with separators.

A tab stop created without a TabLeader enum value defined will use the Spaces value by default. Hence the space before it will not be filled with any separator.

You can define the leader as a parameter in the AddTabStop function:

format.AddTabStop(Unit.FromCentimeter(10), TabLeader.Dots);

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

The position parameter of AddTabStop is of type Unit (see Unit for more information).

The TabLeader enum defines the following values to fill the space with separators:

Dots insert dots as leader.

Dashes insert dashes as leader.

Lines insert underscores as leader. Depending on the used font, they will appear as one line or as a dashed line.

MiddleDot insert middle dots as leader. So, this appears similar to Dots, but with the dots in the middle of the line.

The value Heavy actually is treated exactly like Lines. It exists as equivalent to the entry in Microsoft Word’s Automation model. Word and the Automation model are used as reference for MigraDoc. wdTabLeaderLines and wdTabLeaderHeavy also produce the same result there, while there is only an option for wdTabLeaderLines in Word’s graphical user interface.

Inheritance

For tab stops, inheritance works quite the same as in general (see Document / Formatting). This way each single tab stop will be inherited, if you inherit from a style or if you add an object, that inherits the ParagraphFormat object values from its parent. If you for example inherit from a style that has tab stops defined, all tab stops will be inherited.

Of course it is no problem to add an additional tab stop to the style or to the object which inherits the ParagraphFormat object values.

If you want to break inheritance for a specific tab stop, call the RemoveTabStop function and provide the position, where no tab stop shall be inherited:

format.RemoveTabStop(Unit.FromCentimeter(1));

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

The position parameter of RemoveTabStop is of type Unit (see Unit for more information).

In some case it might be easier to add all tab stops from scratch than removing and adding single tab stops. To achieve this, call the ClearAll function before defining the tab stops:

// Clear all inherited TabStops.
format.ClearAll();
// Create TabStops from scratch.
format.AddTabStop(Unit.FromCentimeter(1.5));
format.AddTabStop(Unit.FromCentimeter(2.5));

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

The position parameter of AddTabStop is of type Unit (see Unit for more information).

Default tab stops

If no tab stops are defined or inherited, the DefaultTabStop property of the Document instance defines the default grid to be used to place tabs at. Also, tabs that are inserted after the last defined or inherited tab stop will be placed at this default grid.

If the DefaultTabStop property is not set, a default tab stop distance of 1.25 centimeters is used.

The following example shows how the default tab stop distance is used to place tab stops - for a paragraph without tab stops and for a paragraph with two defined tab stops:

const string tabStopStyleName = "tabStopStyle";

// Set tab stops for tabStopStyle.
style = document.Styles.AddStyle(tabStopStyleName, StyleNames.Normal);
var format = style.ParagraphFormat;
format.AddTabStop(Unit.FromCentimeter(3));
format.AddTabStop(Unit.FromCentimeter(4));

// Add a section to the document.
var section = document.AddSection();

section.AddParagraph("Default tab stops (1.25 cm):\n" +
					 "\tA\tB\tC\tD\tE\tF\n" +
					 "\t1.25\t2.5\t3.75\t5\t6.25\t7.5");

section.AddParagraph("Defined Tab stops A (3 cm) and B (4 cm), " +
					 "then default tab stops (on 1.25 cm grid):\n" +
					 "\tA\tB\tC\tD\tE\tF\n" + 
					 "\t3\t4\t5\t6.25\t7.5\t8.75", tabStopStyleName);

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

The position parameter of AddTabStop is of type Unit (see Unit for more information).

The next example is almost the same, except that the DefaultTabStop property is set to 1.75 centimeters and the values in the paragraphs are adjusted:

// Set default tab stop width.
document.DefaultTabStop = Unit.FromCentimeter(1.75);

const string tabStopStyleName = "tabStopStyle";

// Set tab stops for tabStopStyle.
style = document.Styles.AddStyle(tabStopStyleName, StyleNames.Normal);
var format = style.ParagraphFormat;
format.AddTabStop(Unit.FromCentimeter(3));
format.AddTabStop(Unit.FromCentimeter(4));

// Add a section to the document.
var section = document.AddSection();

section.AddParagraph("Default tab stops (1.25 cm):\n" +
					 "\tA\tB\tC\tD\tE\tF\n" +
					 "\t1.75\t3.5\t5.25\t7\t8.75\t10.5");

section.AddParagraph("Defined Tab stops A (3 cm) and B (4 cm), " +
					 "then default tab stops (on 1.75 cm grid):\n" +
					 "\tA\tB\tC\tD\tE\tF\n" +
					 "\t3\t4\t5.25\t7\t8.75\t10.5", tabStopStyleName);

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

The DefaultTabStop property and the position parameter of AddTabStop are of type Unit (see Unit for more information).