Lists

A List is a page element that contains a list of items arranged in sequential order. There are two types of lists.

• OrderedList - arranges items using numbers as the index.
• UnorderedList - arranges items using bullets as the index.

A list can also have nested sub-lists. There are two types of sub-lists, both of which are child classes of the SubList class.

• OrderedSubList
• UnorderedSubList

List

The List class is the parent of the OrderedList and UnorderedList classes. Refer to the API documentation for a complete list of properties.

OrderedList

The OrderedList class is used to represent an ordered list. Refer to the API documentation for a complete list of properties.

Number Format

The OrderedList class supports number formatting through its constructor.

public OrderedList(float x, float y, float width, float height, Font font, float fontSize, NumberingStyle nStyle)

The NumberingStyle enumeration allows formatting a list's numbering as AlphabeticLowerCase, AlphabeticUpperCase, None, Numeric, RomanLowerCase, and RomanUpperCase.

For example, the following illustrates creating a simple ordered list and specifying that it uses uppercase roman numerals.

document.Pages.Add(new Page(PageSize.Letter));

OrderedList listRoman = new OrderedList(50, 50, 300, 500, Font.Courier, 14, NumberingStyle.RomanUpperCase);

listRoman.Items.Add("Item One");
listRoman.Items.Add("Item Two");
listRoman.Items.Add("Item Three");
listRoman.Items.Add("Item Four");

document.Pages[0].Elements.Add(listRoman);

document.Pages.Add(New Page(PageSize.Letter))

Dim listRoman As New OrderedList(50, 50, 300, 500, Font.Courier, 14, NumberingStyle.RomanUpperCase)

listRoman.Items.Add("Item One")
listRoman.Items.Add("Item Two")
listRoman.Items.Add("Item Three")
listRoman.Items.Add("Item Four")

document.Pages(0).Elements.Add(listRoman)

UnorderedList

The UnorderedList class is used to represent an unordered list. Refer to the API documentation for a complete list of properties.

The following example illustrates a unordered list.

Document document = new Document();

Page page = new Page();
UnorderedList list = new UnorderedList(50, 50, 300, 500);

list.ListItemTopMargin = 5;
list.ListItemBottomMargin = 5;
list.TextColor = RgbColor.BlueViolet;

ListItem item1 = list.Items.Add("List item 1");
item1.Underline = true;
ListItem item2 = list.Items.Add("List item 2");
item2.Underline = true;
ListItem item3 = list.Items.Add("List item 3");
item3.Underline = true;
ListItem item4 = list.Items.Add("List item 4");
item4.Underline = true;

Dim list As New UnorderedList(50, 50, 300, 500)

list.ListItemTopMargin = 5
list.ListItemBottomMargin = 5
list.TextColor = RgbColor.BlueViolet

Dim item1 As ListItem = list.Items.Add("List item 1")
item1.Underline = True
Dim item2 As ListItem = list.Items.Add("List item 2")
item2.Underline = True
Dim item3 As ListItem = list.Items.Add("List item 3")
item3.Underline = True
Dim item4 As ListItem = list.Items.Add("List item 4")
item4.Underline = True

Bullet Format

The UnorderedList has a constructor that allows customizing the list's bullets using the UnorderedListStyle class. For example, the following illustrates using a circle and a square as the list's bullets.

UnorderedSubList subList1 = item1.SubLists.AddUnorderedSubList(UnorderedListStyle.Circle);
subList1.TextColor = RgbColor.HotPink;
ListItem item5 = subList1.Items.Add("Sub-list item 1");
ListItem item6 = subList1.Items.Add("Sub-list item 2");

UnorderedSubList subList2 = item5.SubLists.AddUnorderedSubList(UnorderedListStyle.Square);
subList2.TextColor = RgbColor.DarkGoldenRod;
ListItem item7 = subList2.Items.Add("Second level sub-list item 1");
ListItem item8 = subList2.Items.Add("Second level sub-list item 2");

Dim subList1 As UnorderedSubList = item1.SubLists.AddUnorderedSubList(UnorderedListStyle.Circle)
subList1.TextColor = RgbColor.HotPink
Dim item5 As ListItem = subList1.Items.Add("Sub-list item 1")
Dim item6 As ListItem = subList1.Items.Add("Sub-list item 2")

Dim subList2 As UnorderedSubList = item5.SubLists.AddUnorderedSubList(UnorderedListStyle.Square)
subList2.TextColor = RgbColor.DarkGoldenRod
Dim item7 As ListItem = subList2.Items.Add("Second level sub-list item 1")
Dim item8 As ListItem = subList2.Items.Add("Second level sub-list item 2")

The UnorderedListStyle class also allows creating custom bullets. The following code example illustrates creating a custom bullet.

UnorderedList listCustom = new UnorderedList(50, 250, 300, 500, Font.Courier, 14, new UnorderedListStyle("$", Font.CourierBold));

listCustom.Items.Add("List item 1");
listCustom.Items.Add("List item 2");
listCustom.Items.Add("List item 3");
listCustom.Items.Add("List item 4");

page.Elements.Add(listCustom);

Dim listCustom As New UnorderedList(50, 250, 300, 500, Font.Courier, 14, New UnorderedListStyle("$", Font.CourierBold))

listCustom.Items.Add("List item 1")
listCustom.Items.Add("List item 2")
listCustom.Items.Add("List item 3")
listCustom.Items.Add("List item 4")

Bullet Prefix and Suffix

Both ordered and unordered lists allow adding a prefix and suffix to a bullet. The following example code illustrates adding a prefix and suffix to an ordered list.

OrderedList list = new OrderedList(50, 50, 300, 500);

list.ListItemTopMargin = 5;
list.ListItemBottomMargin = 5;
list.BulletPrefix = "(";
list.BulletSuffix = ")";

Dim list As New OrderedList(50, 50, 300, 500)

list.ListItemTopMargin = 5
list.ListItemBottomMargin = 5
list.BulletPrefix = "("
list.BulletSuffix = ")"

SubList

Lists can have nested sub-lists. The parent class for lists is SubList, while the two child classes are OrderedSubList and UnorderedSubList. Both classes have the same properties for formatting as their parent class.

Add sub-lists to the particular items of a list and not the list itself. The List class has an Items property containing a ListItemList class, a collection of ListItem instances. The ListItem class has a SubLists property containing a SubListList class, a collection of ListItem instances. By adding sub-lists to a ListItem, lists can be n-levels deep.

The following code illustrates adding sub-list elements to an OrderedList, where only the first list item has a sub-list. However, the first list item of the sub-list also has a nested sub-list.

OrderedList list = new OrderedList(50, 50, 300, 500);

list.ListItemTopMargin = 5;
list.ListItemBottomMargin = 5;
list.BulletPrefix = "(";
list.BulletSuffix = ")";
list.TextColor = RgbColor.BlueViolet;

ListItem item1 = list.Items.Add("List item 1");
item1.Underline = true;
ListItem item2 = list.Items.Add("List item 2");
item2.Underline = true;
ListItem item3 = list.Items.Add("List item 3");
item3.Underline = true;
ListItem item4 = list.Items.Add("List item 4");
item4.Underline = true;

OrderedSubList subList1 = item1.SubLists.AddOrderedSubList(NumberingStyle.RomanUpperCase);
subList1.TextColor = RgbColor.HotPink;
ListItem item5 = subList1.Items.Add("Sub-list item 1");
ListItem item6 = subList1.Items.Add("Sub-list item 2");

OrderedSubList subList2 = item5.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase);
subList2.TextColor = RgbColor.DarkGoldenRod;
ListItem item7 = subList2.Items.Add("Second level sub-list item 1");
ListItem item8 = subList2.Items.Add("Second level sub-list item 2");

page.Elements.Add(list);

Dim list As New OrderedList(50, 50, 300, 500)

list.ListItemTopMargin = 5
list.ListItemBottomMargin = 5
list.BulletPrefix = "("
list.BulletSuffix = ")"
list.TextColor = RgbColor.BlueViolet

Dim item1 As ListItem = list.Items.Add("List item 1")
item1.Underline = True
Dim item2 As ListItem = list.Items.Add("List item 2")
item2.Underline = True
Dim item3 As ListItem = list.Items.Add("List item 3")
item3.Underline = True
Dim item4 As ListItem = list.Items.Add("List item 4")
item4.Underline = True

Dim subList1 As OrderedSubList = item1.SubLists.AddOrderedSubList(NumberingStyle.RomanUpperCase)
subList1.TextColor = RgbColor.HotPink
Dim item5 As ListItem = subList1.Items.Add("Sub-list item 1")
Dim item6 As ListItem = subList1.Items.Add("Sub-list item 2")

Dim subList2 As OrderedSubList = item5.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase)
subList2.TextColor = RgbColor.DarkGoldenRod
Dim item7 As ListItem = subList2.Items.Add("Second level sub-list item 1")
Dim item8 As ListItem = subList2.Items.Add("Second level sub-list item 2")

page.Elements.Add(list)

List Overflow

Sometimes the items in a list might be too numerous to fit on a page. In these situations, use the GetOverFlowList method (OrderedList.GetOverFlowList, UnorderedList.GetOverFlowList) to obtain items that overflow a page. The following example illustrates an ordered list with too many items to display on a single page.

Document document = new Document();

OrderedList ol = new OrderedList(0, 0, 512, 692);

ol.ListItemTopMargin = 5;
ol.ListItemBottomMargin = 5;

for (int i = 0; i < 10; i++)
{
	ListItem item1 = ol.Items.Add("item " + i);
    OrderedSubList sl = item1.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase);

	for (int j = 0; j < 10; j++)
    {
    	ListItem subItem = sl.Items.Add("sub-item " + j);
    }
}

do
{
	Page page = new Page();
    page.Elements.Add(ol);
    document.Pages.Add(page);
    ol = ol.GetOverFlowList();
} while (ol != null);

document.Draw(outputPath);

Dim doc As New Document()

Dim ol As New OrderedList(0, 0, 512, 692)

ol.ListItemTopMargin = 5
ol.ListItemBottomMargin = 5

For i As Integer = 0 To 9
    Dim item1 As ListItem = ol.Items.Add("item " & i)

    Dim sl As OrderedSubList = item1.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase)

    For j As Integer = 0 To 9
        Dim subItem As ListItem = sl.Items.Add("sub-item " & j)
    Next
Next

Do
    Dim page As New Page()
    page.Elements.Add(ol)
    doc.Pages.Add(page)
    ol = ol.GetOverFlowList()
Loop While ol IsNot Nothing

doc.Draw(outputPath)