com.aspose.words

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

Represents formatting of a list.

A list in a Microsoft Word document is a set of list formatting properties. Each list can have up to 9 levels and formatting properties, such as number style, start value, indent, tab position etc are defined separately for each level.

A List object always belongs to the ListCollection collection.

To create a new list, use the Add methods of the ListCollection collection.

To modify formatting of a list, use ListLevel objects found in the ListLevels collection.

To apply or remove list formatting from a paragraph, use ListFormat.

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

// There are 9 levels in this list, lets try them all.
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));

// There are 9 levels in this list, lets try them all.
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);

builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.SpecifyListLevel.doc");

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

builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.RestartNumberingUsingListCopy.doc");

Example:

Shows how to apply custom list formatting to paragraphs when using DocumentBuilder.
Document doc = new Document();

// Create a list based on one of the Microsoft Word list templates.
List list = doc.getLists().add(ListTemplate.NUMBER_DEFAULT);

// Completely customize one list level.
ListLevel level1 = list.getListLevels().get(0);
level1.getFont().setColor(Color.RED);
level1.getFont().setSize(24);
level1.setNumberStyle(NumberStyle.ORDINAL_TEXT);
level1.setStartAt(21);
level1.setNumberFormat("\u0000");

level1.setNumberPosition(-36);
level1.setTextPosition(144);
level1.setTabPosition(144);

// Completely customize yet another list level.
ListLevel level2 = list.getListLevels().get(1);
level2.setAlignment(ListLevelAlignment.RIGHT);
level2.setNumberStyle(NumberStyle.BULLET);
level2.getFont().setName("Wingdings");
level2.getFont().setColor(Color.BLUE);
level2.getFont().setSize(24);
level2.setNumberFormat("\uf0af");    // A bullet that looks like some sort of a star.
level2.setTrailingCharacter(ListTrailingCharacter.SPACE);
level2.setNumberPosition(144);

// Now add some text that uses the list that we created.
// It does not matter when to customize the list - before or after adding the paragraphs.
DocumentBuilder builder = new DocumentBuilder(doc);

builder.getListFormat().setList(list);
builder.writeln("The quick brown fox...");
builder.writeln("The quick brown fox...");

builder.getListFormat().listIndent();
builder.writeln("jumped over the lazy dog.");
builder.writeln("jumped over the lazy dog.");

builder.getListFormat().listOutdent();
builder.writeln("The quick brown fox...");

builder.getListFormat().removeNumbers();

builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.CreateCustomList.doc");
See Also:
ListCollection, ListLevel, ListFormat

Property Getters/Setters Summary
DocumentBasegetDocument()
Gets the owner document.
booleanisListStyleDefinition()
Returns true if this list is a definition of a list style.
booleanisListStyleReference()
Returns true if this list is a reference to a list style.
booleanisMultiLevel()
Returns true when the list contains 9 levels; false when 1 level.
booleanisRestartAtEachSection()
void
           Specifies whether list should be restarted at each section. Default value is false.
intgetListId()
Gets the unique identifier of the list.
ListLevelCollectiongetListLevels()
Gets the collection of list levels for this list.
StylegetStyle()
Gets the list style that this list references or defines.
 
Method Summary
intcompareTo(java.lang.Object obj)
booleanequals(java.lang.Object obj)
 

    • Property Getters/Setters Detail

      • getDocument

        public DocumentBase getDocument()
        
        Gets the owner document.

        A list always has a parent document and is valid only in the context of that document.

        Example:

        Illustrates the owner document properties of lists.
        Document doc = new Document();
        
        ListCollection lists = doc.getLists();
        // All of these should be equal.
        System.out.println("ListCollection document is doc: " + (doc == lists.getDocument()));
        System.out.println("Starting list count: " + lists.getCount());
        
        List list = lists.add(ListTemplate.BULLET_DEFAULT);
        System.out.println("List document is doc: " + (list.getDocument() == doc));
        System.out.println("List count after adding list: " + lists.getCount());
        System.out.println("Is the first document list: " + (lists.get(0) == list));
        System.out.println("ListId: " + list.getListId());
        System.out.println("List is the same by ListId: " + (lists.getListByListId(1) == list));
      • isListStyleDefinition

        public boolean isListStyleDefinition()
        
        Returns true if this list is a definition of a list style.

        When this property is true, the Style property returns the list style that this list defines.

        By modifying properties of a list that defines a list style, you modify the properties of the list style.

        A list that is a definition of a list style cannot be applied directly to paragraphs to make them numbered.

        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.
        System.out.println("IsListStyleDefinition: " + list1.isListStyleDefinition()); // Will be true
        System.out.println("IsListStyleReference: " + list1.isListStyleReference()); // Will be false
        System.out.println("IsMultiLevel: " + list1.isMultiLevel()); // Will be true
        System.out.println("List style has been set: " + (listStyle == list1.getStyle())); // Are equal
        
        // Modify formatting of the list style to our liking.
        for (int i = 0; i < list1.getListLevels().getCount(); i++)
        {
            ListLevel level = list1.getListLevels().get(i);
            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.
        System.out.println("IsListStyleDefinition: " + list2.isListStyleDefinition()); // Will be false
        System.out.println("IsListStyleReference: " + list2.isListStyleReference()); // Will be true
        System.out.println("List Style has been set: " + (listStyle == list2.getStyle())); // Are equal
        
        // 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(getMyDir() + "\\Artifacts\\Lists.CreateAndUseListStyle.doc");
        See Also:
        Style, IsListStyleReference
      • isListStyleReference

        public boolean isListStyleReference()
        
        Returns true if this list is a reference to a list style.

        Note, modifying properties of a list that is a reference to list style has no effect. The list formatting specified in the list style itself always takes precedence.

        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.
        System.out.println("IsListStyleDefinition: " + list1.isListStyleDefinition()); // Will be true
        System.out.println("IsListStyleReference: " + list1.isListStyleReference()); // Will be false
        System.out.println("IsMultiLevel: " + list1.isMultiLevel()); // Will be true
        System.out.println("List style has been set: " + (listStyle == list1.getStyle())); // Are equal
        
        // Modify formatting of the list style to our liking.
        for (int i = 0; i < list1.getListLevels().getCount(); i++)
        {
            ListLevel level = list1.getListLevels().get(i);
            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.
        System.out.println("IsListStyleDefinition: " + list2.isListStyleDefinition()); // Will be false
        System.out.println("IsListStyleReference: " + list2.isListStyleReference()); // Will be true
        System.out.println("List Style has been set: " + (listStyle == list2.getStyle())); // Are equal
        
        // 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(getMyDir() + "\\Artifacts\\Lists.CreateAndUseListStyle.doc");
        See Also:
        Style, IsListStyleDefinition
      • isMultiLevel

        public boolean isMultiLevel()
        
        Returns true when the list contains 9 levels; false when 1 level.

        The lists that you create with Aspose.Words are always multi-level lists and contain 9 levels.

        Microsoft Word 2003 and later always create multi-level lists with 9 levels. But in some documents, created with earlier versions of Microsoft Word you might encounter lists that have 1 level only.

        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.
        System.out.println("IsListStyleDefinition: " + list1.isListStyleDefinition()); // Will be true
        System.out.println("IsListStyleReference: " + list1.isListStyleReference()); // Will be false
        System.out.println("IsMultiLevel: " + list1.isMultiLevel()); // Will be true
        System.out.println("List style has been set: " + (listStyle == list1.getStyle())); // Are equal
        
        // Modify formatting of the list style to our liking.
        for (int i = 0; i < list1.getListLevels().getCount(); i++)
        {
            ListLevel level = list1.getListLevels().get(i);
            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.
        System.out.println("IsListStyleDefinition: " + list2.isListStyleDefinition()); // Will be false
        System.out.println("IsListStyleReference: " + list2.isListStyleReference()); // Will be true
        System.out.println("List Style has been set: " + (listStyle == list2.getStyle())); // Are equal
        
        // 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(getMyDir() + "\\Artifacts\\Lists.CreateAndUseListStyle.doc");
      • isRestartAtEachSection/isRestartAtEachSection

        public boolean isRestartAtEachSection() / public void isRestartAtEachSection(boolean value)
        
        Specifies whether list should be restarted at each section. Default value is false.

        This option is supported only in RTF, DOC and DOCX document formats.

        This option will be written to DOCX only if OoxmlCompliance is higher then OoxmlCompliance.ECMA_376_2006.

        Example:

        Shows how to specify that the list has to be restarted at each section.
        Document doc = new Document();
        
        doc.getLists().add(ListTemplate.NUMBER_DEFAULT);
        
        List list = doc.getLists().get(0);
        
        // Set true to specify that the list has to be restarted at each section.
        list.isRestartAtEachSection(true);
        
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        builder.getListFormat().setList(list);
        
        for (int i = 1; i <= 45; i++)
        {
            builder.write(MessageFormat.format("List Item {0}\n",i));
        
            // Insert section break.
            if (i == 15 || i == 30)
                builder.insertBreak(BreakType.SECTION_BREAK_NEW_PAGE);
        }
        
        // IsRestartAtEachSection will be written only if compliance is higher then OoxmlComplianceCore.Ecma376
        OoxmlSaveOptions options = new OoxmlSaveOptions();
        options.setCompliance(OoxmlCompliance.ISO_29500_2008_TRANSITIONAL);
        
        doc.save(getMyDir() + "\\Artifacts\\RestartingDocumentList.docx", options);
      • getListId

        public int getListId()
        
        Gets the unique identifier of the list.

        You do not normally need to use this property. But if you use it, you normally do so in conjunction with the ListCollection.getListByListId(int) method to find a list by its identifier.

        Example:

        Finds and outputs all paragraphs in a document that are bulleted or numbered.
        NodeCollection paras = doc.getChildNodes(NodeType.PARAGRAPH, true);
        for (Paragraph para : (Iterable<Paragraph>) paras)
        {
            if (para.getListFormat().isListItem())
            {
                System.out.println(java.text.MessageFormat.format("*** A paragraph belongs to list {0}", para.getListFormat().getList().getListId()));
                System.out.println(para.getText());
            }
        }

        Example:

        Illustrates the owner document properties of lists.
        Document doc = new Document();
        
        ListCollection lists = doc.getLists();
        // All of these should be equal.
        System.out.println("ListCollection document is doc: " + (doc == lists.getDocument()));
        System.out.println("Starting list count: " + lists.getCount());
        
        List list = lists.add(ListTemplate.BULLET_DEFAULT);
        System.out.println("List document is doc: " + (list.getDocument() == doc));
        System.out.println("List count after adding list: " + lists.getCount());
        System.out.println("Is the first document list: " + (lists.get(0) == list));
        System.out.println("ListId: " + list.getListId());
        System.out.println("List is the same by ListId: " + (lists.getListByListId(1) == list));
      • getListLevels

        public ListLevelCollection getListLevels()
        
        Gets the collection of list levels for this list.

        Use this property to access and modify formatting individual to each level of the list.

        Example:

        Shows how to apply custom list formatting to paragraphs when using DocumentBuilder.
        Document doc = new Document();
        
        // Create a list based on one of the Microsoft Word list templates.
        List list = doc.getLists().add(ListTemplate.NUMBER_DEFAULT);
        
        // Completely customize one list level.
        ListLevel level1 = list.getListLevels().get(0);
        level1.getFont().setColor(Color.RED);
        level1.getFont().setSize(24);
        level1.setNumberStyle(NumberStyle.ORDINAL_TEXT);
        level1.setStartAt(21);
        level1.setNumberFormat("\u0000");
        
        level1.setNumberPosition(-36);
        level1.setTextPosition(144);
        level1.setTabPosition(144);
        
        // Completely customize yet another list level.
        ListLevel level2 = list.getListLevels().get(1);
        level2.setAlignment(ListLevelAlignment.RIGHT);
        level2.setNumberStyle(NumberStyle.BULLET);
        level2.getFont().setName("Wingdings");
        level2.getFont().setColor(Color.BLUE);
        level2.getFont().setSize(24);
        level2.setNumberFormat("\uf0af");    // A bullet that looks like some sort of a star.
        level2.setTrailingCharacter(ListTrailingCharacter.SPACE);
        level2.setNumberPosition(144);
        
        // Now add some text that uses the list that we created.
        // It does not matter when to customize the list - before or after adding the paragraphs.
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        builder.getListFormat().setList(list);
        builder.writeln("The quick brown fox...");
        builder.writeln("The quick brown fox...");
        
        builder.getListFormat().listIndent();
        builder.writeln("jumped over the lazy dog.");
        builder.writeln("jumped over the lazy dog.");
        
        builder.getListFormat().listOutdent();
        builder.writeln("The quick brown fox...");
        
        builder.getListFormat().removeNumbers();
        
        builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.CreateCustomList.doc");
      • getStyle

        public Style getStyle()
        
        Gets the list style that this list references or defines.

        If this list is not associated with a list style, the property will return null.

        A list could be a reference to a list style, in this case IsListStyleReference will be true.

        A list could be a definition of a list style, in this case IsListStyleDefinition will be true. Such a list cannot be applied to paragraphs in the document directly.

        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.
        System.out.println("IsListStyleDefinition: " + list1.isListStyleDefinition()); // Will be true
        System.out.println("IsListStyleReference: " + list1.isListStyleReference()); // Will be false
        System.out.println("IsMultiLevel: " + list1.isMultiLevel()); // Will be true
        System.out.println("List style has been set: " + (listStyle == list1.getStyle())); // Are equal
        
        // Modify formatting of the list style to our liking.
        for (int i = 0; i < list1.getListLevels().getCount(); i++)
        {
            ListLevel level = list1.getListLevels().get(i);
            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.
        System.out.println("IsListStyleDefinition: " + list2.isListStyleDefinition()); // Will be false
        System.out.println("IsListStyleReference: " + list2.isListStyleReference()); // Will be true
        System.out.println("List Style has been set: " + (listStyle == list2.getStyle())); // Are equal
        
        // 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(getMyDir() + "\\Artifacts\\Lists.CreateAndUseListStyle.doc");
    • Method Detail

      • compareTo

        public int compareTo(java.lang.Object obj)
        Parameters:
        obj -
        Returns:
      • equals

        public boolean equals(java.lang.Object obj)