java.lang.Objectcom.aspose.words.List
public class 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 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) | |
int | hashCode() | |
Calculates hash code for this list object. |
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() |
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() |
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() |
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) |
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
A list could be a definition of a list style, in this case
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() |