Bullets and Numbered Lists

Bulleted lists, numbered lists and outlines with several levels, such as "1.", "1.1." and "1.1.1.", are paragraph formatting in TX Text Control. Users create them with the list buttons of the ribbon and the Bullets and Numbering dialog box; your code creates them with a ListFormat object, restarts numbering, builds list styles and reads the numbers the editor has assigned. Other paragraph attributes are described in Text and Paragraph Formatting.

How Lists Work

A list is an attribute of paragraphs: each paragraph of a list has a ListFormat. Its Type is one of the ListType values:

Further facts to know before you write list code:

• Levels. Level is between 1 and 10, the value of MaxLevel. The default is 1.
• Numbering continues. A numbered list continues the numbering of the list before it until RestartNumbering starts a new one. FirstNumber sets the starting number, by default 1.
• Indents. HangingIndent, by default 360 twips, and LeftIndent position the bullet or number and the text.
• Separator. FormatCharacter decides what follows the bullet or number: Tab, the default, Space or None.
• Mixed selections. When the selection contains paragraphs with different list settings, the properties of ListFormat return their defaults. IsCommonValueSelected of the selection tells you whether a value is shared.

Let Users Format Lists

The Paragraph group of the ribbon's formatting tab has buttons for bulleted, numbered and structured lists. ListFormatDialog opens the Bullets and Numbering dialog box for the selected paragraphs, for example from a menu item of your own:

private void bulletsAndNumberingMenuItem_Click(object sender, EventArgs e)
{
    textControl1.ListFormatDialog();
}

The dialog box offers the list types, the positions of the bullet or number and of the text, the separating character, the level, the bullet character and its size, and for numbered lists the number style, the start number, the text in front of and after the number, and whether to restart the numbering or continue the list:

ListFormatDialog returns DialogResult.Cancel if the user canceled or changed nothing, and DialogResult.OK otherwise.

Create a Bulleted List

To turn the selected paragraphs into a list, create a ListFormat, set its attributes and assign it to Selection.ListFormat. The following Click handler in Form1.cs creates a bulleted list with a round bullet from the Arial font:

private void bulletsButton_Click(object sender, EventArgs e)
{
    ListFormat bullets = new ListFormat(ListType.Bulleted);
    bullets.BulletCharacter = '•';
    bullets.FontName = "Arial";

    textControl1.Selection.ListFormat = bullets;
}

• The bullet character. By default, BulletCharacter is the character B7 (hexadecimal) of the Windows Symbol font. Since version 23.0, it can be any Unicode character, and FontName names the font it comes from. Without a font, the Symbol font is assumed.
• Size. BulletSize sets the size of the bullet; 0, the default, uses the font size of the list text.

Create a Numbered List

A numbered list has a NumberFormat and optional text around the number:

private void numbersButton_Click(object sender, EventArgs e)
{
    ListFormat numbers = new ListFormat(ListType.Numbered);
    numbers.NumberFormat = NumberFormat.ArabicNumbers;
    numbers.TextAfterNumber = ".";
    numbers.FormatCharacter = ListFormatCharacter.Tab;

    textControl1.Selection.ListFormat = numbers;
}

• Number formats. NumberFormat is ArabicNumbers (1, 2, 3), Letters (a, b, c), CapitalLetters (A, B, C), RomanNumbers (I, II, III) or SmallRomanNumbers (i, ii, iii).
• Text around the number. TextBeforeNumber and TextAfterNumber hold up to 20 characters each, the value of MaxText, such as "(" and ")" for "(1)". They replace the obsolete CharBeforeNumber and CharAfterNumber.

Create a Multilevel List

A structured list shows the numbers of all higher levels, and the text before and after them, in front of each number. The level of a paragraph decides how deep it is nested:

private void outlineButton_Click(object sender, EventArgs e)
{
    ListFormat outline = new ListFormat(ListType.Structured);
    outline.NumberFormat = NumberFormat.ArabicNumbers;
    outline.TextAfterNumber = ".";
    outline.Level = 2;

    textControl1.Selection.ListFormat = outline;
}

Paragraphs at level 2 of a structured list are numbered 1.1., 1.2. and so on, below the level 1 paragraph before them.

Restart the Numbering

RestartNumbering set to true makes the selected paragraph the first item of a new list:

private void restartButton_Click(object sender, EventArgs e)
{
    ListFormat restart = new ListFormat(ListType.Numbered);
    restart.RestartNumbering = true;
    restart.FirstNumber = 1;

    textControl1.Selection.ListFormat = restart;
}

As the blog article Two Ways to Restart Numbered Lists in TX Text Control explains, a new paragraph created with ENTER inherits RestartNumbering, so the next item would start again at 1. The article shows two remedies: code that resets the property for the new item, and list styles.

Use List Styles

With styles, users never touch RestartNumbering themselves. A "List" style continues the numbering, and a "List Restart" style restarts it and names "List" as the style of the following paragraph, so that the item after it continues the new list:

private void AddListStyles()
{
    ParagraphStyle list = new ParagraphStyle("List");
    list.ListFormat = new ListFormat(ListType.Numbered) { RestartNumbering = false };
    list.FollowingStyle = "List";

    ParagraphStyle restart = new ParagraphStyle("List Restart", "List");
    restart.ListFormat = new ListFormat(ListType.Numbered) { RestartNumbering = true };
    restart.FollowingStyle = "List";

    textControl1.ParagraphStyles.Add(list);
    textControl1.ParagraphStyles.Add(restart);
}

Users can create the same styles in the styles dialog box: the Numbering... button sets the list attributes, and Style for the following paragraph names the style of the next paragraph:

Stylesheets explains styles in general.

Remove a List

Assign a ListFormat of the type None to remove the list from the selected paragraphs:

textControl1.Selection.ListFormat = new ListFormat(ListType.None);

Read the List Numbers

The number that the editor displays in front of a paragraph isn't part of its text. Paragraph.ListNumber returns it, 0 for a paragraph outside a numbered list, and ListNumberText returns it with the text before and after it. The following method lists the numbered paragraphs of the document; it needs using System.Diagnostics;:

private void ShowNumbers()
{
    foreach (Paragraph paragraph in textControl1.Paragraphs)
    {
        if (paragraph.ListNumber > 0)
        {
            Debug.WriteLine(paragraph.ListNumberText + " " + paragraph.Text);
        }
    }
}

For a toolbar of your own, InputFormat reports the list at the input position through BulletedList, NumberedList and StructuredList.

Next Steps

• Stylesheets: list attributes in paragraph styles.
• Text and Paragraph Formatting: the other paragraph attributes.
• Built-in Dialog Boxes: the other dialog boxes of the editor.