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
| Requirement | Detail |
|---|---|
| Java | 8 or later |
| Dependency | The package from Installation |
| Import | import com.aspose.words.*; |
| Code | The 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: BuildBulleted 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: 2Tips and Best Practices
- Call
removeNumberswhen the list ends, otherwise the next paragraphs stay in the list. ListTemplatehas bullet and number templates, for exampleBULLET_DEFAULTandNUMBER_ARABIC_DOT.ListFormat.getListLevelNumberreturns the level of a paragraph, from 0 to 8.
Common Issues
| Issue | Cause | Fix |
|---|---|---|
| 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 / Method | Description |
|---|---|
ListFormat | Allows to control what list formatting is applied to a paragraph. |
ListCollection | Stores and manages formatting of bulleted and numbered lists used in a document. |
ListTemplate | Specifies one of the predefined list formats available in Microsoft Word. |
DocumentBuilder.getListFormat() | Returns an object that represents current list formatting properties. |
Related Guides
- Working with Text
- Working with Tables
- Bookmarks
- How to Create Bulleted and Numbered Lists in a Word Document in Java (knowledge base)