Table of Contents

• Jun 07, 2019
• 5 minutes to read

This topic describes how to manually create a table of contents - from classic tables to tables of equations, and covers the following areas.

• Create a Table of Contents in API
• Operate the Table of Contents in the User Interface

Create a Table of Contents

1. Specify items that should be included into the TOC. To do that, mark paragraphs that correspond to the desired headings using one of the following approaches.

   • Outline levels

     Specify a paragraph outline level by the Paragraph.OutlineLevel property. With the outline level applied, the paragraph content formatting remains the same. The maximum outline level is 9.

   • Heading styles

     Create a new heading style or retrieve the existing one and apply it to the target paragraph using the ParagraphProperties.Style property. The collection of styles is accessible through the Document.ParagraphStyles property.

     C#

     Paragraph targetParagraph = richEditControl1.Document.Paragraphs[5];
     richEditControl1.Document.InsertText(targetParagraph.Range.Start, "Title 2");
     targetParagraph.Style = richEditControl1.Document.ParagraphStyles["heading 2"];
     

     VB.NET

     Dim targetParagraph As Paragraph = richEditControl1.Document.Paragraphs(5)
     richEditControl1.Document.InsertText(targetParagraph.Range.Start, "Title 2")
     targetParagraph.Style = richEditControl1.Document.ParagraphStyles("heading 2")
     

   • TC fields

     The use of the TC field allows you to show alternative titles in the table of contents. If your document needs two or more TOCs showing different entries, you can mark entries for a particular TOC using TC fields with an identifier (e.g., “{TC Finish \f bvz}”), which is specific for each TOC. To specify the outline level, use the \l field switch.

     

2. Insert the TOC field with the corresponding switch and call the FieldCollection.Update method. Depending on the approach used to mark the TOC entry, the following switches can be used.

   • none - if entries are marked using heading styles
   • \u - if entries are marked by specifying the outline level
   • \f identifier - if the TC field is used

   Tip

   To insert all TOC entries as hyperlinks, use the \h switch. You can use any other TOC field switch to modify any kind of TOC to suit your needs.

   C#

   richEditControl1.Document.BeginUpdate();
   Document document = richEditControl1.Document;
   Paragraph paragraph = document.Paragraphs.Append();            
   document.Fields.Create(paragraph.Range.Start, @"TOC \h ");
   document.EndUpdate();
   document.Fields.Update();
   

   VB.NET

   richEditControl1.Document.BeginUpdate()
   Dim document As Document = richEditControl1.Document
   Dim paragraph As Paragraph = document.Paragraphs.Append()
   document.Fields.Create(paragraph.Range.Start, "TOC \h ")
   document.EndUpdate()
   document.Fields.Update()
   

Create a Table of Figures, Table of Tables, or Table of Equations

1. To include an element into the table, insert the element caption using the SubDocument.AppendText method and mark it with the SEQ field.

   Note

   A complete sample project is available at https://github.com/DevExpress-Examples/how-to-create-table-of-figures-and-table-of-tables-programmatically-t437901.

   Form1.cs

   private void PrepareDocumentForFigures()
   {
       richEditControl1.CreateNewDocument();
       Document document = richEditControl1.Document;
       document.BeginUpdate();
   
       document.AppendText(Characters.PageBreak.ToString());
       document.AppendText("Images:\r\n");
   
       for (int i = 0; i < imageCollection1.Images.Count; i++)
       {
           // Insert the caption
           document.AppendText("Image ");
           // Insert the SEQ field
           Field field = document.Fields.Create(document.Range.End, "SEQ  Image \\* ARABIC");
           document.Images.Append(imageCollection1.Images[i].Clone() as Image);
           document.Paragraphs.Append();
       }
       //Update the inserted field
       document.Fields.Update();
       document.EndUpdate();
   }
   

   Form1.vb

   Private Sub PrepareDocumentForFigures()
       richEditControl1.CreateNewDocument()
       Dim document As Document = richEditControl1.Document
       document.BeginUpdate()
   
       document.AppendText(Characters.PageBreak.ToString())
       document.AppendText("Images:" & ControlChars.CrLf)
   
       For i As Integer = 0 To imageCollection1.Images.Count - 1
           ' Insert the caption
           document.AppendText("Image ")
           ' Insert the SEQ field
           Dim field As Field = document.Fields.Create(document.Range.End, "SEQ  Image \* ARABIC")
           document.Images.Append(TryCast(imageCollection1.Images(i).Clone(), Image))
           document.Paragraphs.Append()
       Next i
       'Update the inserted field
       document.Fields.Update()
       document.EndUpdate()
   End Sub
   

2. Insert the TOC field with the \c switch and call the FieldCollection.Update method. The TOC will be created automatically.

   Note

   A complete sample project is available at https://github.com/DevExpress-Examples/how-to-create-table-of-figures-and-table-of-tables-programmatically-t437901.

   Form1.cs

   private void InsertTableOfEntries(String key)
   {
       Document document = richEditControl1.Document;
       document.BeginUpdate();
       Field field = document.Fields.Create(document.Range.Start, string.Format("TOC \\h \\c \"{0}\"", key));
       field.Update();
       document.Fields.Update();
       document.EndUpdate();
   }
   

   Form1.vb

   Private Sub InsertTableOfEntries(ByVal key As String)
       Dim document As Document = richEditControl1.Document
       document.BeginUpdate()
       Dim field As Field = document.Fields.Create(document.Range.Start, String.Format("TOC \h \c ""{0}""", key))
       field.Update()
       document.Fields.Update()
       document.EndUpdate()
   End Sub
   

The table of figures will appear in the following way.

Table of Contents in the Command UI

End-users can create and update a table of contents, figures or captions using the corresponding commands of the References Ribbon tab. To see how to provide an application with the Ribbon Command UI, refer to the Lesson 5 - Create Separate Ribbon Pages for a Rich Text Editor article.

To include the heading into the TOC, end-users should do the following.

• Select the target text.
• On the References ribbon tab, in the Table of Contents group, click Add Text.
• In the invoked list, select the required level.

As a result, the corresponding heading style (Heading 1, Heading 2, etc.) is automatically applied to the selected text and added to the list of available styles.

Note

The Table of Contents group allows end-users to operate the table of contents built from heading styles only. To create a TOC from outline levels or TC fields, end-users should insert the TOC field with the corresponding switch manually.

The Reference ribbon tab allows end-users to insert captions to the document tables, figures, or equations. To do that, in the Captions group, click Insert Captions and select the corresponding item.

The Table of Contents Dialog allows end-users to change the target table of contents’ appearance by changing the number of displaying levels or by hiding the entries’ page numbers.