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 restart numbering in a list by copying a list.
Document doc = new Document();

// A list allows us to organize and decorate sets of paragraphs with prefix symbols and indents.
// We can create nested lists by increasing the indent level. 
// We can begin and end a list by using a document builder's "ListFormat" property. 
// Each paragraph that we add between a list's start and the end will become an item in the list.
// Create a list from a Microsoft Word template, and customize its first list level.
List list1 = doc.getLists().add(ListTemplate.NUMBER_ARABIC_PARENTHESIS);
list1.getListLevels().get(0).getFont().setColor(Color.RED);
list1.getListLevels().get(0).setAlignment(ListLevelAlignment.RIGHT);

// Apply our list to some paragraphs.
DocumentBuilder builder = new DocumentBuilder(doc);

builder.writeln("List 1 starts below:");
builder.getListFormat().setList(list1);
builder.writeln("Item 1");
builder.writeln("Item 2");
builder.getListFormat().removeNumbers();

// We can add a copy of an existing list to the document's list collection
// to create a similar list without making changes to the original.
List list2 = doc.getLists().addCopy(list1);
list2.getListLevels().get(0).getFont().setColor(Color.BLUE);
list2.getListLevels().get(0).setStartAt(10);

// Apply the second list to new paragraphs.
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 work with list levels.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Assert.assertFalse(builder.getListFormat().isListItem());

// A list allows us to organize and decorate sets of paragraphs with prefix symbols and indents.
// We can create nested lists by increasing the indent level. 
// We can begin and end a list by using a document builder's "ListFormat" property. 
// Each paragraph that we add between a list's start and the end will become an item in the list.
// Below are two types of lists that we can create using a document builder.
// 1 -  A numbered list:
// Numbered lists create a logical order for their paragraphs by numbering each item.
builder.getListFormat().setList(doc.getLists().add(ListTemplate.NUMBER_DEFAULT));

Assert.assertTrue(builder.getListFormat().isListItem());

// By setting the "ListLevelNumber" property, we can increase the list level
// to begin a self-contained sub-list at the current list item.
// The Microsoft Word list template called "NumberDefault" uses numbers to create list levels for the first list level.
// Deeper list levels use letters and lowercase Roman numerals. 
for (int i = 0; i < 9; i++) {
    builder.getListFormat().setListLevelNumber(i);
    builder.writeln("Level " + i);
}

// 2 -  A bulleted list:
// This list will apply an indent and a bullet symbol ("�") before each paragraph.
// Deeper levels of this list will use different symbols, such as "�" and "?".
builder.getListFormat().setList(doc.getLists().add(ListTemplate.BULLET_DEFAULT));

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

// We can disable list formatting to not format any subsequent paragraphs as lists by un-setting the "List" flag.
builder.getListFormat().setList(null);

Assert.assertFalse(builder.getListFormat().isListItem());

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

Example:

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

// A list allows us to organize and decorate sets of paragraphs with prefix symbols and indents.
// We can create nested lists by increasing the indent level. 
// We can begin and end a list by using a document builder's "ListFormat" property. 
// Each paragraph that we add between a list's start and the end will become an item in the list.
// Create a list from a Microsoft Word template, and customize the first two of its list levels.
List list = doc.getLists().add(ListTemplate.NUMBER_DEFAULT);

ListLevel listLevel = list.getListLevels().get(0);
listLevel.getFont().setColor(Color.RED);
listLevel.getFont().setSize(24.0);
listLevel.setNumberStyle(NumberStyle.ORDINAL_TEXT);
listLevel.setStartAt(21);
listLevel.setNumberFormat("\u0000");

listLevel.setNumberPosition(-36);
listLevel.setTextPosition(144.0);
listLevel.setTabPosition(144.0);

listLevel = list.getListLevels().get(1);
listLevel.setAlignment(ListLevelAlignment.RIGHT);
listLevel.setNumberStyle(NumberStyle.BULLET);
listLevel.getFont().setName("Wingdings");
listLevel.getFont().setColor(Color.BLUE);
listLevel.getFont().setSize(24.0);

// This NumberFormat value will create star-shaped bullet list symbols.
listLevel.setNumberFormat("\uf0af");
listLevel.setTrailingCharacter(ListTrailingCharacter.SPACE);
listLevel.setNumberPosition(144.0);

// Create paragraphs and apply both list levels of our custom list formatting to them.
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(getArtifactsDir() + "Lists.CreateCustomList.docx");
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(List other)
Compares the specified list to the current list.
booleanequals(List list)
Compares with the specified list.
booleanequals(java.lang.Object obj)
inthashCode()
Calculates hash code for this list object.
 

    • 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:

        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)));
      • 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();
        
        // A list allows us to organize and decorate sets of paragraphs with prefix symbols and indents.
        // We can create nested lists by increasing the indent level. 
        // We can begin and end a list by using a document builder's "ListFormat" property. 
        // Each paragraph that we add between a list's start and the end will become an item in the list.
        // We can contain an entire List object within a style.
        Style listStyle = doc.getStyles().add(StyleType.LIST, "MyListStyle");
        
        List list1 = listStyle.getList();
        
        Assert.assertTrue(list1.isListStyleDefinition());
        Assert.assertFalse(list1.isListStyleReference());
        Assert.assertTrue(list1.isMultiLevel());
        Assert.assertEquals(listStyle, list1.getStyle());
        
        // Change the appearance of all list levels in our list.
        for (ListLevel level : list1.getListLevels()) {
            level.getFont().setName("Verdana");
            level.getFont().setColor(Color.BLUE);
            level.getFont().setBold(true);
        }
        
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        builder.writeln("Using list style first time:");
        
        // Create another list from a list within a style.
        List list2 = doc.getLists().add(listStyle);
        
        Assert.assertFalse(list2.isListStyleDefinition());
        Assert.assertTrue(list2.isListStyleReference());
        Assert.assertEquals(listStyle, list2.getStyle());
        
        // Add some list items that our list will format.
        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");
        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();
        
        // A list allows us to organize and decorate sets of paragraphs with prefix symbols and indents.
        // We can create nested lists by increasing the indent level. 
        // We can begin and end a list by using a document builder's "ListFormat" property. 
        // Each paragraph that we add between a list's start and the end will become an item in the list.
        // We can contain an entire List object within a style.
        Style listStyle = doc.getStyles().add(StyleType.LIST, "MyListStyle");
        
        List list1 = listStyle.getList();
        
        Assert.assertTrue(list1.isListStyleDefinition());
        Assert.assertFalse(list1.isListStyleReference());
        Assert.assertTrue(list1.isMultiLevel());
        Assert.assertEquals(listStyle, list1.getStyle());
        
        // Change the appearance of all list levels in our list.
        for (ListLevel level : list1.getListLevels()) {
            level.getFont().setName("Verdana");
            level.getFont().setColor(Color.BLUE);
            level.getFont().setBold(true);
        }
        
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        builder.writeln("Using list style first time:");
        
        // Create another list from a list within a style.
        List list2 = doc.getLists().add(listStyle);
        
        Assert.assertFalse(list2.isListStyleDefinition());
        Assert.assertTrue(list2.isListStyleReference());
        Assert.assertEquals(listStyle, list2.getStyle());
        
        // Add some list items that our list will format.
        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");
        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();
        
        // A list allows us to organize and decorate sets of paragraphs with prefix symbols and indents.
        // We can create nested lists by increasing the indent level. 
        // We can begin and end a list by using a document builder's "ListFormat" property. 
        // Each paragraph that we add between a list's start and the end will become an item in the list.
        // We can contain an entire List object within a style.
        Style listStyle = doc.getStyles().add(StyleType.LIST, "MyListStyle");
        
        List list1 = listStyle.getList();
        
        Assert.assertTrue(list1.isListStyleDefinition());
        Assert.assertFalse(list1.isListStyleReference());
        Assert.assertTrue(list1.isMultiLevel());
        Assert.assertEquals(listStyle, list1.getStyle());
        
        // Change the appearance of all list levels in our list.
        for (ListLevel level : list1.getListLevels()) {
            level.getFont().setName("Verdana");
            level.getFont().setColor(Color.BLUE);
            level.getFont().setBold(true);
        }
        
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        builder.writeln("Using list style first time:");
        
        // Create another list from a list within a style.
        List list2 = doc.getLists().add(listStyle);
        
        Assert.assertFalse(list2.isListStyleDefinition());
        Assert.assertTrue(list2.isListStyleReference());
        Assert.assertEquals(listStyle, list2.getStyle());
        
        // Add some list items that our list will format.
        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");
      • 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 configure a list to restart numbering at each section.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        doc.getLists().add(ListTemplate.NUMBER_DEFAULT);
        
        List list = doc.getLists().get(0);
        list.isRestartAtEachSection(restartListAtEachSection);
        
        // The "IsRestartAtEachSection" property will only be applicable when
        // the document's OOXML compliance level is to a standard that is newer than "OoxmlComplianceCore.Ecma376".
        OoxmlSaveOptions options = new OoxmlSaveOptions();
        {
            options.setCompliance(OoxmlCompliance.ISO_29500_2008_TRANSITIONAL);
        }
        
        builder.getListFormat().setList(list);
        
        builder.writeln("List item 1");
        builder.writeln("List item 2");
        builder.insertBreak(BreakType.SECTION_BREAK_NEW_PAGE);
        builder.writeln("List item 3");
        builder.writeln("List item 4");
        
        doc.save(getArtifactsDir() + "OoxmlSaveOptions.RestartingDocumentList.docx", options);
        
        doc = new Document(getArtifactsDir() + "OoxmlSaveOptions.RestartingDocumentList.docx");
        
        Assert.assertEquals(restartListAtEachSection, doc.getLists().get(0).isRestartAtEachSection());
      • 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:

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

        Example:

        Shows how to output all paragraphs in a document that are list items.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        builder.getListFormat().applyNumberDefault();
        builder.writeln("Numbered list item 1");
        builder.writeln("Numbered list item 2");
        builder.writeln("Numbered list item 3");
        builder.getListFormat().removeNumbers();
        
        builder.getListFormat().applyBulletDefault();
        builder.writeln("Bulleted list item 1");
        builder.writeln("Bulleted list item 2");
        builder.writeln("Bulleted list item 3");
        builder.getListFormat().removeNumbers();
        
        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());
            }
        }
      • 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();
        
        // A list allows us to organize and decorate sets of paragraphs with prefix symbols and indents.
        // We can create nested lists by increasing the indent level. 
        // We can begin and end a list by using a document builder's "ListFormat" property. 
        // Each paragraph that we add between a list's start and the end will become an item in the list.
        // Create a list from a Microsoft Word template, and customize the first two of its list levels.
        List list = doc.getLists().add(ListTemplate.NUMBER_DEFAULT);
        
        ListLevel listLevel = list.getListLevels().get(0);
        listLevel.getFont().setColor(Color.RED);
        listLevel.getFont().setSize(24.0);
        listLevel.setNumberStyle(NumberStyle.ORDINAL_TEXT);
        listLevel.setStartAt(21);
        listLevel.setNumberFormat("\u0000");
        
        listLevel.setNumberPosition(-36);
        listLevel.setTextPosition(144.0);
        listLevel.setTabPosition(144.0);
        
        listLevel = list.getListLevels().get(1);
        listLevel.setAlignment(ListLevelAlignment.RIGHT);
        listLevel.setNumberStyle(NumberStyle.BULLET);
        listLevel.getFont().setName("Wingdings");
        listLevel.getFont().setColor(Color.BLUE);
        listLevel.getFont().setSize(24.0);
        
        // This NumberFormat value will create star-shaped bullet list symbols.
        listLevel.setNumberFormat("\uf0af");
        listLevel.setTrailingCharacter(ListTrailingCharacter.SPACE);
        listLevel.setNumberPosition(144.0);
        
        // Create paragraphs and apply both list levels of our custom list formatting to them.
        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(getArtifactsDir() + "Lists.CreateCustomList.docx");
      • 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();
        
        // A list allows us to organize and decorate sets of paragraphs with prefix symbols and indents.
        // We can create nested lists by increasing the indent level. 
        // We can begin and end a list by using a document builder's "ListFormat" property. 
        // Each paragraph that we add between a list's start and the end will become an item in the list.
        // We can contain an entire List object within a style.
        Style listStyle = doc.getStyles().add(StyleType.LIST, "MyListStyle");
        
        List list1 = listStyle.getList();
        
        Assert.assertTrue(list1.isListStyleDefinition());
        Assert.assertFalse(list1.isListStyleReference());
        Assert.assertTrue(list1.isMultiLevel());
        Assert.assertEquals(listStyle, list1.getStyle());
        
        // Change the appearance of all list levels in our list.
        for (ListLevel level : list1.getListLevels()) {
            level.getFont().setName("Verdana");
            level.getFont().setColor(Color.BLUE);
            level.getFont().setBold(true);
        }
        
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        builder.writeln("Using list style first time:");
        
        // Create another list from a list within a style.
        List list2 = doc.getLists().add(listStyle);
        
        Assert.assertFalse(list2.isListStyleDefinition());
        Assert.assertTrue(list2.isListStyleReference());
        Assert.assertEquals(listStyle, list2.getStyle());
        
        // Add some list items that our list will format.
        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");
    • Method Detail

      • compareTo

        public int compareTo(List other)
        Compares the specified list to the current list.
      • equals

        public boolean equals(List list)
        Compares with the specified list.
      • equals

        public boolean equals(java.lang.Object obj)
      • hashCode

        public int hashCode()
        Calculates hash code for this list object.