com.aspose.words.List
java.lang.Object
com.aspose.words.List
public class List
To learn more, visit the Working with Lists documentation article. 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 To create a new list, use the Add methods of the To modify formatting of a list, use To apply or remove list formatting from a paragraph, use Example: Example: Example:
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");
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");
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");
| Property Getters/Setters Summary | ||
|---|---|---|
DocumentBase | getDocument() | |
| Gets the owner document. | ||
boolean | isListStyleDefinition() | |
Returns true if this list is a definition of a list style.
|
||
boolean | isListStyleReference() | |
Returns true if this list is a reference to a list style.
|
||
boolean | isMultiLevel() | |
Returns true when the list contains 9 levels; false when 1 level.
|
||
boolean | isRestartAtEachSection() | |
void | isRestartAtEachSection(boolean value) | |
Specifies whether list should be restarted at each section.
Default value is false.
|
||
int | getListId() | |
| Gets the unique identifier of the list. | ||
ListLevelCollection | getListLevels() | |
| Gets the collection of list levels for this list. | ||
Style | getStyle() | |
| Gets the list style that this list references or defines. | ||
| Method Summary | ||
|---|---|---|
int | compareTo(List other) | |
| Compares the specified list to the current list. | ||
boolean | equals(List list) | |
| Compares with the specified list. | ||
boolean | equals(java.lang.Object obj) | |
| Determines whether the specified object is equal in value to the current object. | ||
int | hashCode() | |
| Calculates hash code for this list object. | ||
boolean | hasSameTemplate(List other) | |
| Returns true if the current list and the given list are created from the same template. | ||
| Property Getters/Setters Detail |
|---|
getDocument | |
public DocumentBase getDocument() | |
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() | |
true if this list is a definition of a list style.
When this property is true, the
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");isListStyleReference | |
public boolean isListStyleReference() | |
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");isMultiLevel | |
public boolean isMultiLevel() | |
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) | |
false.
This option is supported only in RTF, DOC and DOCX document formats.
This option will be written to DOCX only if
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() | |
You do not normally need to use this property. But if you use it, you normally do so
in conjunction with the
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() | |
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() | |
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 true.
A list could be a definition of a list style, in this case 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) | |
equals | |
public boolean equals(List list) | |
equals | |
public boolean equals(java.lang.Object obj) | |
hashCode | |
public int hashCode() | |
hasSameTemplate | |
public boolean hasSameTemplate(List other) | |
Example:
Shows how to define lists with the same ListDefId.Document doc = new Document(getMyDir() + "Different lists.docx"); Assert.assertTrue(doc.getLists().get(0).hasSameTemplate(doc.getLists().get(1))); Assert.assertFalse(doc.getLists().get(1).hasSameTemplate(doc.getLists().get(2)));