Lists

Lists can be used to format and arrange text in an organized way. The appearance of lists can be customized by defining numbered, bulleted, and multilevel lists.

GcWord provides 21 built-in list templates to create lists in a document using the ListTemplate class. This class represents a list template that defines the format of list including the type of bullet or numbering style applied to the list. The Add method of the ListTemplateCollection class allows you to define and add list template to the collection of list templates in a document. The list templates are applied to a sequence of paragraphs to convert them to a list, where each paragraph serves as the list item. GcWord allows you to apply list formatting to the paragraphs using properties of the ListFormat class. It also provides ListLevel class which represents single list level for bulleted or numbered list. In addition, you can use BuiltInListTemplateId enumeration to use predefined list templates and NumberStyle enumeration to specify the number style for a list.

Nested list in a Word document

Create List

To create list in a Word document:

Add a paragraph using the Add method.
Access the list templates collection using ListTemplates property of the DocumentBase class.
Add a sequence of paragraphs which will serve as the list items using Add method of the ListTemplateCollection class.
Add paragraph part of the list using Add method of the paragraph collection for each item in the list.

Apply list template to all the paragraphs by using ListFormat property of the Paragraph class.

//Define a ListTemplate for level 1 list items:
ListTemplate myListTemplate = doc.ListTemplates.Add(
        BuiltInListTemplateId.BulletDefault, "myListTemplate");

//Define list templates for level 2 list items
ListTemplate mySubList1Template = doc.ListTemplates.Add(
        BuiltInListTemplateId.NumberUppercaseRomanDot, "mySubList1Template");
ListTemplate mySubList2Template = doc.ListTemplates.Add(
        BuiltInListTemplateId.NumberUppercaseRomanDot, "mySubList2Template");
ListTemplate mySubList3Template = doc.ListTemplates.Add(
        BuiltInListTemplateId.NumberUppercaseRomanDot, "mySubList3Template");

ParagraphCollection pars = doc.Body.Sections.First.GetRange().Paragraphs;
pars.Add("The list of bullets:");

//Add list items using Paragraph and set their list template and level number:
Paragraph p1 = pars.Add("Bullet item 1");
p1.ListFormat.Template = myListTemplate;
p1.ListFormat.LevelNumber = 1;
Paragraph p1s1 = pars.Add("Numbered item 1: Nested item 1");
p1s1.ListFormat.Template = mySubList1Template;
p1s1.ListFormat.LevelNumber = 2;

Paragraph p2 = pars.Add("Bullet item 2");
p2.ListFormat.Template = myListTemplate;
p2.ListFormat.LevelNumber = 1;
Paragraph p2s1 = pars.Add("Numbered item 2: Nested item 1");
p2s1.ListFormat.Template = mySubList2Template;
p2s1.ListFormat.LevelNumber = 2;
Paragraph p2s2 = pars.Add("Numbered item 2: Nested item 2");
p2s2.ListFormat.Template = mySubList2Template;
p2s2.ListFormat.LevelNumber = 2;

Paragraph p3 = pars.Add("Bullet item 3");
p3.ListFormat.Template = myListTemplate;
p3.ListFormat.LevelNumber = 1;
Paragraph p3s1 = pars.Add("Numbered item 3: Nested item 1");
p3s1.ListFormat.Template = mySubList3Template;
p3s1.ListFormat.LevelNumber = 2;

//Save the document
doc.Save("CreateList.docx");

Modify List

To modify a list:

Access the list templates collection using ListTemplates property of the DocumentBase class.
Add a paragraph to the list using the Add method. This adds another item in the list.
Apply list template to all the paragraph using ListFormat property of the Paragraph class.

Set the list level for the new paragraph, if required. For example, set the level number to 2, so that it appears as a nested item in the list.

doc.Load("List.docx");

//Access the list template collection
ListTemplate myListTemplate = doc.ListTemplates["myListTemplate"];

//Add a paragraph to the list
Paragraph p4=doc.Body.Sections.First.GetRange().Paragraphs.Add("Bullet item 4");
p4.ListFormat.Template = myListTemplate;

//Set the bullet level
p4.ListFormat.LevelNumber = 2;

//Save the document
doc.Save("ModifyList.docx");

Delete List

To delete a list, remove list formatting from the last paragraph of the document using ClearFormatting method of the ListFormat class.

doc.Load("List.docx");

//Access the list template collection
ListTemplate myListTemplate = doc.ListTemplates["myListTemplate"];

//Remove list formatting from all the paragraphs serving as the list items
for (int p = 1; p < doc.Body.Paragraphs.Count; p++)
    doc.Body.Paragraphs[p].ListFormat.ClearFormatting();

//Save the document
doc.Save("DeleteList.docx");

Restart List

You can also restart a list by using the RestartList method of Paragraph class. The method provides an optional startNumberingValue parameter which defines the new numerical value to be used as the restart value in the list. If the list is alphabetical, this numerical value defines the index of the letter in the alphabet to be used as the restart value in the list. For example, if the numerical value is 8:

A numbered list will restart from 8
An alphabetical list will restart from 'h' (8th letter)

If startNumberingValue parameter is null, the list will restart from the first number or first letter, whichever is applicable.

The screenshot below shows a document (List.docx) that contains a multi-level list, and the same document after being updated using the following code:

Restart aplhabetical list in GcWord

var doc = new GcWordDocument();
//Load document containing list
doc.Load("List.docx");
//Restart 5th paragraph of the list and switch its list element to 8th alphabet letter (h)
doc.Body.Paragraphs[4].RestartList(8);

//Save the document
doc.Save("RestartList.docx");

Note: The following behavior in GcWord differs from MS Word:
GcWord allows you to restart last items of lists unlike MS Word.
GcWord does not allow you to restart single-level lists as multilevel-lists unlike MS Word.

For more information on how to implement lists using GcWord, see GcWord sample browser.