Lists

Overview

This guide shows how to create bulleted, numbered and multilevel lists in a Word document with Aspose.Words FOSS for Java. Bulleted and numbered lists in a Word document are controlled through the ListFormat of a paragraph, which DocumentBuilder.getListFormat returns for the current position. applyBulletDefault and applyNumberDefault start a list, listIndent and listOutdent change the level of the current paragraph and removeNumbers ends the list. A list can also be created from a predefined template with ListCollection.add and ListTemplate. This page builds a multilevel numbered list and reads the levels back. Both examples were compiled and run against the published package on Java 8, 17 and 21.


Prerequisites

RequirementDetail
Java8 or later
DependencyThe package from Installation
Importimport com.aspose.words.*;
CodeThe examples are statements. Put them in a method that declares throws Exception.

Build a Multilevel Numbered List

Create a list with doc.getLists().add(ListTemplate.NUMBER_ARABIC_DOT), make it the current list with setList, and write paragraphs. listIndent moves the following paragraphs one level down and listOutdent moves back. The run printed level 0 for Prepare, level 1 for the two indented items and level 0 for Build.

import com.aspose.words.*;

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

List list = doc.getLists().add(ListTemplate.NUMBER_ARABIC_DOT);
builder.getListFormat().setList(list);
builder.writeln("Prepare");
builder.getListFormat().listIndent();
builder.writeln("Check the prerequisites");
builder.writeln("Download the package");
builder.getListFormat().listOutdent();
builder.writeln("Build");
builder.getListFormat().removeNumbers();

NodeCollection paragraphs = doc.getChildNodes(NodeType.PARAGRAPH, true);
for (int i = 0; i < paragraphs.getCount(); i++) {
    Paragraph paragraph = (Paragraph) paragraphs.get(i);
    if (paragraph.getListFormat().isListItem()) {
        System.out.println("level " + paragraph.getListFormat().getListLevelNumber() + ": " + paragraph.getText().trim());
    }
}

The program printed:

level 0: Prepare
level 1: Check the prerequisites
level 1: Download the package
level 0: Build

Bulleted and Numbered Lists With the Defaults

applyBulletDefault starts a default bulleted list and applyNumberDefault a default numbered one; removeNumbers ends the list for the next paragraph. The example writes two bulleted and two numbered paragraphs, saves and reloads the document and counted 4 list items in 2 lists.

import com.aspose.words.*;

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

builder.getListFormat().applyBulletDefault();
builder.writeln("Install the package");
builder.writeln("Write the code");
builder.getListFormat().removeNumbers();

builder.getListFormat().applyNumberDefault();
builder.writeln("First step");
builder.writeln("Second step");
builder.getListFormat().removeNumbers();

doc.save("lists.docx");

Document reloaded = new Document("lists.docx");
int items = 0;
NodeCollection paragraphs = reloaded.getChildNodes(NodeType.PARAGRAPH, true);
for (int i = 0; i < paragraphs.getCount(); i++) {
    if (((Paragraph) paragraphs.get(i)).getListFormat().isListItem()) {
        items++;
    }
}
System.out.println("List items: " + items);
System.out.println("Lists in the document: " + reloaded.getLists().getCount());

The program printed:

List items: 4
Lists in the document: 2

Tips and Best Practices

  • Call removeNumbers when the list ends, otherwise the next paragraphs stay in the list.
  • ListTemplate has bullet and number templates, for example BULLET_DEFAULT and NUMBER_ARABIC_DOT.
  • ListFormat.getListLevelNumber returns the level of a paragraph, from 0 to 8.

Common Issues

IssueCauseFix
The compiler reports cannot find symbol for Document.The com.aspose.words package is not imported.Add import com.aspose.words.*;.
The compiler reports an unreported exception.The Document constructors, Document.save and some other methods declare throws Exception.Declare it on the calling method or catch it.
Paragraphs after the list are still numbered.The list was not ended.Call getListFormat().removeNumbers().

FAQ

How do I start a bulleted list?

Call applyBulletDefault on the ListFormat of the DocumentBuilder.

How do I make a nested item?

Call listIndent before writing the paragraph, and listOutdent to go back.

How do I tell whether a paragraph is a list item?

ListFormat.isListItem returns true when the paragraph has bulleted or numbered formatting.


API Reference Summary

Class / MethodDescription
ListFormatAllows to control what list formatting is applied to a paragraph.
ListCollectionStores and manages formatting of bulleted and numbered lists used in a document.
ListTemplateSpecifies one of the predefined list formats available in Microsoft Word.
DocumentBuilder.getListFormat()Returns an object that represents current list formatting properties.

Related Guides

See Also