Lists in Rich Text Documents
- 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:
-
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 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.
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();
Create a Numbered List
The code sample below creates a numbered list.
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();
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.
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 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();
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 the target 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);