## List class Represents formatting of a list. To learn more, visit the [Working with Lists](https://docs.aspose.com/words/cpp/working-with-lists/) documentation article. ```cpp class List : public System::IComparable> ``` ## Methods | Method | Description | | --- | --- | | [CompareTo](./compareto/)(const System::SharedPtr\\&) | Compares the specified object to the current object. | | [CompareTo](./compareto/)(System::SharedPtr\) override | Compares the specified list to the current list. | | [Equals](./equals/)(const System::SharedPtr\\&) | Compares with the specified list. | | [Equals](./equals/)(System::SharedPtr\) override | Determines whether the specified object is equal in value to the current object. | | [get_Document](./get_document/)() const | Gets the owner document. | | [get_IsListStyleDefinition](./get_isliststyledefinition/)() | Returns **true** if this list is a definition of a list style. | | [get_IsListStyleReference](./get_isliststylereference/)() | Returns **true** if this list is a reference to a list style. | | [get_IsMultiLevel](./get_ismultilevel/)() | Returns **true** when the list contains 9 levels; **false** when 1 level. | | [get_IsRestartAtEachSection](./get_isrestartateachsection/)() | Specifies whether list should be restarted at each section. Default value is **false**. | | [get_ListId](./get_listid/)() const | Gets the unique identifier of the list. | | [get_ListLevels](./get_listlevels/)() | Gets the collection of list levels for this list. | | [get_Style](./get_style/)() | Gets the list style that this list references or defines. | | [GetHashCode](./gethashcode/)() const override | Calculates hash code for this list object. | | [GetType](./gettype/)() const override | | | [HasSameTemplate](./hassametemplate/)(const System::SharedPtr\\&) | Returns true if the current list and the given list are created from the same template. | | [Is](./is/)(const System::TypeInfo\&) const override | | | [set_IsRestartAtEachSection](./set_isrestartateachsection/)(bool) | Setter for [Aspose::Words::Lists::List::get_IsRestartAtEachSection](./get_isrestartateachsection/). | | static [Type](./type/)() | | ## 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 [ListLevels](./get_listlevels/) collection. To apply or remove list formatting from a paragraph, use [ListFormat](../listformat/). ## Examples Shows how to work with list levels. ```cpp auto doc = System::MakeObject(); auto builder = System::MakeObject(doc); ASSERT_FALSE(builder->get_ListFormat()->get_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->get_ListFormat()->set_List(doc->get_Lists()->Add(ListTemplate::NumberDefault)); ASSERT_TRUE(builder->get_ListFormat()->get_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 (int32_t i = 0; i < 9; i++) { builder->get_ListFormat()->set_ListLevelNumber(i); builder->Writeln(System::String(u"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->get_ListFormat()->set_List(doc->get_Lists()->Add(ListTemplate::BulletDefault)); for (int32_t i = 0; i < 9; i++) { builder->get_ListFormat()->set_ListLevelNumber(i); builder->Writeln(System::String(u"Level ") + i); } // We can disable list formatting to not format any subsequent paragraphs as lists by un-setting the "List" flag. builder->get_ListFormat()->set_List(nullptr); ASSERT_FALSE(builder->get_ListFormat()->get_IsListItem()); doc->Save(get_ArtifactsDir() + u"Lists.SpecifyListLevel.docx"); ``` Shows how to apply custom list formatting to paragraphs when using [DocumentBuilder](../../aspose.words/documentbuilder/). ```cpp auto doc = System::MakeObject(); // 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. System::SharedPtr list = doc->get_Lists()->Add(ListTemplate::NumberDefault); System::SharedPtr listLevel = list->get_ListLevels()->idx_get(0); listLevel->get_Font()->set_Color(System::Drawing::Color::get_Red()); listLevel->get_Font()->set_Size(24); listLevel->set_NumberStyle(NumberStyle::OrdinalText); listLevel->set_StartAt(21); listLevel->set_NumberFormat(u"\x0000"); listLevel->set_NumberPosition(-36); listLevel->set_TextPosition(144); listLevel->set_TabPosition(144); listLevel = list->get_ListLevels()->idx_get(1); listLevel->set_Alignment(ListLevelAlignment::Right); listLevel->set_NumberStyle(NumberStyle::Bullet); listLevel->get_Font()->set_Name(u"Wingdings"); listLevel->get_Font()->set_Color(System::Drawing::Color::get_Blue()); listLevel->get_Font()->set_Size(24); // This NumberFormat value will create star-shaped bullet list symbols. listLevel->set_NumberFormat(u"\xf0af"); listLevel->set_TrailingCharacter(ListTrailingCharacter::Space); listLevel->set_NumberPosition(144); // Create paragraphs and apply both list levels of our custom list formatting to them. auto builder = System::MakeObject(doc); builder->get_ListFormat()->set_List(list); builder->Writeln(u"The quick brown fox..."); builder->Writeln(u"The quick brown fox..."); builder->get_ListFormat()->ListIndent(); builder->Writeln(u"jumped over the lazy dog."); builder->Writeln(u"jumped over the lazy dog."); builder->get_ListFormat()->ListOutdent(); builder->Writeln(u"The quick brown fox..."); builder->get_ListFormat()->RemoveNumbers(); builder->get_Document()->Save(get_ArtifactsDir() + u"Lists.CreateCustomList.docx"); ``` Shows how to restart numbering in a list by copying a list. ```cpp auto doc = System::MakeObject(); // 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. System::SharedPtr list1 = doc->get_Lists()->Add(ListTemplate::NumberArabicParenthesis); list1->get_ListLevels()->idx_get(0)->get_Font()->set_Color(System::Drawing::Color::get_Red()); list1->get_ListLevels()->idx_get(0)->set_Alignment(ListLevelAlignment::Right); // Apply our list to some paragraphs. auto builder = System::MakeObject(doc); builder->Writeln(u"List 1 starts below:"); builder->get_ListFormat()->set_List(list1); builder->Writeln(u"Item 1"); builder->Writeln(u"Item 2"); builder->get_ListFormat()->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. System::SharedPtr list2 = doc->get_Lists()->AddCopy(list1); list2->get_ListLevels()->idx_get(0)->get_Font()->set_Color(System::Drawing::Color::get_Blue()); list2->get_ListLevels()->idx_get(0)->set_StartAt(10); // Apply the second list to new paragraphs. builder->Writeln(u"List 2 starts below:"); builder->get_ListFormat()->set_List(list2); builder->Writeln(u"Item 1"); builder->Writeln(u"Item 2"); builder->get_ListFormat()->RemoveNumbers(); doc->Save(get_ArtifactsDir() + u"Lists.RestartNumberingUsingListCopy.docx"); ``` ## See Also * Namespace [Aspose::Words::Lists](../) * Library [Aspose.Words for C++](../../)