List class

Represents formatting of a list. To learn more, visit the Working with Lists documentation article.

Remarks

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 List.list_levels collection.

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

Properties

Name	Description
document	Gets the owner document.
is_list_style_definition	Returns `True` if this list is a definition of a list style.
is_list_style_reference	Returns `True` if this list is a reference to a list style.
is_multi_level	Returns `True` when the list contains 9 levels; `False` when 1 level.
is_restart_at_each_section	Specifies whether list should be restarted at each section. Default value is `False`.
list_id	Gets the unique identifier of the list.
list_levels	Gets the collection of list levels for this list.
style	Gets the list style that this list references or defines.

Methods

Name	Description
compare_to(obj)	Compares the specified object to the current object.
compare_to(other)	Compares the specified list to the current list.
equals(list)	Compares with the specified list.
has_same_template(other)	Returns true if the current list and the given list are created from the same template.

Examples

Shows how to work with list levels.

doc = aw.Document()
builder = aw.DocumentBuilder(doc)
self.assertFalse(builder.list_format.is_list_item)
# 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 "list_format" 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.list_format.list = doc.lists.add(aw.lists.ListTemplate.NUMBER_DEFAULT)
self.assertTrue(builder.list_format.is_list_item)
# By setting the "list_level_number" 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 i in range(9):
    builder.list_format.list_level_number = i
    builder.writeln(f'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.list_format.list = doc.lists.add(aw.lists.ListTemplate.BULLET_DEFAULT)
for i in range(9):
    builder.list_format.list_level_number = i
    builder.writeln(f'Level {i}')
# We can disable list formatting to not format any subsequent paragraphs as lists by un-setting the "List" flag.
builder.list_format.list = None
self.assertFalse(builder.list_format.is_list_item)
doc.save(ARTIFACTS_DIR + 'Lists.specify_list_level.docx')

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

doc = aw.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 "list_format" 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 = doc.lists.add(aw.lists.ListTemplate.NUMBER_DEFAULT)
list_level = list.list_levels[0]
list_level.font.color = aspose.pydrawing.Color.red
list_level.font.size = 24
list_level.number_style = aw.NumberStyle.ORDINAL_TEXT
list_level.start_at = 21
list_level.number_format = '\x00'
list_level.number_position = -36
list_level.text_position = 144
list_level.tab_position = 144
list_level = list.list_levels[1]
list_level.alignment = aw.lists.ListLevelAlignment.RIGHT
list_level.number_style = aw.NumberStyle.BULLET
list_level.font.name = 'Wingdings'
list_level.font.color = aspose.pydrawing.Color.blue
list_level.font.size = 24
# This NumberFormat value will create star-shaped bullet list symbols.
list_level.number_format = '\uf0af'
list_level.trailing_character = aw.lists.ListTrailingCharacter.SPACE
list_level.number_position = 144
# Create paragraphs and apply both list levels of our custom list formatting to them.
builder = aw.DocumentBuilder(doc)
builder.list_format.list = list
builder.writeln('The quick brown fox...')
builder.writeln('The quick brown fox...')
builder.list_format.list_indent()
builder.writeln('jumped over the lazy dog.')
builder.writeln('jumped over the lazy dog.')
builder.list_format.list_outdent()
builder.writeln('The quick brown fox...')
builder.list_format.remove_numbers()
builder.document.save(ARTIFACTS_DIR + 'Lists.create_custom_list.docx')

Shows how to restart numbering in a list by copying a list.

doc = aw.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 "list_format" 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.
list1 = doc.lists.add(aw.lists.ListTemplate.NUMBER_ARABIC_PARENTHESIS)
list1.list_levels[0].font.color = aspose.pydrawing.Color.red
list1.list_levels[0].alignment = aw.lists.ListLevelAlignment.RIGHT
# Apply our list to some paragraphs.
builder = aw.DocumentBuilder(doc)
builder.writeln('List 1 starts below:')
builder.list_format.list = list1
builder.writeln('Item 1')
builder.writeln('Item 2')
builder.list_format.remove_numbers()
# 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.
list2 = doc.lists.add_copy(list1)
list2.list_levels[0].font.color = aspose.pydrawing.Color.blue
list2.list_levels[0].start_at = 10
# Apply the second list to new paragraphs.
builder.writeln('List 2 starts below:')
builder.list_format.list = list2
builder.writeln('Item 1')
builder.writeln('Item 2')
builder.list_format.remove_numbers()
doc.save(ARTIFACTS_DIR + 'Lists.restart_numbering_using_list_copy.docx')

List class

List class

Remarks

Properties

Methods

Examples

See Also