com.aspose.words

com.aspose.words

Class ListCollection

  • java.lang.Object
    • com.aspose.words.ListCollection
  • All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Iterable
    public class ListCollection 
    extends java.lang.Object

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

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 DocumentBase.Lists property.

To create a new list based on a predefined list template or based on a list style, use the add(com.aspose.words.Style) method.

To create a new list with formatting identical to an existing list, use the addCopy(com.aspose.words.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 ListFormat.List property of ListFormat.

To remove list formatting from a paragraph, use the ListFormat.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.

Example:

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.getListFormat().setList(doc.getLists().add(ListTemplate.NUMBER_ARABIC_DOT));

// Insert text at each of the 9 indent levels
for (int i = 0; i < 9; i++) {
    builder.getListFormat().setListLevelNumber(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.getListFormat().setList(doc.getLists().add(ListTemplate.BULLET_DIAMONDS));

for (int i = 0; i < 9; i++) {
    builder.getListFormat().setListLevelNumber(i);
    builder.writeln("Level " + i);
}

// This is a way to stop list formatting
builder.getListFormat().setList(null);

doc.save(getArtifactsDir() + "Lists.SpecifyListLevel.docx");

Example:

Shows how to enumerate through all lists defined in one document and creates a sample of those lists in another document.
public void printOutAllLists() throws Exception {
    // Open a document that contains lists
    Document srcDoc = new Document(getMyDir() + "Rendering.docx");

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

    for (List srcList : srcDoc.getLists()) {
        // This copies the list formatting from the source into the destination document
        List dstList = dstDoc.getLists().addCopy(srcList);
        addListSample(builder, dstList);
    }

    dstDoc.save(getArtifactsDir() + "Lists.PrintOutAllLists.docx");
}

private static void addListSample(final DocumentBuilder builder, final List list) {
    builder.writeln("Sample formatting of list with ListId:" + list.getListId());
    builder.getListFormat().setList(list);
    for (int i = 0; i < list.getListLevels().getCount(); i++) {
        builder.getListFormat().setListLevelNumber(i);
        builder.writeln("Level " + i);
    }
    builder.getListFormat().removeNumbers();
    builder.writeln();
}

Example:

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.getLists().add(ListTemplate.NUMBER_ARABIC_PARENTHESIS);
// Modify the formatting of the list
list1.getListLevels().get(0).getFont().setColor(Color.RED);
list1.getListLevels().get(0).setAlignment(ListLevelAlignment.RIGHT);

builder.writeln("List 1 starts below:");
// Use the first list in the document for a while
builder.getListFormat().setList(list1);
builder.writeln("Item 1");
builder.writeln("Item 2");
builder.getListFormat().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.getLists().addCopy(list1);

// We can modify the new list in any way. Including setting new start number
list2.getListLevels().get(0).setStartAt(10);

// Use the second list in the document
builder.writeln("List 2 starts below:");
builder.getListFormat().setList(list2);
builder.writeln("Item 1");
builder.writeln("Item 2");
builder.getListFormat().removeNumbers();

doc.save(getArtifactsDir() + "Lists.RestartNumberingUsingListCopy.docx");
See Also:
List, ListLevel, ListFormat

Property Getters/Setters Summary
intgetCount()
Gets the count of numbered and bulleted lists in the document.
DocumentBasegetDocument()
Gets the owner document.
Listget(int index)
Gets a list by index.
 
Method Summary
Listadd(Style listStyle)
Creates a new list that references a list style and adds it to the collection of lists in the document.
Listadd(int listTemplate)
Creates a new list based on a predefined template and adds it to the collection of lists in the document.
ListaddCopy(List srcList)
Creates a new list by copying the specified list and adding it to the collection of lists in the document.
ListgetListByListId(int listId)
Gets a list by a list identifier.
java.util.Iterator<List>iterator()
Gets the enumerator object that will enumerate lists in the document.
 

    • Property Getters/Setters Detail

      • getCount

        public int getCount()
        Gets the count of numbered and bulleted lists in the document.

        Example:

        Shows how to verify owner document properties of lists.
        Document doc = new Document();

ListCollection lists = doc.getLists();

Assert.assertEquals(doc, lists.getDocument());

List list = lists.add(ListTemplate.BULLET_DEFAULT);

Assert.assertEquals(doc, list.getDocument());

System.out.println("Current list count: " + lists.getCount());
System.out.println("Is the first document list: " + (lists.get(0).equals(list)));
System.out.println("ListId: " + list.getListId());
System.out.println("List is the same by ListId: " + (lists.getListByListId(1).equals(list)));

      • getDocument

        public DocumentBase getDocument()
        Gets the owner document.

        Example:

        Shows how to verify owner document properties of lists.
        Document doc = new Document();

ListCollection lists = doc.getLists();

Assert.assertEquals(doc, lists.getDocument());

List list = lists.add(ListTemplate.BULLET_DEFAULT);

Assert.assertEquals(doc, list.getDocument());

System.out.println("Current list count: " + lists.getCount());
System.out.println("Is the first document list: " + (lists.get(0).equals(list)));
System.out.println("ListId: " + list.getListId());
System.out.println("List is the same by ListId: " + (lists.getListByListId(1).equals(list)));

      • get

        public List get(int index)
        Gets a list by index.

        Example:

        Shows how to apply list formatting of an existing list to a collection of paragraphs.
        Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.writeln("Paragraph 1");
builder.writeln("Paragraph 2");
builder.write("Paragraph 3");

NodeCollection paras = doc.getChildNodes(NodeType.PARAGRAPH, true);

Assert.assertEquals(0, DocumentHelper.getListItemCount(paras));

doc.getLists().add(ListTemplate.NUMBER_DEFAULT);
List list = doc.getLists().get(0);

for (Paragraph paragraph : doc.getFirstSection().getBody().getParagraphs()) {
    paragraph.getListFormat().setList(list);
    paragraph.getListFormat().setListLevelNumber(2);
}

paras = doc.getChildNodes(NodeType.PARAGRAPH, true);

Assert.assertEquals(3, DocumentHelper.getListItemCount(paras));

        Example:

        Shows how to verify owner document properties of lists.
        Document doc = new Document();

ListCollection lists = doc.getLists();

Assert.assertEquals(doc, lists.getDocument());

List list = lists.add(ListTemplate.BULLET_DEFAULT);

Assert.assertEquals(doc, list.getDocument());

System.out.println("Current list count: " + lists.getCount());
System.out.println("Is the first document list: " + (lists.get(0).equals(list)));
System.out.println("ListId: " + list.getListId());
System.out.println("List is the same by ListId: " + (lists.getListByListId(1).equals(list)));

    • Method Detail

      • add

        public List add(Style listStyle)
        Creates a new list that references a list style and adds it to the collection of lists in the document.

        The newly created list references the list style. If you change the properties of the list style, it is reflected in the properties of the list. Vice versa, if you change the properties of the list, it is reflected in the properties of the list style.

        Parameters:
        listStyle - The list style.
        Returns:
        The newly created list.

        Example:

        Shows how to create a list style and use it in a document.
        Document doc = new Document();

// Create a new list style
// List formatting associated with this list style is default numbered
Style listStyle = doc.getStyles().add(StyleType.LIST, "MyListStyle");

// This list defines the formatting of the list style
// Note this list can not be used directly to apply formatting to paragraphs (see below)
List list1 = listStyle.getList();

// Check some basic rules about the list that defines a list style
Assert.assertTrue(list1.isListStyleDefinition());
Assert.assertFalse(list1.isListStyleReference());
Assert.assertTrue(list1.isMultiLevel());
Assert.assertEquals(listStyle, list1.getStyle());

// Modify formatting of the list style to our liking
for (ListLevel level : list1.getListLevels()) {
    level.getFont().setName("Verdana");
    level.getFont().setColor(Color.BLUE);
    level.getFont().setBold(true);
}

// Add some text to our document and use the list style
DocumentBuilder builder = new DocumentBuilder(doc);

builder.writeln("Using list style first time:");

// This creates a list based on the list style
List list2 = doc.getLists().add(listStyle);

// Check some basic rules about the list that references a list style
Assert.assertFalse(list2.isListStyleDefinition());
Assert.assertTrue(list2.isListStyleReference());
Assert.assertEquals(listStyle, list2.getStyle());

// Apply the list that references the list style
builder.getListFormat().setList(list2);
builder.writeln("Item 1");
builder.writeln("Item 2");
builder.getListFormat().removeNumbers();

builder.writeln("Using list style second time:");

// Create and apply another list based on the list style
List list3 = doc.getLists().add(listStyle);
builder.getListFormat().setList(list3);
builder.writeln("Item 1");
builder.writeln("Item 2");
builder.getListFormat().removeNumbers();

builder.getDocument().save(getArtifactsDir() + "Lists.CreateAndUseListStyle.docx");

      • add

        public List add(int listTemplate)
        Creates a new list based on a predefined template and adds it to the collection of lists in the document.

        Aspose.Words list templates correspond to the 21 list templates available in the Bullets and Numbering dialog box in Microsoft Word 2003.

        All lists created using this method have 9 list levels.

        Parameters:
        listTemplate - A ListTemplate value. The template of the list.
        Returns:
        The newly created list.

        Example:

        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.getLists().add(ListTemplate.NUMBER_ARABIC_PARENTHESIS);
// Modify the formatting of the list
list1.getListLevels().get(0).getFont().setColor(Color.RED);
list1.getListLevels().get(0).setAlignment(ListLevelAlignment.RIGHT);

builder.writeln("List 1 starts below:");
// Use the first list in the document for a while
builder.getListFormat().setList(list1);
builder.writeln("Item 1");
builder.writeln("Item 2");
builder.getListFormat().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.getLists().addCopy(list1);

// We can modify the new list in any way. Including setting new start number
list2.getListLevels().get(0).setStartAt(10);

// Use the second list in the document
builder.writeln("List 2 starts below:");
builder.getListFormat().setList(list2);
builder.writeln("Item 1");
builder.writeln("Item 2");
builder.getListFormat().removeNumbers();

doc.save(getArtifactsDir() + "Lists.RestartNumberingUsingListCopy.docx");

        Example:

        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.getListFormat().setList(doc.getLists().add(ListTemplate.NUMBER_ARABIC_DOT));

// Insert text at each of the 9 indent levels
for (int i = 0; i < 9; i++) {
    builder.getListFormat().setListLevelNumber(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.getListFormat().setList(doc.getLists().add(ListTemplate.BULLET_DIAMONDS));

for (int i = 0; i < 9; i++) {
    builder.getListFormat().setListLevelNumber(i);
    builder.writeln("Level " + i);
}

// This is a way to stop list formatting
builder.getListFormat().setList(null);

doc.save(getArtifactsDir() + "Lists.SpecifyListLevel.docx");

        Example:

        Shows how to create a list by applying a new list format to a collection of paragraphs.
        Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.writeln("Paragraph 1");
builder.writeln("Paragraph 2");
builder.write("Paragraph 3");

NodeCollection paras = doc.getChildNodes(NodeType.PARAGRAPH, true);

Assert.assertEquals(0, DocumentHelper.getListItemCount(paras));

List list = doc.getLists().add(ListTemplate.NUMBER_UPPERCASE_LETTER_DOT);

for (Paragraph paragraph : doc.getFirstSection().getBody().getParagraphs()) {
    paragraph.getListFormat().setList(list);
    paragraph.getListFormat().setListLevelNumber(1);
}

Assert.assertEquals(3, DocumentHelper.getListItemCount(paras));

      • addCopy

        public List addCopy(List srcList)
        Creates a new list by copying the specified list and adding it to the collection of lists in the document.

        The source list can be from any document. If the source list belongs to a different document, a copy of the list is created and added to the current document.

        If the source list is a reference to or a definition of a list style, the newly created list is not related to the original list style.

        Parameters:
        srcList - The source list to copy from.
        Returns:
        The newly created list.

        Example:

        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.getLists().add(ListTemplate.NUMBER_ARABIC_PARENTHESIS);
// Modify the formatting of the list
list1.getListLevels().get(0).getFont().setColor(Color.RED);
list1.getListLevels().get(0).setAlignment(ListLevelAlignment.RIGHT);

builder.writeln("List 1 starts below:");
// Use the first list in the document for a while
builder.getListFormat().setList(list1);
builder.writeln("Item 1");
builder.writeln("Item 2");
builder.getListFormat().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.getLists().addCopy(list1);

// We can modify the new list in any way. Including setting new start number
list2.getListLevels().get(0).setStartAt(10);

// Use the second list in the document
builder.writeln("List 2 starts below:");
builder.getListFormat().setList(list2);
builder.writeln("Item 1");
builder.writeln("Item 2");
builder.getListFormat().removeNumbers();

doc.save(getArtifactsDir() + "Lists.RestartNumberingUsingListCopy.docx");

        Example:

        Shows how to enumerate through all lists defined in one document and creates a sample of those lists in another document.
        public void printOutAllLists() throws Exception {
    // Open a document that contains lists
    Document srcDoc = new Document(getMyDir() + "Rendering.docx");

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

    for (List srcList : srcDoc.getLists()) {
        // This copies the list formatting from the source into the destination document
        List dstList = dstDoc.getLists().addCopy(srcList);
        addListSample(builder, dstList);
    }

    dstDoc.save(getArtifactsDir() + "Lists.PrintOutAllLists.docx");
}

private static void addListSample(final DocumentBuilder builder, final List list) {
    builder.writeln("Sample formatting of list with ListId:" + list.getListId());
    builder.getListFormat().setList(list);
    for (int i = 0; i < list.getListLevels().getCount(); i++) {
        builder.getListFormat().setListLevelNumber(i);
        builder.writeln("Level " + i);
    }
    builder.getListFormat().removeNumbers();
    builder.writeln();
}

      • getListByListId

        public List getListByListId(int listId)
        Gets a list by a list identifier.

        You don't normally need to use this method. Most of the time you apply list formatting to paragraphs just by settings the ListFormat.List property of the ListFormat object.

        Parameters:
        listId - The list identifier.
        Returns:
        Returns the list object. Returns null if a list with the specified identifier was not found.

        Example:

        Shows how to verify owner document properties of lists.
        Document doc = new Document();

ListCollection lists = doc.getLists();

Assert.assertEquals(doc, lists.getDocument());

List list = lists.add(ListTemplate.BULLET_DEFAULT);

Assert.assertEquals(doc, list.getDocument());

System.out.println("Current list count: " + lists.getCount());
System.out.println("Is the first document list: " + (lists.get(0).equals(list)));
System.out.println("ListId: " + list.getListId());
System.out.println("List is the same by ListId: " + (lists.getListByListId(1).equals(list)));

      • iterator

        public java.util.Iterator<List> iterator()
        Gets the enumerator object that will enumerate lists in the document.

        Example:

        Shows how to enumerate through all lists defined in one document and creates a sample of those lists in another document.
        public void printOutAllLists() throws Exception {
    // Open a document that contains lists
    Document srcDoc = new Document(getMyDir() + "Rendering.docx");

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

    for (List srcList : srcDoc.getLists()) {
        // This copies the list formatting from the source into the destination document
        List dstList = dstDoc.getLists().addCopy(srcList);
        addListSample(builder, dstList);
    }

    dstDoc.save(getArtifactsDir() + "Lists.PrintOutAllLists.docx");
}

private static void addListSample(final DocumentBuilder builder, final List list) {
    builder.writeln("Sample formatting of list with ListId:" + list.getListId());
    builder.getListFormat().setList(list);
    for (int i = 0; i < list.getListLevels().getCount(); i++) {
        builder.getListFormat().setListLevelNumber(i);
        builder.writeln("Level " + i);
    }
    builder.getListFormat().removeNumbers();
    builder.writeln();
}