Lists in Word Documents
- 8 minutes to read
The RichEditDocumentServer supports numbered, bulleted and multilevel lists. This topic describes the related API and shows how to create and format each list type.
List API
You need to use two types of objects to create and manage lists:
-
A list pattern that can be used to format multiple lists.
-
A list that takes settings from a pattern object and can restart or resume list numbering.
Each list object automatically creates nine pre-defined ListLevel objects which can be accessed by the index notation.
The image below shows the correspondence 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.
Document document = server.Document;
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];
//Set the left indent of the list
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();
Create a Numbered List
The code sample below creates a numbered list.
Document document = server.Document;
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 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();
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.NewStart property.
The code sample below shows how to create two lists based on the same pattern, but with different starting numbers.
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);
Create a Multilevel List
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 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 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 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)
{
//Specify the list index first:
pgf.ListIndex = 0;
pgf.ListLevel = pgf.Index;
}
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.
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();
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 a specific range to the ParagraphCollection.RemoveNumberingFromParagraphs method to exclude multiple paragraphs from the list.
//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);