com.aspose.words

Classes

Exceptions

Constants

com.aspose.words

Class List

java.lang.Object
- com.aspose.words.List

All Implemented Interfaces:
java.lang.Cloneable, java.lang.Comparable
```
public class List extends java.lang.Object
```

Represents formatting of a 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 List object always belongs to the ListCollection collection.

To create a new list, use the Add methods of the ListCollection collection.

To modify formatting of a list, use ListLevel objects found in the ListLevels collection.

To apply or remove list formatting from a paragraph, use ListFormat.

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

// Insert text at each of the 9 indent levels
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));

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

doc.save(getArtifactsDir() + "Lists.SpecifyListLevel.docx");

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

doc.save(getArtifactsDir() + "Lists.RestartNumberingUsingListCopy.docx");

Example:

Shows how to apply custom list formatting to paragraphs when using DocumentBuilder.

Document doc = new Document();

// Create a list based on one of the Microsoft Word list templates
List list = doc.getLists().add(ListTemplate.NUMBER_DEFAULT);

// Completely customize one list level
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);

// Customize another list level
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);
listLevel.setNumberFormat("\uf0af"); // A bullet that looks like a star
listLevel.setTrailingCharacter(ListTrailingCharacter.SPACE);
listLevel.setNumberPosition(144.0);

// Now add some text that uses the list that we created
// It does not matter when to customize the list - before or after adding the paragraphs
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");

See Also:: ListCollection, ListLevel, ListFormat

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(booleanvalue)`
	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)`
`int`	Compares the specified list to the current list.
`boolean`	`equals(List list)`
`boolean`	Compares with the specified list.
`boolean`	`equals(java.lang.Object obj)`
`boolean`
`int`	`hashCode()`
`int`	Calculates hash code for this list object.

Property Getters/Setters Detail

getDocument

public DocumentBase getDocument()

Gets the owner document.

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()

Returns true if this list is a definition of a list style.

When this property is true, the Style property returns the list style that this list defines.

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

// Create a new list style
// List formatting associated with this list style is default numbered
Style listStyle = doc.getStyles().add(StyleType.LIST, "MyListStyle");

// This list defines the formatting of the list style
// Note this list can not be used directly to apply formatting to paragraphs (see below)
List list1 = listStyle.getList();

// Check some basic rules about the list that defines a list style
Assert.assertTrue(list1.isListStyleDefinition());
Assert.assertFalse(list1.isListStyleReference());
Assert.assertTrue(list1.isMultiLevel());
Assert.assertEquals(listStyle, list1.getStyle());

// Modify formatting of the list style to our liking
for (ListLevel level : list1.getListLevels()) {
    level.getFont().setName("Verdana");
    level.getFont().setColor(Color.BLUE);
    level.getFont().setBold(true);
}

// Add some text to our document and use the list style
DocumentBuilder builder = new DocumentBuilder(doc);

builder.writeln("Using list style first time:");

// This creates a list based on the list style
List list2 = doc.getLists().add(listStyle);

// Check some basic rules about the list that references a list style
Assert.assertFalse(list2.isListStyleDefinition());
Assert.assertTrue(list2.isListStyleReference());
Assert.assertEquals(listStyle, list2.getStyle());

// Apply the list that references the list style
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");

See Also:: Style, IsListStyleReference

isListStyleReference

public boolean isListStyleReference()

Returns 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();

// Create a new list style
// List formatting associated with this list style is default numbered
Style listStyle = doc.getStyles().add(StyleType.LIST, "MyListStyle");

// This list defines the formatting of the list style
// Note this list can not be used directly to apply formatting to paragraphs (see below)
List list1 = listStyle.getList();

// Check some basic rules about the list that defines a list style
Assert.assertTrue(list1.isListStyleDefinition());
Assert.assertFalse(list1.isListStyleReference());
Assert.assertTrue(list1.isMultiLevel());
Assert.assertEquals(listStyle, list1.getStyle());

// Modify formatting of the list style to our liking
for (ListLevel level : list1.getListLevels()) {
    level.getFont().setName("Verdana");
    level.getFont().setColor(Color.BLUE);
    level.getFont().setBold(true);
}

// Add some text to our document and use the list style
DocumentBuilder builder = new DocumentBuilder(doc);

builder.writeln("Using list style first time:");

// This creates a list based on the list style
List list2 = doc.getLists().add(listStyle);

// Check some basic rules about the list that references a list style
Assert.assertFalse(list2.isListStyleDefinition());
Assert.assertTrue(list2.isListStyleReference());
Assert.assertEquals(listStyle, list2.getStyle());

// Apply the list that references the list style
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");

See Also:: Style, IsListStyleDefinition

isMultiLevel

public boolean isMultiLevel()

Returns 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();

// Create a new list style
// List formatting associated with this list style is default numbered
Style listStyle = doc.getStyles().add(StyleType.LIST, "MyListStyle");

// This list defines the formatting of the list style
// Note this list can not be used directly to apply formatting to paragraphs (see below)
List list1 = listStyle.getList();

// Check some basic rules about the list that defines a list style
Assert.assertTrue(list1.isListStyleDefinition());
Assert.assertFalse(list1.isListStyleReference());
Assert.assertTrue(list1.isMultiLevel());
Assert.assertEquals(listStyle, list1.getStyle());

// Modify formatting of the list style to our liking
for (ListLevel level : list1.getListLevels()) {
    level.getFont().setName("Verdana");
    level.getFont().setColor(Color.BLUE);
    level.getFont().setBold(true);
}

// Add some text to our document and use the list style
DocumentBuilder builder = new DocumentBuilder(doc);

builder.writeln("Using list style first time:");

// This creates a list based on the list style
List list2 = doc.getLists().add(listStyle);

// Check some basic rules about the list that references a list style
Assert.assertFalse(list2.isListStyleDefinition());
Assert.assertTrue(list2.isListStyleReference());
Assert.assertEquals(listStyle, list2.getStyle());

// Apply the list that references the list style
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)

Specifies whether list should be restarted at each section. Default value is false.

This option is supported only in RTF, DOC and DOCX document formats.

This option will be written to DOCX only if OoxmlCompliance is higher then OoxmlCompliance.ECMA_376_2006.

Example:

Shows how to specify that the list has to be restarted at each section.

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

doc.getLists().add(ListTemplate.NUMBER_DEFAULT);

List list = doc.getLists().get(0);

// Set true to specify that the list has to be restarted at each section
list.isRestartAtEachSection(doRestartListAtEachSection);

// IsRestartAtEachSection will be written only if compliance is higher then 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);

getListId

public int getListId()

Gets the unique identifier of the list.

You do not normally need to use this property. But if you use it, you normally do so in conjunction with the ListCollection.getListByListId(int) method to find a list by its identifier.

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 bulleted or numbered.

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()

Gets the collection of list levels for this list.

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

// Create a list based on one of the Microsoft Word list templates
List list = doc.getLists().add(ListTemplate.NUMBER_DEFAULT);

// Completely customize one list level
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);

// Customize another list level
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);
listLevel.setNumberFormat("\uf0af"); // A bullet that looks like a star
listLevel.setTrailingCharacter(ListTrailingCharacter.SPACE);
listLevel.setNumberPosition(144.0);

// Now add some text that uses the list that we created
// It does not matter when to customize the list - before or after adding the paragraphs
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()

Gets the list style that this list references or defines.

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 IsListStyleReference will be true.

A list could be a definition of a list style, in this case IsListStyleDefinition will be 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();

// Create a new list style
// List formatting associated with this list style is default numbered
Style listStyle = doc.getStyles().add(StyleType.LIST, "MyListStyle");

// This list defines the formatting of the list style
// Note this list can not be used directly to apply formatting to paragraphs (see below)
List list1 = listStyle.getList();

// Check some basic rules about the list that defines a list style
Assert.assertTrue(list1.isListStyleDefinition());
Assert.assertFalse(list1.isListStyleReference());
Assert.assertTrue(list1.isMultiLevel());
Assert.assertEquals(listStyle, list1.getStyle());

// Modify formatting of the list style to our liking
for (ListLevel level : list1.getListLevels()) {
    level.getFont().setName("Verdana");
    level.getFont().setColor(Color.BLUE);
    level.getFont().setBold(true);
}

// Add some text to our document and use the list style
DocumentBuilder builder = new DocumentBuilder(doc);

builder.writeln("Using list style first time:");

// This creates a list based on the list style
List list2 = doc.getLists().add(listStyle);

// Check some basic rules about the list that references a list style
Assert.assertFalse(list2.isListStyleDefinition());
Assert.assertTrue(list2.isListStyleReference());
Assert.assertEquals(listStyle, list2.getStyle());

// Apply the list that references the list style
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)
```
  Compares the specified list to the current list.
- equals
```
public boolean equals(List list)
```
  Compares with the specified list.
- equals
```
public boolean equals(java.lang.Object obj)
```
- hashCode
```
public int hashCode()
```
  Calculates hash code for this list object.

com.aspose.words

Classes

Interfaces

Exceptions

Constants

Class List

Property Getters/Setters Detail

getDocument

isListStyleDefinition

isListStyleReference

isMultiLevel

isRestartAtEachSection/isRestartAtEachSection

getListId

getListLevels

getStyle

Method Detail

compareTo

equals

equals

hashCode