Aspose::Words::Lists Namespace Reference

The Aspose.Words.Lists namespace contains classes for working with bulleted and numbered lists defined in a document.

Classes
class	List
	Represents formatting of a list. More...
class	ListCollection
	Stores and manages formatting of bulleted and numbered lists used in a document. More...
class	ListFormat
	Allows to control what list formatting is applied to a paragraph. More...
class	ListLabel
	Defines properties specific to a list label. More...
class	ListLevel
	Defines formatting for a list level. More...
class	ListLevelCollection
	A collection of list formatting for each level in a list. More...

Enumerations
enum class	ListLevelAlignment
	Specifies alignment for the list number or bullet. More...
enum class	ListTemplate
	Specifies one of the predefined list formats available in Microsoft Word. More...
enum class	ListTrailingCharacter
	Specifies the character that separates the list label from the text of the paragraph. More...

Enumeration Type Documentation

ListLevelAlignment

enum Aspose::Words::Lists::ListLevelAlignment

strong

Specifies alignment for the list number or bullet.

Used as a value for the Alignment property.

Examples

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

auto doc = MakeObject<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.
SharedPtr<List> list = doc->get_Lists()->Add(ListTemplate::NumberDefault);
 
SharedPtr<ListLevel> 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 = MakeObject<DocumentBuilder>(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(ArtifactsDir + u"Lists.CreateCustomList.docx");

Enumerator
Left	The list label is aligned to the left of the number position.
Center	The list label is centered at the number position.
Right	This list label is aligned to the right of the number position.

ListTemplate

enum Aspose::Words::Lists::ListTemplate

strong

Specifies one of the predefined list formats available in Microsoft Word.

A list template value is used as a parameter into the Add() method.

Aspose.Words list templates correspond to the 21 list templates available in the Bullets and Numbering dialog box in Microsoft Word 2003.

Examples

Shows how to work with list levels.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(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 (int i = 0; i < 9; i++)
{
    builder->get_ListFormat()->set_ListLevelNumber(i);
    builder->Writeln(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 (int i = 0; i < 9; i++)
{
    builder->get_ListFormat()->set_ListLevelNumber(i);
    builder->Writeln(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(ArtifactsDir + u"Lists.SpecifyListLevel.docx");

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

auto doc = MakeObject<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.
SharedPtr<List> 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 = MakeObject<DocumentBuilder>(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.
SharedPtr<List> 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(ArtifactsDir + u"Lists.RestartNumberingUsingListCopy.docx");

Shows how to create a document that contains all outline headings list templates.

void OutlineHeadingTemplates()
{
    auto doc = MakeObject<Document>();
    auto builder = MakeObject<DocumentBuilder>(doc);
 
    SharedPtr<List> list = doc->get_Lists()->Add(ListTemplate::OutlineHeadingsArticleSection);
    AddOutlineHeadingParagraphs(builder, list, u"Aspose.Words Outline - \"Article Section\"");
 
    list = doc->get_Lists()->Add(ListTemplate::OutlineHeadingsLegal);
    AddOutlineHeadingParagraphs(builder, list, u"Aspose.Words Outline - \"Legal\"");
 
    builder->InsertBreak(BreakType::PageBreak);
 
    list = doc->get_Lists()->Add(ListTemplate::OutlineHeadingsNumbers);
    AddOutlineHeadingParagraphs(builder, list, u"Aspose.Words Outline - \"Numbers\"");
 
    list = doc->get_Lists()->Add(ListTemplate::OutlineHeadingsChapter);
    AddOutlineHeadingParagraphs(builder, list, u"Aspose.Words Outline - \"Chapters\"");
 
    doc->Save(ArtifactsDir + u"Lists.OutlineHeadingTemplates.docx");
}
 
static void AddOutlineHeadingParagraphs(SharedPtr<DocumentBuilder> builder, SharedPtr<List> list, String title)
{
    builder->get_ParagraphFormat()->ClearFormatting();
    builder->Writeln(title);
 
    for (int i = 0; i < 9; i++)
    {
        builder->get_ListFormat()->set_List(list);
        builder->get_ListFormat()->set_ListLevelNumber(i);
 
        String styleName = String(u"Heading ") + (i + 1);
        builder->get_ParagraphFormat()->set_StyleName(styleName);
        builder->Writeln(styleName);
    }
 
    builder->get_ListFormat()->RemoveNumbers();
}

Enumerator
BulletDefault	Default bulleted list with 9 levels. Bullet of the first level is a disc, bullet of the second level is a circle, bullet of the third level is a square. Then formatting repeats for the remaining levels. Each level is indented to the right by 0.25" relative to the previous level. Corresponds to the 1st bulleted list template in the Bullets and Numbering dialog box in Microsoft Word.
BulletDisk	Same as BulletDefault. Corresponds to the 1st bulleted list template in the Bullets and Numbering dialog box in Microsoft Word.
BulletCircle	The bullet of the first level is a circle. The remaining levels are same as in BulletDefault. Corresponds to the 2nd bulleted list template in the Bullets and Numbering dialog box in Microsoft Word.
BulletSquare	The bullet of the first level is a square. The remaining levels are same as in BulletDefault. Corresponds to the 3rd bulleted list template in the Bullets and Numbering dialog box in Microsoft Word.
BulletDiamonds	The bullet of the first level is a 4-diamond Wingding character. The remaining levels are same as in BulletDefault. Corresponds to the 5th bulleted list template in the Bullets and Numbering dialog box in Microsoft Word.
BulletArrowHead	The bullet of the first level is an arrow head Wingding character. The remaining levels are same as in BulletDefault. Corresponds to the 6th bulleted list template in the Bullets and Numbering dialog box in Microsoft Word.
BulletTick	The bullet of the first level is a tick Wingding character. The remaining levels are same as in BulletDefault. Corresponds to the 7th bulleted list template in the Bullets and Numbering dialog box in Microsoft Word.
NumberDefault	Default numbered list with 9 levels. Arabic numbering (1., 2., 3., ...) for the first level, lowecase letter numbering (a., b., c., ...) for the second level, lowercase roman numbering (i., ii., iii., ...) for the third level. Then formatting repeats for the remaining levels. Each level is indented to the right by 0.25" relative to the previous level. Corresponds to the 1st numbered list template in the Bullets and Numbering dialog box in Microsoft Word.
NumberArabicDot	Same as NumberDefault. Corresponds to the 1st numbered list template in the Bullets and Numbering dialog box in Microsoft Word.
NumberArabicParenthesis	The number of the first level is "1)". The remaining levels are same as in NumberDefault. Corresponds to the 2nd numbered list template in the Bullets and Numbering dialog box in Microsoft Word.
NumberUppercaseRomanDot	The number of the first level is "I.". The remaining levels are same as in NumberDefault. Corresponds to the 3rd numbered list template in the Bullets and Numbering dialog box in Microsoft Word.
NumberUppercaseLetterDot	The number of the first level is "A.". The remaining levels are same as in NumberDefault. Corresponds to the 4th numbered list template in the Bullets and Numbering dialog box in Microsoft Word.
NumberLowercaseLetterParenthesis	The number of the first level is "a)". The remaining levels are same as in NumberDefault. Corresponds to the 5th numbered list template in the Bullets and Numbering dialog box in Microsoft Word.
NumberLowercaseLetterDot	The number of the first level is "a.". The remaining levels are same as in NumberDefault. Corresponds to the 6th numbered list template in the Bullets and Numbering dialog box in Microsoft Word.
NumberLowercaseRomanDot	The number of the first level is "i.". The remaining levels are same as in NumberDefault. Corresponds to the 7th numbered list template in the Bullets and Numbering dialog box in Microsoft Word.
OutlineNumbers	An outline list with levels numbered "1), a), i), (1), (a), (i), 1., a., i.". Corresponds to the 1st outline list template in the Bullets and Numbering dialog box in Microsoft Word.
OutlineLegal	An outline list with levels are numbered "1., 1.1., 1.1.1, ...". Corresponds to the 2nd outline list template in the Bullets and Numbering dialog box in Microsoft Word.
OutlineBullets	An outline lists with various bullets for different levels. Corresponds to the 3rd outline list template in the Bullets and Numbering dialog box in Microsoft Word.
OutlineHeadingsArticleSection	An outline list with levels linked to Heading styles. Corresponds to the 4th outline list template in the Bullets and Numbering dialog box in Microsoft Word.
OutlineHeadingsLegal	An outline list with levels linked to Heading styles. Corresponds to the 5th outline list template in the Bullets and Numbering dialog box in Microsoft Word.
OutlineHeadingsNumbers	An outline list with levels linked to Heading styles. Corresponds to the 6th outline list template in the Bullets and Numbering dialog box in Microsoft Word.
OutlineHeadingsChapter	An outline list with levels linked to Heading styles. Corresponds to the 7th outline list template in the Bullets and Numbering dialog box in Microsoft Word.

ListTrailingCharacter

enum Aspose::Words::Lists::ListTrailingCharacter

strong

Specifies the character that separates the list label from the text of the paragraph.

Used as a value for the TrailingCharacter property.

Examples

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

auto doc = MakeObject<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.
SharedPtr<List> list = doc->get_Lists()->Add(ListTemplate::NumberDefault);
 
SharedPtr<ListLevel> 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 = MakeObject<DocumentBuilder>(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(ArtifactsDir + u"Lists.CreateCustomList.docx");

Enumerator
Tab	A tab character is placed between the list label and text of the paragraph.
Space	A space character is placed between the list label and text of the paragraph.
Nothing	There is no separator character between the list label and text of the paragraph.