## List class Represents formatting of a list. To learn more, visit the [Working with Lists](https://docs.aspose.com/words/python-net/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](../listcollection/) collection. To create a new list, use the Add methods of the [ListCollection](../listcollection/) collection. To modify formatting of a list, use [ListLevel](../listlevel/) objects found in the [List.list_levels](./list_levels/) collection. To apply or remove list formatting from a paragraph, use [ListFormat](../listformat/). ### Properties | Name | Description | | --- | --- | | [document](./document/) | Gets the owner document. | | [is_list_style_definition](./is_list_style_definition/) | Returns ``True`` if this list is a definition of a list style. | | [is_list_style_reference](./is_list_style_reference/) | Returns ``True`` if this list is a reference to a list style. | | [is_multi_level](./is_multi_level/) | Returns ``True`` when the list contains 9 levels; ``False`` when 1 level. | | [is_restart_at_each_section](./is_restart_at_each_section/) | Specifies whether list should be restarted at each section. Default value is ``False``. | | [list_id](./list_id/) | Gets the unique identifier of the list. | | [list_levels](./list_levels/) | Gets the collection of list levels for this list. | | [style](./style/) | Gets the list style that this list references or defines. | ### Methods | Name | Description | | --- | --- | |[ compare_to(obj)](./compare_to/#object) | Compares the specified object to the current object. | |[ compare_to(other)](./compare_to/#list) | Compares the specified list to the current list. | |[ equals(list)](./equals/#list) | Compares with the specified list. | |[ has_same_template(other)](./has_same_template/#list) | Returns true if the current list and the given list are created from the same template. | ### Examples Shows how to work with list levels. ```python doc = aw.Document() builder = aw.DocumentBuilder(doc=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 "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.list_format.list = doc.lists.add(list_template=aw.lists.ListTemplate.NUMBER_DEFAULT) self.assertTrue(builder.list_format.is_list_item) # 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. i = 0 while i < 9: builder.list_format.list_level_number = i builder.writeln('Level ' + str(i)) i += 1 # 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(list_template=aw.lists.ListTemplate.BULLET_DEFAULT) i = 0 while i < 9: builder.list_format.list_level_number = i builder.writeln('Level ' + str(i)) i += 1 # 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(file_name=ARTIFACTS_DIR + 'Lists.SpecifyListLevel.docx') ``` Shows how to apply custom list formatting to paragraphs when using DocumentBuilder. ```python 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 "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. doc_list = doc.lists.add(list_template=aw.lists.ListTemplate.NUMBER_DEFAULT) list_level = doc_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 = doc_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=doc) builder.list_format.list = doc_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(file_name=ARTIFACTS_DIR + 'Lists.CreateCustomList.docx') ``` Shows how to restart numbering in a list by copying a list. ```python 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 "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. list1 = doc.lists.add(list_template=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=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(file_name=ARTIFACTS_DIR + 'Lists.RestartNumberingUsingListCopy.docx') ``` ### See Also * module [aspose.words.lists](../) * class [ListCollection](../listcollection/) * class [ListLevel](../listlevel/) * class [ListFormat](../listformat/)