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 to 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.

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

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

UnorderedList

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

Bullet Format

The UnorderedList has a constructor that allows customizing the list's bullets.

public UnorderedList(float x, float y, float width, float height, Font font, float fontSize, UnorderedListStyle bullet)

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

UnorderedList list = new UnorderedList(50, 50, 300, 500, Font.Courier, 14, new UnorderedListStyle("xyz", Font.CourierBold));

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

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.

ListItem item1 = list.Items.Add("List item 1");

//add sublist to first list item
OrderedSubList subList = item1.SubLists.AddOrderedSubList(NumberingStyle.Numeric);

//create first sub-list item but add a sub-list to it.
ListItem subItem = subList.Items.Add("a");
UnorderedSubList subList2 = subItem.SubLists.AddUnorderedSubList();
subList2.Items.Add("sub-one");
subList2.Items.Add("sub-two");

//add another item to outer sub-list
subList.Items.Add("b");        

//add remaining items
ListItem item2 = list.Items.Add("List item 2");
ListItem item3 = list.Items.Add("List item 3");
ListItem item4 = list.Items.Add("List item 4");

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 unordered list with too many items to display on a single page.

// Create a OrderedList.
UnorderedList list = new UnorderedList(50, 50, 300, 500);

// Add ListItem to the List.
for(int i = 0; i < 400; i++)
{
   list.Items.Add("List item " + i);
}

//add list items and ensure overflow is added to page
do
{
   Page page = new Page();
   page.Elements.Add(list);
   document.Pages.Add(page);
   list = list.GetOverFlowList();
} while (list != null);

Example

The following example shows how to create an OrderedList in a document.

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");
OrderedSubList subList3 = item6.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase);
subList3.TextColor = RgbColor.DarkGoldenRod;
ListItem item9 = subList3.Items.Add("Second level sub-list item 1");
ListItem item10 = subList3.Items.Add("Second level sub-list item 2");
OrderedSubList subList4 = item2.SubLists.AddOrderedSubList(NumberingStyle.RomanUpperCase);
subList4.TextColor = RgbColor.HotPink;
ListItem item11 = subList4.Items.Add("Sub-list item 1");
ListItem item12 = subList4.Items.Add("Sub-list item 2");
OrderedSubList subList5 = item11.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase);
subList5.TextColor = RgbColor.DarkGoldenRod;
ListItem item13 = subList5.Items.Add("Second level sub-list item 1");
ListItem item14 = subList5.Items.Add("Second level sub-list item 2");
OrderedSubList subList6 = item12.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase);
subList6.TextColor = RgbColor.DarkGoldenRod;
ListItem item15 = subList6.Items.Add("Second level sub-list item 1");
ListItem item16 = subList6.Items.Add("Second level sub-list item 2");
OrderedSubList subList7 = item3.SubLists.AddOrderedSubList(NumberingStyle.RomanUpperCase);
subList7.TextColor = RgbColor.HotPink;
ListItem item17 = subList7.Items.Add("Sub-list item 1");
ListItem item18 = subList7.Items.Add("Sub-list item 2");
page.Elements.Add(list);        

Dim list As OrderedList = 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 = item2.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")
Dim subList3 As OrderedSubList = item3.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase)
subList3.TextColor = RgbColor.DarkGoldenRod
Dim item9 As ListItem = subList3.Items.Add("Second level sub-list item 1")
Dim item10 As ListItem = subList3.Items.Add("Second level sub-list item 2")
Dim subList4 As OrderedSubList = item6.SubLists.AddOrderedSubList(NumberingStyle.RomanUpperCase)
subList4.TextColor = RgbColor.HotPink
Dim item11 As ListItem = subList4.Items.Add("Sub-list item 1")
Dim item12 As ListItem = subList4.Items.Add("Sub-list item 2")
Dim subList5 As OrderedSubList = item7.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase)
subList5.TextColor = RgbColor.DarkGoldenRod
Dim item13 As ListItem = subList5.Items.Add("Second level sub-list item 1")
Dim item14 As ListItem = subList5.Items.Add("Second level sub-list item 2")
Dim subList6 As OrderedSubList = item4.SubLists.AddOrderedSubList(NumberingStyle.AlphabeticLowerCase)
subList6.TextColor = RgbColor.DarkGoldenRod
Dim item15 As ListItem = subList6.Items.Add("Second level sub-list item 1")
Dim item16 As ListItem = subList6.Items.Add("Second level sub-list item 2")
Dim subList7 As OrderedSubList = item5.SubLists.AddOrderedSubList(NumberingStyle.RomanUpperCase)
subList7.TextColor = RgbColor.HotPink
Dim item17 As ListItem = subList7.Items.Add("Sub-list item 1")
Dim item18 As ListItem = subList7.Items.Add("Sub-list item 2")
MyPage.Elements.Add(list)