Lists in Rich Text Documents

Dec 12, 2022
8 minutes to read

The RichEditControl supports numbered, bulleted and multilevel lists. This topic shows how to create and format each list type in code and from the User Interface.

Lists in the User Interface

End users can use the Paragraph group’s items on the Home ribbon tab to include or exclude paragraphs from the list.

Right-click the text in the list and select Bullets and Numbering from the context menu to invoke the Bullets and Numbering Dialog. The dialog allows end users to view and customize styles for each list type.

Tip

You can restrict end users from creating and customizing lists. Set the DocumentCapabilitiesOptions.Numbering property to Disabled or Hidden to disable or hide the corresponding commands in the Ribbon UI and the pop-up menu

List API

You need to use two types of objects to create and manage lists:

Each list object automatically creates nine pre-defined ListLevel objects which can be accessed by the index notation.

The image below shows the connection between AbstractNumberingList and NumberingList objects, and document paragraphs.

The table below lists API used to create lists in code.

API	Description
Document.AbstractNumberingLists	Provides access to the collection of AbstractNumberingList objects.
AbstractNumberingListCollection.Add	Creates a new AbstractNumberingList and adds it to the collection.
NumberingListBase.NumberingType	Specifies the list’s type (determined by the NumberingType enumerator).
NumberingListBase.Levels	Obtains the collection of list levels. Any list type has 9 levels.
ListLevelProperties.DisplayFormatString	Specifies a symbol used to mark the list item.
Document.NumberingLists	Retrieves the collection of NumberingList objects.
NumberingListCollection.Add	Adds a new NumberingList object based on the AbstractNumberingList instance.
ParagraphCollection.AddParagraphToList	Adds a paragraph to the specified list and level.
ParagraphCollection.AddParagraphsToList	Adds a range of paragraphs to the specified list and level.

Create a Bulleted List

The code sample below creates a bulleted list and applies it to paragraphs.

View Example

List.cs
List.vb

csharp

document.BeginUpdate();

// Create a new list pattern object
AbstractNumberingList list = document.AbstractNumberingLists.Add();

//Specify the list's type
list.NumberingType = NumberingType.Bullet;
ListLevel level = list.Levels[0];
level.ParagraphProperties.LeftIndent = 100;

//Specify the bullets' format
//Without this step, the list is considered as numbered
level.DisplayFormatString = "\u00B7";
level.CharacterProperties.FontName = "Symbol";

//Create a new list based on the specific pattern
NumberingList bulletedList = document.NumberingLists.Add(0);

// Add paragraphs to the list
ParagraphCollection paragraphs = document.Paragraphs;
paragraphs.AddParagraphsToList(document.Range, bulletedList, 0);

document.EndUpdate();

document.BeginUpdate()

' Create a new list pattern objects
Dim list As AbstractNumberingList = document.AbstractNumberingLists.Add()

' Specify the list's type
list.NumberingType = NumberingType.Bullet
Dim level As ListLevel = list.Levels(0)
level.ParagraphProperties.LeftIndent = 100

' Specify the bullet's format
' Without this step, the list is considered as numbered
level.DisplayFormatString = "·"
level.CharacterProperties.FontName = "Symbol"

' Create a new list based on the specific pattern
Dim bulletedList as NumberingList = document.NumberingLists.Add(0)

' Add paragraphs to the list
Dim paragraphs As ParagraphCollection = document.Paragraphs
paragraphs.AddParagraphsToList(document.Range, bulletedList, 0)
document.EndUpdate()

Create a Numbered List

The code sample below creates a numbered list.

List.cs
List.vb

csharp

document.BeginUpdate();

//Create a new pattern object
AbstractNumberingList abstractListNumberingRoman = document.AbstractNumberingLists.Add();

//Specify the list's type
abstractListNumberingRoman.NumberingType = NumberingType.Simple;

//Define the first level's properties
ListLevel level = abstractListNumberingRoman.Levels[0];
level.ParagraphProperties.LeftIndent = 150;

// Align list level with the surrounding text
level.ParagraphProperties.FirstLineIndentType = ParagraphFirstLineIndent.Hanging;
level.ParagraphProperties.FirstLineIndent = 75;
level.Start = 1;

//Specify the roman format
level.NumberingFormat = NumberingFormat.LowerRoman;
level.DisplayFormatString = "{0}.";

//Create a new list based on the specific pattern
NumberingList numberingList = document.NumberingLists.Add(0);

document.EndUpdate();

document.BeginUpdate();
ParagraphCollection paragraphs = document.Paragraphs;
//Add paragraphs to the list
paragraphs.AddParagraphsToList(document.Range, numberingList, 0);
document.EndUpdate();

document.BeginUpdate()

'Create a new pattern object
Dim abstractListNumberingRoman As AbstractNumberingList = document.AbstractNumberingLists.Add()

'Specify the list's type
abstractListNumberingRoman.NumberingType = NumberingType.Simple

'Define the first level's properties
Dim level As ListLevel = abstractListNumberingRoman.Levels(0)
level.ParagraphProperties.LeftIndent = 150

' Align list level with the surrounding text
level.ParagraphProperties.FirstLineIndentType = ParagraphFirstLineIndent.Hanging
level.ParagraphProperties.FirstLineIndent = 75
level.Start = 1
level.NumberingFormat = NumberingFormat.LowerRoman
level.DisplayFormatString = "{0}."

'Create a new list based on the specific pattern
Dim numberingList As NumberingList = document.NumberingLists.Add(0)
document.EndUpdate()

document.BeginUpdate()
Dim paragraphs As ParagraphCollection = document.Paragraphs

'Add paragraphs to the list
paragraphs.AddParagraphsToList(document.Range, numberingList, 0)
document.EndUpdate()

Reset the List Item’s Numeration

You can create two NumberingList objects based on the same AbstractNumberingList instance and override one of the list’s starting number.

Call the OverrideListLevel.SetOverrideStart method for the list level and specify the OverrideListLevel.OverrideStart property.

The code sample below shows how to create two lists based on the same pattern, but with different starting numbers.

C#
VB.NET

csharp

document.BeginUpdate();

// Create a new list pattern object
AbstractNumberingList list = document.AbstractNumberingLists.Add();

// Specify the list's type
list.NumberingType = NumberingType.Simple;

ListLevel level = list.Levels[0];
level.Start = 1;
level.NumberingFormat = NumberingFormat.UpperRoman;
level.DisplayFormatString = "{0}.";

// Create new list objects based on the specified pattern
NumberingList bulletedList = document.NumberingLists.Add(0);
NumberingList overrideList = document.NumberingLists.Add(0);

// Change the start number for the second list
overrideList.Levels[0].SetOverrideStart(true);
overrideList.Levels[0].NewStart = 3;
document.EndUpdate();

// Add paragraphs from the target range to the first list
DocumentRange range = document.CreateRange(document.Paragraphs[0].Range.Start,document.Paragraphs[3].Range.End.ToInt() - document.Paragraphs[0].Range.Start.ToInt());
document.Paragraphs.AddParagraphsToList(range, bulletedList,0);

// Add paragraphs from the target range to the second list
DocumentRange range2 = document.CreateRange(document.Paragraphs[5].Range.Start, document.Paragraphs[7].Range.End.ToInt() - document.Paragraphs[4].Range.Start.ToInt());
document.Paragraphs.AddParagraphsToList(range2, overrideList, 0);

document.BeginUpdate()
' Create a new list pattern object
Dim list As AbstractNumberingList = document.AbstractNumberingLists.Add()

'Specify the list's type
list.NumberingType = NumberingType.Simple

Dim level As ListLevel = list.Levels(0)
level.Start = 1
level.NumberingFormat = NumberingFormat.UpperRoman
level.DisplayFormatString = "{0}."

' Create new list objects based on the specified pattern
Dim bulletedList As NumberingList = document.NumberingLists.Add(0)
Dim overrideList As NumberingList = document.NumberingLists.Add(0)

' Change the start number for the second list
overrideList.Levels(0).SetOverrideStart(True)
overrideList.Levels(0).NewStart = 3
document.EndUpdate()

'Add paragraphs from the target range to the first list
Dim range As DocumentRange = document.CreateRange(document.Paragraphs(0).Range.Start,document.Paragraphs(3).Range.End.ToInt() - document.Paragraphs(0).Range.Start.ToInt())
document.Paragraphs.AddParagraphsToList(range, bulletedList,0)

'Add paragraphs from the target range to the second list
Dim range2 As DocumentRange = document.CreateRange(document.Paragraphs(5).Range.Start, document.Paragraphs(7).Range.End.ToInt() - document.Paragraphs(4).Range.Start.ToInt())
document.Paragraphs.AddParagraphsToList(range2, overrideList, 0)

csharp

document.BeginUpdate();

//Create a new pattern object
AbstractNumberingList list = document.AbstractNumberingLists.Add();

//Specify the list's type
list.NumberingType = NumberingType.MultiLevel;

//Specify parameters for each list level
ListLevel level = list.Levels[0];
level.ParagraphProperties.LeftIndent = 105;

// Align list level with the surrounding text
level.ParagraphProperties.FirstLineIndentType = ParagraphFirstLineIndent.Hanging;
level.ParagraphProperties.FirstLineIndent = 55;
level.Start = 1;
level.NumberingFormat = NumberingFormat.UpperRoman;
level.DisplayFormatString = "{0}";

level = list.Levels[1];
level.ParagraphProperties.LeftIndent = 125;

// Align list level with the surrounding text
level.ParagraphProperties.FirstLineIndentType = ParagraphFirstLineIndent.Hanging;
level.ParagraphProperties.FirstLineIndent = 65;
level.Start = 1;
level.NumberingFormat = NumberingFormat.LowerRoman;
level.DisplayFormatString = "{1})";

level = list.Levels[2];
level.ParagraphProperties.LeftIndent = 145;

// Align list level with the surrounding text
level.ParagraphProperties.FirstLineIndentType = ParagraphFirstLineIndent.Hanging;
level.ParagraphProperties.FirstLineIndent = 75;
level.Start = 1;
level.NumberingFormat = NumberingFormat.LowerLetter;
level.DisplayFormatString = "{2}.";

//Create a new list object based on the specified pattern
document.NumberingLists.Add(0);
document.EndUpdate();

//Convert all paragraphs to list items
document.BeginUpdate();
ParagraphCollection paragraphs = document.Paragraphs;

foreach (Paragraph pgf in paragraphs)
{
    pgf.ListIndex = 0;
    pgf.ListLevel = pgf.Index;
}

document.EndUpdate();

document.BeginUpdate()

'Create a new list pattern object
Dim list As AbstractNumberingList = document.AbstractNumberingLists.Add()

'Specify the list's type
list.NumberingType = NumberingType.MultiLevel

'Specify parameters for each level
Dim level As ListLevel = list.Levels(0)
level.ParagraphProperties.LeftIndent = 105

' Align list level with the surrounding text
level.ParagraphProperties.FirstLineIndentType = ParagraphFirstLineIndent.Hanging
level.ParagraphProperties.FirstLineIndent = 55
level.Start = 1
level.NumberingFormat = NumberingFormat.UpperRoman
level.DisplayFormatString = "{0}"

level = list.Levels(1)
level.ParagraphProperties.LeftIndent = 125

' Align list level with the surrounding text
level.ParagraphProperties.FirstLineIndentType = ParagraphFirstLineIndent.Hanging
level.ParagraphProperties.FirstLineIndent = 65
level.Start = 1
level.NumberingFormat = NumberingFormat.LowerRoman
level.DisplayFormatString = "{1})"

level = list.Levels(2)
level.ParagraphProperties.LeftIndent = 145

' Align list level with the surrounding text
level.ParagraphProperties.FirstLineIndentType = ParagraphFirstLineIndent.Hanging
level.ParagraphProperties.FirstLineIndent = 75
level.Start = 1
level.NumberingFormat = NumberingFormat.LowerLetter
level.DisplayFormatString = "{2}."

'Create a new list object based on the specified pattern
document.NumberingLists.Add(0)
document.EndUpdate()

document.BeginUpdate()

' Apply numbering to a list
Dim paragraphs As ParagraphCollection = document.Paragraphs

For Each pgf As Paragraph In paragraphs
    pgf.ListIndex = 0
    pgf.ListLevel = pgf.Index
Next

document.EndUpdate()

Change List Marker’s Formatting

The ListLevel.CharacterProperties and ListLevel.ParagraphProperties properties provide access to the level marker’s format options. The code sample below shows how to change the indent and the font color for the first list level so it appears as follows.

C#
VB.NET

csharp

document.BeginUpdate();

// Create a new list pattern object
AbstractNumberingList list = document.AbstractNumberingLists.Add();

//Specify the list type
list.NumberingType = NumberingType.Simple;

ListLevel level = list.Levels[0];
level.Start = 1;

//Define paragraph and character properties for the level's marker
level.NumberingFormat = NumberingFormat.UpperRoman;
level.ParagraphProperties.Alignment = ParagraphAlignment.Center;
level.CharacterProperties.ForeColor = System.Drawing.Color.Red;
level.DisplayFormatString = "{0}.";

ListLevel level1 = list.Levels[1];
level1.ParagraphProperties.Alignment = ParagraphAlignment.Left;
level1.CharacterProperties.ForeColor = System.Drawing.Color.DarkOrange;

// Create a new list based on the given pattern
NumberingList bulletedList = document.NumberingLists.Add(0);

document.EndUpdate();

document.BeginUpdate()

'Create a new list pattern object
Dim list As AbstractNumberingList = document.AbstractNumberingLists.Add()

'Specify the list type
list.NumberingType = NumberingType.Simple
Dim level As ListLevel = list.Levels(0)
level.Start = 1

'Define paragraph and character properties for the level's marker
level.NumberingFormat = NumberingFormat.UpperRoman
level.ParagraphProperties.Alignment = ParagraphAlignment.Center
level.CharacterProperties.ForeColor = System.Drawing.Color.Red
level.DisplayFormatString = "{0}."
Dim level1 As ListLevel = list.Levels(1)
level1.ParagraphProperties.Alignment = ParagraphAlignment.Left
level1.CharacterProperties.ForeColor = System.Drawing.Color.DarkOrange

'Create a new list based on the given pattern
Dim bulletedList As NumberingList = document.NumberingLists.Add(0)
document.EndUpdate()

Note

The ListLevel.CharacterProperties and ListLevel.ParagraphProperties options do not change the format of the level’s content. Call the SubDocument.BeginUpdateParagraphs or SubDocument.BeginUpdateCharacters method to change the text formatting. Refer to the Text Formatting topic for examples on how to format text.

Exclude a Paragraph from the List

Set the Paragraph.ListIndex property to -1 or call the ParagraphCollection.RemoveNumberingFromParagraph method to exclude paragraphs from the list. Pass the target range to the ParagraphCollection.RemoveNumberingFromParagraphs method to exclude multiple paragraphs from the list.

C#
VB.NET

csharp

//Remove numbering from one paragraph
paragraphs.RemoveNumberingFromParagraph(paragraphs[3]);

//Remove numbering from the range of paragraphs
DocumentRange range = document.CreateRange(paragraphs[4].Range.Start,paragraphs[paragraphs.Count-1].Range.End.ToInt()-paragraphs[4].Range.Start.ToInt());
paragraphs.RemoveNumberingFromParagraphs(range);

'Remove numbering from one paragraph
paragraphs.RemoveNumberingFromParagraph(paragraphs(3))

'Remove numbering from the range of paragraphs
Dim range As DocumentRange = document.CreateRange(paragraphs(4).Range.Start, paragraphs(paragraphs.Count - 1).Range.[End].ToInt() - paragraphs(4).Range.Start.ToInt())
paragraphs.RemoveNumberingFromParagraphs(range)