Documents for Word, .NET Edition
Features / Lists
In This Topic
    Lists
    In This Topic

    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:

    1. Add a paragraph using the Add method.
    2. Access the list templates collection using ListTemplates property of the DocumentBase class.
    3. Add a sequence of paragraphs which will serve as the list items using Add method of the ListTemplateCollection class.
    4. Add paragraph part of the list using Add method of the paragraph collection for each item in the list.
    5. Apply list template to all the paragraphs by using ListFormat property of the Paragraph class.
      C#
      Copy Code
      //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");
      
    Back to Top

    Modify List

    To modify a list:

    1. Access the list templates collection using ListTemplates property of the DocumentBase class.
    2. Add a paragraph to the list using the Add method. This adds another item in the list.
    3. Apply list template to all the paragraph using ListFormat property of the Paragraph class.
    4. 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.
      C#
      Copy Code
      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");
    Back to Top

    Delete List

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

    C#
    Copy Code
    doc.Load("CreateList.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");

    Back to Top

        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:

        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

        C#
        Copy Code
        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.

        Back to Top

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