ARTICLE UNDER CONSTRUCTION

Lists

Version 6.1.0

In this article

• Introduction
• Bulleted lists
• Numbered lists
• Mixed lists
• Indents

This article describes, how lists are added to a MigraDoc document.

Introduction

This article is placed in the "Contents" chapter, as you could regard lists as an own content type. But in MigraDoc, lists are actually simple paragraphs that take use of some specific format properties. We recommend to use styles to set those properties (see Document / Formatting for more information). The samples for the topics below are implemented using styles.

Bulleted lists

MigraDoc comes with three levels of bullet list types. Each of them has a unique kind of bullet. Those list types are defined in the ListType enum: BulletList1, BulletList2 and BulletList3. You can assign the list type to the ListType property of an ListInfo instance. Usually, you just access the ListInfo property of a ParagraphFormat (see Formats / Paragraph.

The next important action is to set the indents for the list (see Indents for more information).

The creation of a style for a list level could look like this:

// Style for list level 1
const string listLevel1StyleName = "ListLevel1";
style = document.Styles.AddStyle(listLevel1StyleName, StyleNames.List);
style.ParagraphFormat.ListInfo.ListType = ListType.BulletList1;
style.ParagraphFormat.ListInfo.NumberPosition = Unit.Zero;
style.ParagraphFormat.LeftIndent = Unit.FromCentimeter(0.5);

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

The indent properties and NumberPosition are of the type Unit (see Formats / Unit for more information).

Using a style, you simply have to assign it to a paragraph to make it a list (see Document / Formatting for more information).

MigraDoc only defines three levels of list types. To realize lists with more levels, you could reuse the ListType values in other styles for the deeper levels.

Numbered lists

Like bullet list types, MigraDoc comes with three levels of numbered list types. Each of them has a unique numbering format (numbers, letters, and roman numbers). Those list types are also defined in the ListType enum: NumberList1, NumberList2 and NumberList3.

The creation of a style for a list level of a numbered list looks similar to the one of a bulleted list:

// Style for list level 1
const string listLevel1StyleName = "ListLevel1";
style = document.Styles.AddStyle(listLevel1StyleName, StyleNames.List);
style.ParagraphFormat.ListInfo.ListType = ListType.NumberList1;
style.ParagraphFormat.ListInfo.NumberPosition = Unit.Zero;
style.ParagraphFormat.LeftIndent = Unit.FromCentimeter(0.5);

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

The indent properties and NumberPosition are of the type Unit (see Formats / Unit for more information).

Unlike in bullet lists, in numbered lists a number is incremented and added to a list item. In MigraDoc, for each number list type in ListType the number is incremented automatically each time a list item of this type is added. This number is also incremented when formatting a paragraph as a list item for a new list way after the last list was added. And also, after adding a list item of a lower level, a deeper level item is not considered as its child and will simply continue with the next number for that list type.

To avoid that, you have to set the ContinuePreviousList property in ListInfo to false. You could do this in special styles for the first list item of each list type that derive from the style for the appropriate list type:

// Special style for list level 1, first line
const string listLevel1Line1StyleName = "ListLevel1Line1";
style = document.Styles.AddStyle(listLevel1Line1StyleName, listLevel1StyleName);
style.ParagraphFormat.ListInfo.ContinuePreviousList = false;

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

Using those styles, you simply have to assign the right one to a paragraph to make it a list (see Document / Formatting for more information).

MigraDoc only defines three levels of numbered list types. Unlike for bulleted lists, there is a problem if you try to reuse a numbered list type in other styles for the deeper levels: The automatic increment of the number per list type. So, if you use a list type in multiple styles for multiple list levels, they will use the same counter. Due to this, it is currently not possible to set up more then three correctly working numbered list levels in MigraDoc.

Mixed lists

Of course, you can also mix list levels using bullets and numbers. Like for other numbered lists, you have to set the ContinuePreviousList property, when needed (see Numbered lists).

See MixedLists sample in PDFsharp.Sample repository. Show resulting PDF

Indents

As generally for paragraphs, the indent to the left page margin of a list item can be controlled by the LeftIndent property (see Formats / Paragraph).

The position of the bullet can be controlled in two ways. You can explicitly set the NumberPosition, which is a property of ListInfo, to set the position relatively to the left page margin. If NumberPosition is not set, the FirstLineIndent property value is used instead (see Formats / Paragraph). Here the position is relative to the left indent of the paragraph.

Between the bullet or number and the text a tab is implicitly inserted. Usually, the text will start with the left indent of the paragraph, but at least 5 millimeters after the bullet or number position. You can also specify a specific distance to the bullet or number position by adding a tab stop (see Formats / Tab stops).

Use of LeftIndent and NumberPosition, like done in Bulleted lists:

// Style for list level 1
const string listLevel1StyleName = "ListLevel1";
style = document.Styles.AddStyle(listLevel1StyleName, StyleNames.List);
style.ParagraphFormat.ListInfo.ListType = ListType.BulletList1;
style.ParagraphFormat.ListInfo.NumberPosition = Unit.Zero;
style.ParagraphFormat.LeftIndent = Unit.FromCentimeter(0.5);

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

Other examples using LeftIndent, FirstLineIndent and tab stops:

// Style for list level 1
const string listLevel1StyleName = "ListLevel1";
style = document.Styles.AddStyle(listLevel1StyleName, StyleNames.List);
style.ParagraphFormat.ListInfo.ListType = ListType.BulletList1;
style.ParagraphFormat.LeftIndent = Unit.FromCentimeter(0.5);
style.ParagraphFormat.FirstLineIndent = Unit.FromCentimeter(-0.5);
// The bullet is at the left margin (LeftIndent + FirstLineIndent).
// This equals NumberPosition = Unit.Zero.

// Style for list level 2
const string listLevel2StyleName = "ListLevel2";
style = document.Styles.AddStyle(listLevel2StyleName, StyleNames.List);
style.ParagraphFormat.ListInfo.ListType = ListType.BulletList2;
style.ParagraphFormat.LeftIndent = Unit.FromCentimeter(1);
style.ParagraphFormat.FirstLineIndent = Unit.FromCentimeter(-0.5);
// The bullet is 0.5 cm from left margin (LeftIndent + FirstLineIndent).
style.ParagraphFormat.TabStops.AddTabStop(Unit.FromCentimeter(1.5));
// The text after the bullet starts 1.5 cm from left margin
// (tab stop is independent of LeftIndent).

// Style for list level 3
const string listLevel3StyleName = "ListLevel3";
style = document.Styles.AddStyle(listLevel3StyleName, StyleNames.List);
style.ParagraphFormat.ListInfo.ListType = ListType.BulletList3;
style.ParagraphFormat.LeftIndent = Unit.FromCentimeter(2.5);
// As NumberPosition, FirstLineIndent and tab stops are not set, the default tab stops are used
// to position the text after the bullet. The default tab stop distance is 1.25 cm, so the next
// tab stop after 2.5 cm will be found at 3.75 cm.

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