Create Word Lists in C# and VB.NET
With lists, you can easily organize content in your documents hierarchically.
GemBox.Document supports creating bulleted, pictured, numbered, and/or alphabetized multi-level lists. You can format them up to 9 levels (from level 0 to level 8) using ListStyle.ListLevelFormats.
List items are Paragraph elements that have ListStyle applied to them. Typically by incrementing or decrementing the list item's level, you increase or decrease its indentation and thus promote or demote that list item in its hierarchy.
The following example shows how to create simple bulleted and numbered list styles and create list items with different levels.
using GemBox.Document;
class Program
{
static void Main()
{
// If using the Professional version, put your serial key below.
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
var document = new DocumentModel();
var section = new Section(document);
document.Sections.Add(section);
var blocks = section.Blocks;
// Create bullet list style.
ListStyle bulletList = new ListStyle(ListTemplateType.Bullet);
bulletList.ListLevelFormats[0].ParagraphFormat.NoSpaceBetweenParagraphsOfSameStyle = true;
bulletList.ListLevelFormats[0].CharacterFormat.FontColor = Color.Red;
// Create bullet list items.
blocks.Add(new Paragraph(document, "First item.")
{
ListFormat = { Style = bulletList }
});
blocks.Add(new Paragraph(document, "Second item.")
{
ListFormat = { Style = bulletList }
});
blocks.Add(new Paragraph(document, "Third item.")
{
ListFormat = { Style = bulletList }
});
blocks.Add(new Paragraph(document));
// Create number list style.
var numberList = new ListStyle(ListTemplateType.NumberWithDot);
// Create number list items.
blocks.Add(new Paragraph(document, "First item.")
{
ListFormat = { Style = numberList }
});
blocks.Add(new Paragraph(document, "Sub item 1. a.")
{
ListFormat = { Style = numberList, ListLevelNumber = 1 }
});
blocks.Add(new Paragraph(document, "Item below sub item 1. a.")
{
ListFormat = { Style = numberList, ListLevelNumber = 2 }
});
blocks.Add(new Paragraph(document, "Sub item 1. b.")
{
ListFormat = { Style = numberList, ListLevelNumber = 1 }
});
blocks.Add(new Paragraph(document, "Second item.")
{
ListFormat = { Style = numberList }
});
document.Save("Lists.%OutputFileType%");
}
}
Imports GemBox.Document
Module Program
Sub Main()
' If using the Professional version, put your serial key below.
ComponentInfo.SetLicense("FREE-LIMITED-KEY")
Dim document As New DocumentModel()
Dim section As New Section(document)
document.Sections.Add(section)
Dim blocks = section.Blocks
' Create bullet list style.
Dim bulletList As New ListStyle(ListTemplateType.Bullet)
bulletList.ListLevelFormats(0).ParagraphFormat.NoSpaceBetweenParagraphsOfSameStyle = True
bulletList.ListLevelFormats(0).CharacterFormat.FontColor = Color.Red
' Create bullet list items.
blocks.Add(New Paragraph(document, "First item.") With
{
.ListFormat = New ListFormat() With {.Style = bulletList}
})
blocks.Add(New Paragraph(document, "Second item.") With
{
.ListFormat = New ListFormat() With {.Style = bulletList}
})
blocks.Add(New Paragraph(document, "Third item.") With
{
.ListFormat = New ListFormat() With {.Style = bulletList}
})
blocks.Add(New Paragraph(document))
' Create number list style.
Dim numberList As New ListStyle(ListTemplateType.NumberWithDot)
' Create number list items.
blocks.Add(New Paragraph(document, "First item.") With
{
.ListFormat = New ListFormat() With {.Style = numberList}
})
blocks.Add(New Paragraph(document, "Sub item 1. a.") With
{
.ListFormat = New ListFormat() With {.Style = numberList, .ListLevelNumber = 1}
})
blocks.Add(New Paragraph(document, "Item below sub item 1. a.") With
{
.ListFormat = New ListFormat() With {.Style = numberList, .ListLevelNumber = 2}
})
blocks.Add(New Paragraph(document, "Sub item 1. b.") With
{
.ListFormat = New ListFormat() With {.Style = numberList, .ListLevelNumber = 1}
})
blocks.Add(New Paragraph(document, "Second item.") With
{
.ListFormat = New ListFormat() With {.Style = numberList}
})
document.Save("Lists.%OutputFileType%")
End Sub
End Module
You can easily customize the list items' appearance, in Word documents, as shown in the Define new bullets, numbers, and multilevel lists article. GemBox.Document enables you to specify the desired format and indentation for each list level individually, by using ListLevelFormat objects from the ListStyle.
The example below shows how you can create a customized multi-level numbered list.
using GemBox.Document;
using System.Linq;
class Program
{
static void Main()
{
// If using the Professional version, put your serial key below.
ComponentInfo.SetLicense("FREE-LIMITED-KEY");
int listItemsCount = %NumberOfListItems%;
var document = new DocumentModel();
var section = new Section(document);
document.Sections.Add(section);
// Create number list style.
var numberList = new ListStyle(ListTemplateType.NumberWithDot);
// Customize list level formats.
for (int level = 0; level < numberList.ListLevelFormats.Count; level++)
{
ListLevelFormat levelFormat = numberList.ListLevelFormats[level];
levelFormat.ParagraphFormat.NoSpaceBetweenParagraphsOfSameStyle = true;
levelFormat.Alignment = HorizontalAlignment.Left;
levelFormat.NumberStyle = NumberStyle.Decimal;
levelFormat.NumberPosition = 18 * level;
levelFormat.NumberFormat = string.Concat(Enumerable.Range(1, level + 1).Select(i => $"%{i}."));
}
// Create number list items.
for (int i = 0; i < listItemsCount; i++)
{
var paragraph = new Paragraph(document, "Lorem ipsum");
paragraph.ListFormat.Style = numberList;
paragraph.ListFormat.ListLevelNumber = i % 9;
section.Blocks.Add(paragraph);
}
document.Save("CustomizedList.%OutputFileType%");
}
}
Imports GemBox.Document
Imports System.Linq
Module Program
Sub Main()
' If using the Professional version, put your serial key below.
ComponentInfo.SetLicense("FREE-LIMITED-KEY")
Dim listItemsCount As Integer = %NumberOfListItems%
Dim document As New DocumentModel()
Dim section As New Section(document)
document.Sections.Add(section)
' Create number list style.
Dim numberList As New ListStyle(ListTemplateType.NumberWithDot)
' Customize list level formats.
For level = 0 To numberList.ListLevelFormats.Count - 1
Dim levelFormat As ListLevelFormat = numberList.ListLevelFormats(level)
levelFormat.ParagraphFormat.NoSpaceBetweenParagraphsOfSameStyle = True
levelFormat.Alignment = HorizontalAlignment.Left
levelFormat.NumberStyle = NumberStyle.Decimal
levelFormat.NumberPosition = 18 * level
levelFormat.NumberFormat = String.Concat(Enumerable.Range(1, level + 1).Select(Function(i) $"%{i}."))
Next
' Create number list items.
For i = 0 To listItemsCount - 1
Dim paragraph As New Paragraph(document, "Lorem ipsum")
paragraph.ListFormat.Style = numberList
paragraph.ListFormat.ListLevelNumber = i Mod 9
section.Blocks.Add(paragraph)
Next
document.Save("CustomizedList.%OutputFileType%")
End Sub
End Module
Often you'll want to combine your list with some ParagraphStyle, for instance, when creating numbered headings.
To do this, you can use the ListLevelFormat.AssociatedParagraphStyle property and assign your list's first level to the Heading 1 style, second level to the Heading 2 style, and so on. By using such styling you can assign just the Paragraph.ParagraphFormat.Style to the required Paragraph element, without having to set the Paragraph.ListFormat.Style as well.
In Word files, list items are automatically numbered: Paragraph elements don't contain the information about their number. They only have a reference to the ListStyle they're using.
GemBox.Document calculates the list numbers when exporting the document into PDF, XPS, or image format. Also, GemBox.Document provides a CalculateListItems method, from which you can find out the level numbers of any list item through Paragraph.ListItem.Numbers or retrieve the list item's numerical representation through Paragraph.ListItem.Inlines.
