Skip to main content

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.

Lists-Ribbon

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.

RTEBulletsAndNumberingBulletedTab

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:

  • AbstractNumberingList

    A list pattern that can be used to format multiple lists.

  • NumberingList

    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.

Diagram

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.

IMAGE

View Example

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.

IMAGE

View Example

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.

IMAGE

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

IMAGE

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.

IMAGE

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);