com.aspose.words

Class ListFormat

  • java.lang.Object
    • com.aspose.words.ListFormat
public class ListFormat 
extends java.lang.Object

Allows to control what list formatting is applied to a paragraph.

A paragraph in a Microsoft Word document can be bulleted or numbered. When a paragraph is bulleted or numbered, it is said that list formatting is applied to the paragraph.

You do not create objects of the ListFormat class directly. You access ListFormat as a property of another object that can have list formatting associated with it. At the moment the objects that can have list formatting are: Paragraph, Style and DocumentBuilder.

ListFormat of a Paragraph specifies what list formatting and list level is applied to that particular paragraph.

ListFormat of a Style (applicable to paragraph styles only) allows to specify what list formatting and list level is applied to all paragraphs of that particular style.

ListFormat of a DocumentBuilder provides access to the list formatting at the current cursor position inside the DocumentBuilder.

The list formatting itself is stored inside a List object that is stored separately from the paragraphs. The list objects are stored inside a ListCollection collection. There is a single ListCollection collection per Document.

The paragraphs do not physically belong to a list. The paragraphs just reference a particular list object via the List property and a particular level in the list via the ListLevelNumber property. By setting these two properties you control what bullets and numbering is applied to a paragraph.

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

Property Getters/Setters Summary
booleanisListItem()
True when the paragraph has bulleted or numbered formatting applied to it.
ListgetList()
void
setList(List value)
           Gets or sets the list this paragraph is a member of.
ListLevelgetListLevel()
Returns the list level formatting plus any formatting overrides applied to the current paragraph.
intgetListLevelNumber()
void
           Gets or sets the list level number (0 to 8) for the paragraph.
 
Method Summary
voidapplyBulletDefault()
Starts a new default bulleted list and applies it to the paragraph.
voidapplyNumberDefault()
Starts a new default numbered list and applies it to the paragraph.
voidlistIndent()
Increases the list level of the current paragraph by one level.
voidlistOutdent()
Decreases the list level of the current paragraph by one level.
voidremoveNumbers()
Removes numbers or bullets from the current paragraph and sets list level to zero.
 

    • Property Getters/Setters Detail

      • isListItem

        public boolean isListItem()
        
        True when the paragraph has bulleted or numbered formatting applied to it.

        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());
            }
        }
      • getList/setList

        public List getList() / public void setList(List value)
        
        Gets or sets the list this paragraph is a member of.

        The list that is being assigned to this property must belong to the current document.

        The list that is being assigned to this property must not be a list style definition.

        Setting this property to null removes bullets and numbering from the paragraph and sets the list level number to zero. Setting this property to null is equivalent to calling removeNumbers().

        Example:

        Applies list formatting of an existing list to a collection of paragraphs.
        Body body = doc.getFirstSection().getBody();
        List list = doc.getLists().get(0);
        for (Paragraph paragraph : body.getParagraphs())
        {
            paragraph.getListFormat().setList(list);
            paragraph.getListFormat().setListLevelNumber(2);
        }

        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 start a numbered list, add a bulleted list inside it, then return to the numbered list.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Create an outline list for the headings.
        List outlineList = doc.getLists().add(ListTemplate.OUTLINE_NUMBERS);
        builder.getListFormat().setList(outlineList);
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        builder.writeln("This is my Chapter 1");
        
        // Create a numbered list.
        List numberedList = doc.getLists().add(ListTemplate.NUMBER_DEFAULT);
        builder.getListFormat().setList(numberedList);
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.NORMAL);
        builder.writeln("Numbered list item 1.");
        
        // Create a bulleted list.
        List bulletedList = doc.getLists().add(ListTemplate.BULLET_DEFAULT);
        builder.getListFormat().setList(bulletedList);
        builder.getParagraphFormat().setLeftIndent(72);
        builder.writeln("Bulleted list item 1.");
        builder.writeln("Bulleted list item 2.");
        builder.getParagraphFormat().clearFormatting();
        
        // Revert to the numbered list.
        builder.getListFormat().setList(numberedList);
        builder.writeln("Numbered list item 2.");
        builder.writeln("Numbered list item 3.");
        
        // Revert to the outline list.
        builder.getListFormat().setList(outlineList);
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        builder.writeln("This is my Chapter 2");
        
        builder.getParagraphFormat().clearFormatting();
        
        builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.NestedLists.doc");
        See Also:
        ListLevelNumber, removeNumbers()
      • getListLevel

        public ListLevel getListLevel()
        
        Returns the list level formatting plus any formatting overrides applied to the current paragraph.

        Example:

        Shows how to modify list formatting of the current list level.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Create and apply list formatting to the current paragraph.
        builder.getListFormat().setList(doc.getLists().add(ListTemplate.NUMBER_DEFAULT));
        
        // Modify formatting of the current (first) list level.
        builder.getListFormat().getListLevel().getFont().setBold(true);
        
        builder.writeln("Item 1");
        builder.writeln("Item 2");
        builder.getListFormat().removeNumbers();
      • getListLevelNumber/setListLevelNumber

        public int getListLevelNumber() / public void setListLevelNumber(int value)
        
        Gets or sets the list level number (0 to 8) for the paragraph.

        In Word documents, lists may consist of 1 or 9 levels, numbered 0 to 8.

        Has effect only when the List property is set to reference a valid list.

        Example:

        Applies list formatting of an existing list to a collection of paragraphs.
        Body body = doc.getFirstSection().getBody();
        List list = doc.getLists().get(0);
        for (Paragraph paragraph : body.getParagraphs())
        {
            paragraph.getListFormat().setList(list);
            paragraph.getListFormat().setListLevelNumber(2);
        }

        Example:

        Creates new list formatting and applies it to a collection of paragraphs.
        List list = doc.getLists().add(ListTemplate.NUMBER_UPPERCASE_LETTER_DOT);
        
        Body body = doc.getFirstSection().getBody();
        for (Paragraph paragraph : body.getParagraphs())
        {
            paragraph.getListFormat().setList(list);
            paragraph.getListFormat().setListLevelNumber(1);
        }

        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");
        See Also:
        List
    • Method Detail

      • applyBulletDefault

        public void applyBulletDefault()
        Starts a new default bulleted list and applies it to the paragraph.

        This is a shortcut method that creates a new list using the default bulleted template, applies it to the paragraph and selects the 1st list level.

        See Also:
        List, removeNumbers(), ListLevelNumber

        Example:

        Shows how to apply default bulleted or numbered list formatting to paragraphs when using DocumentBuilder.
        DocumentBuilder builder = new DocumentBuilder();
        
        builder.writeln("Aspose.Words allows:");
        builder.writeln();
        
        // Start a numbered list with default formatting.
        builder.getListFormat().applyNumberDefault();
        builder.writeln("Opening documents from different formats:");
        
        // Go to second list level, add more text.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        
        // Outdent to the first list level.
        builder.getListFormat().listOutdent();
        builder.writeln("Processing documents");
        builder.writeln("Saving documents in different formats:");
        
        // Indent the list level again.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        builder.writeln("MHTML");
        builder.writeln("Plain text");
        
        // Outdent the list level again.
        builder.getListFormat().listOutdent();
        builder.writeln("Doing many other things!");
        
        // End the numbered list.
        builder.getListFormat().removeNumbers();
        builder.writeln();
        
        builder.writeln("Aspose.Words main advantages are:");
        builder.writeln();
        
        // Start a bulleted list with default formatting.
        builder.getListFormat().applyBulletDefault();
        builder.writeln("Great performance");
        builder.writeln("High reliability");
        builder.writeln("Quality code and working");
        builder.writeln("Wide variety of features");
        builder.writeln("Easy to understand API");
        
        // End the bulleted list.
        builder.getListFormat().removeNumbers();
        
        builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.ApplyDefaultBulletsAndNumbers.doc");
      • applyNumberDefault

        public void applyNumberDefault()
        Starts a new default numbered list and applies it to the paragraph.

        This is a shortcut method that creates a new list using the default numbered template, applies it to the paragraph and selects the 1st list level.

        See Also:
        List, removeNumbers(), ListLevelNumber

        Example:

        Shows how to apply default bulleted or numbered list formatting to paragraphs when using DocumentBuilder.
        DocumentBuilder builder = new DocumentBuilder();
        
        builder.writeln("Aspose.Words allows:");
        builder.writeln();
        
        // Start a numbered list with default formatting.
        builder.getListFormat().applyNumberDefault();
        builder.writeln("Opening documents from different formats:");
        
        // Go to second list level, add more text.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        
        // Outdent to the first list level.
        builder.getListFormat().listOutdent();
        builder.writeln("Processing documents");
        builder.writeln("Saving documents in different formats:");
        
        // Indent the list level again.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        builder.writeln("MHTML");
        builder.writeln("Plain text");
        
        // Outdent the list level again.
        builder.getListFormat().listOutdent();
        builder.writeln("Doing many other things!");
        
        // End the numbered list.
        builder.getListFormat().removeNumbers();
        builder.writeln();
        
        builder.writeln("Aspose.Words main advantages are:");
        builder.writeln();
        
        // Start a bulleted list with default formatting.
        builder.getListFormat().applyBulletDefault();
        builder.writeln("Great performance");
        builder.writeln("High reliability");
        builder.writeln("Quality code and working");
        builder.writeln("Wide variety of features");
        builder.writeln("Easy to understand API");
        
        // End the bulleted list.
        builder.getListFormat().removeNumbers();
        
        builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.ApplyDefaultBulletsAndNumbers.doc");
      • listIndent

        public void listIndent()
        Increases the list level of the current paragraph by one level.

        This method changes the list level and applies formatting properties of the new level.

        In Word documents, lists may consist of up to nine levels. List formatting for each level specifies what bullet or number is used, left indent, space between the bullet and text etc.

        Example:

        Shows how to apply default bulleted or numbered list formatting to paragraphs when using DocumentBuilder.
        DocumentBuilder builder = new DocumentBuilder();
        
        builder.writeln("Aspose.Words allows:");
        builder.writeln();
        
        // Start a numbered list with default formatting.
        builder.getListFormat().applyNumberDefault();
        builder.writeln("Opening documents from different formats:");
        
        // Go to second list level, add more text.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        
        // Outdent to the first list level.
        builder.getListFormat().listOutdent();
        builder.writeln("Processing documents");
        builder.writeln("Saving documents in different formats:");
        
        // Indent the list level again.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        builder.writeln("MHTML");
        builder.writeln("Plain text");
        
        // Outdent the list level again.
        builder.getListFormat().listOutdent();
        builder.writeln("Doing many other things!");
        
        // End the numbered list.
        builder.getListFormat().removeNumbers();
        builder.writeln();
        
        builder.writeln("Aspose.Words main advantages are:");
        builder.writeln();
        
        // Start a bulleted list with default formatting.
        builder.getListFormat().applyBulletDefault();
        builder.writeln("Great performance");
        builder.writeln("High reliability");
        builder.writeln("Quality code and working");
        builder.writeln("Wide variety of features");
        builder.writeln("Easy to understand API");
        
        // End the bulleted list.
        builder.getListFormat().removeNumbers();
        
        builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.ApplyDefaultBulletsAndNumbers.doc");
      • listOutdent

        public void listOutdent()
        Decreases the list level of the current paragraph by one level.

        This method changes the list level and applies formatting properties of the new level.

        In Word documents, lists may consist of up to nine levels. List formatting for each level specifies what bullet or number is used, left indent, space between the bullet and text etc.

        Example:

        Shows how to apply default bulleted or numbered list formatting to paragraphs when using DocumentBuilder.
        DocumentBuilder builder = new DocumentBuilder();
        
        builder.writeln("Aspose.Words allows:");
        builder.writeln();
        
        // Start a numbered list with default formatting.
        builder.getListFormat().applyNumberDefault();
        builder.writeln("Opening documents from different formats:");
        
        // Go to second list level, add more text.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        
        // Outdent to the first list level.
        builder.getListFormat().listOutdent();
        builder.writeln("Processing documents");
        builder.writeln("Saving documents in different formats:");
        
        // Indent the list level again.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        builder.writeln("MHTML");
        builder.writeln("Plain text");
        
        // Outdent the list level again.
        builder.getListFormat().listOutdent();
        builder.writeln("Doing many other things!");
        
        // End the numbered list.
        builder.getListFormat().removeNumbers();
        builder.writeln();
        
        builder.writeln("Aspose.Words main advantages are:");
        builder.writeln();
        
        // Start a bulleted list with default formatting.
        builder.getListFormat().applyBulletDefault();
        builder.writeln("Great performance");
        builder.writeln("High reliability");
        builder.writeln("Quality code and working");
        builder.writeln("Wide variety of features");
        builder.writeln("Easy to understand API");
        
        // End the bulleted list.
        builder.getListFormat().removeNumbers();
        
        builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.ApplyDefaultBulletsAndNumbers.doc");
      • removeNumbers

        public void removeNumbers()
        Removes numbers or bullets from the current paragraph and sets list level to zero.

        Calling this method is equivalent to setting the List property to null.

        Example:

        Shows how to apply default bulleted or numbered list formatting to paragraphs when using DocumentBuilder.
        DocumentBuilder builder = new DocumentBuilder();
        
        builder.writeln("Aspose.Words allows:");
        builder.writeln();
        
        // Start a numbered list with default formatting.
        builder.getListFormat().applyNumberDefault();
        builder.writeln("Opening documents from different formats:");
        
        // Go to second list level, add more text.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        
        // Outdent to the first list level.
        builder.getListFormat().listOutdent();
        builder.writeln("Processing documents");
        builder.writeln("Saving documents in different formats:");
        
        // Indent the list level again.
        builder.getListFormat().listIndent();
        builder.writeln("DOC");
        builder.writeln("PDF");
        builder.writeln("HTML");
        builder.writeln("MHTML");
        builder.writeln("Plain text");
        
        // Outdent the list level again.
        builder.getListFormat().listOutdent();
        builder.writeln("Doing many other things!");
        
        // End the numbered list.
        builder.getListFormat().removeNumbers();
        builder.writeln();
        
        builder.writeln("Aspose.Words main advantages are:");
        builder.writeln();
        
        // Start a bulleted list with default formatting.
        builder.getListFormat().applyBulletDefault();
        builder.writeln("Great performance");
        builder.writeln("High reliability");
        builder.writeln("Quality code and working");
        builder.writeln("Wide variety of features");
        builder.writeln("Easy to understand API");
        
        // End the bulleted list.
        builder.getListFormat().removeNumbers();
        
        builder.getDocument().save(getMyDir() + "\\Artifacts\\Lists.ApplyDefaultBulletsAndNumbers.doc");

        Example:

        Removes bullets and numbering from all paragraphs in the main text of a section.
        Body body = doc.getFirstSection().getBody();
        
        for (Paragraph paragraph : body.getParagraphs())
            paragraph.getListFormat().removeNumbers();