ListCollection Class

Stores and manages formatting of bulleted and numbered lists used in a document.

Inheritance Hierarchy

SystemObject
Aspose.Words.ListsListCollection

Namespace: Aspose.Words.Lists
Assembly: Aspose.Words (in Aspose.Words.dll) Version: 20.7.0

Syntax

public class ListCollection : IEnumerable<List>, 
	IEnumerable

Public Class ListCollection
	Implements IEnumerable(Of List), IEnumerable

public ref class ListCollection : IEnumerable<List^>, 
	IEnumerable

type ListCollection =  
    class
        interface IEnumerable<List>
        interface IEnumerable
    end

The ListCollection type exposes the following members.

Properties

	Name	Description
	Count	Gets the count of numbered and bulleted lists in the document.
	Document	Gets the owner document.
	Item	Gets a list by index.

Methods

	Name	Description
	Add(ListTemplate)	Creates a new list based on a predefined template and adds it to the collection of lists in the document.
	Add(Style)	Creates a new list that references a list style and adds it to the collection of lists in the document.
	AddCopy	Creates a new list by copying the specified list and adding it to the collection of lists in the document.
	Equals	(Inherited from Object.)
	GetEnumerator	Gets the enumerator object that will enumerate lists in the document.
	GetHashCode	(Inherited from Object.)
	GetListByListId	Gets a list by a list identifier.
	GetType	(Inherited from Object.)
	ToString	(Inherited from Object.)

Remarks

A list in a Microsoft Word document is a set of list formatting properties. The formatting of the lists is stored in the ListCollection collection separately from the paragraphs of text.

You do not create objects of this class. There is always only one ListCollection object per document and it is accessible via the Lists property.

To create a new list based on a predefined list template or based on a list style, use the Add(Style) method.

To create a new list with formatting identical to an existing list, use the AddCopy(List) method.

To make a paragraph bulleted or numbered, you need to apply list formatting to a paragraph by assigning a List object to the List property of ListFormat.

To remove list formatting from a paragraph, use the RemoveNumbers method.

If you know a bit about WordprocessingML, then you might know it defines separate concepts for "list" and "list definition". This exactly corresponds to how list formatting is stored in a Microsoft Word document at the low level. List definition is like a "schema" and list is like an instance of a list definition.

To simplify programming model, Aspose.Words hides the distinction between list and list definition in much the same way like Microsoft Word hides this in its user interface. This allows you to concentrate more on how you want your document to look like, rather than building low-level objects to satisfy requirements of the Microsoft Word file format.

It is not possible to delete lists once they are created in the current version of Aspose.Words. This is similar to Microsoft Word where user does not have explicit control over list definitions.

Examples

Shows how to specify list level number when building a list using DocumentBuilder.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Create a numbered list based on one of the Microsoft Word list templates and
// apply it to the current paragraph in the document builder
builder.ListFormat.List = doc.Lists.Add(ListTemplate.NumberArabicDot);

// Insert text at each of the 9 indent levels
for (int i = 0; i < 9; i++)
{
    builder.ListFormat.ListLevelNumber = i;
    builder.Writeln("Level " + i);
}

// Create a bulleted list based on one of the Microsoft Word list templates
// and apply it to the current paragraph in the document builder
builder.ListFormat.List = doc.Lists.Add(ListTemplate.BulletDiamonds);

for (int i = 0; i < 9; i++)
{
    builder.ListFormat.ListLevelNumber = i;
    builder.Writeln("Level " + i);
}

// This is a way to stop list formatting
builder.ListFormat.List = null;

doc.Save(ArtifactsDir + "Lists.SpecifyListLevel.docx");

Shows how to enumerate through all lists defined in one document and creates a sample of those lists in another document.

public void PrintOutAllLists()
{
    // Open a document that contains lists
    Document srcDoc = new Document(MyDir + "Rendering.docx");

    // This will be the sample document we product
    Document dstDoc = new Document();
    DocumentBuilder builder = new DocumentBuilder(dstDoc);

    foreach (List srcList in srcDoc.Lists)
    {
        // This copies the list formatting from the source into the destination document
        List dstList = dstDoc.Lists.AddCopy(srcList);
        AddListSample(builder, dstList);
    }

    dstDoc.Save(ArtifactsDir + "Lists.PrintOutAllLists.docx");
}

private static void AddListSample(DocumentBuilder builder, List list)
{
    builder.Writeln("Sample formatting of list with ListId:" + list.ListId);
    builder.ListFormat.List = list;
    for (int i = 0; i < list.ListLevels.Count; i++)
    {
        builder.ListFormat.ListLevelNumber = i;
        builder.Writeln("Level " + i);
    }

    builder.ListFormat.RemoveNumbers();
    builder.Writeln();
}

Shows how to restart numbering in a list by copying a list.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Create a list based on a template
List list1 = doc.Lists.Add(ListTemplate.NumberArabicParenthesis);
// Modify the formatting of the list
list1.ListLevels[0].Font.Color = Color.Red;
list1.ListLevels[0].Alignment = ListLevelAlignment.Right;

builder.Writeln("List 1 starts below:");
// Use the first list in the document for a while
builder.ListFormat.List = list1;
builder.Writeln("Item 1");
builder.Writeln("Item 2");
builder.ListFormat.RemoveNumbers();

// Now I want to reuse the first list, but need to restart numbering
// This should be done by creating a copy of the original list formatting
List list2 = doc.Lists.AddCopy(list1);

// We can modify the new list in any way. Including setting new start number
list2.ListLevels[0].StartAt = 10;

// Use the second list in the document
builder.Writeln("List 2 starts below:");
builder.ListFormat.List = list2;
builder.Writeln("Item 1");
builder.Writeln("Item 2");
builder.ListFormat.RemoveNumbers();

doc.Save(ArtifactsDir + "Lists.RestartNumberingUsingListCopy.docx");