How to: Create a Table of Contents
- 8 minutes to read
RichEditControl allows your end-users to automatically generate a table of contents (TOC) from paragraphs marked in a special way, quickly update a TOC after it has been modified, as well as format and modify it. You can accompany RichEditControl with Ribbon or Bars UI (see the Lesson 2 - Create Separate Command UI for a Rich Text Editordocument) to provide your end-users with a comprehensive functionality for creating various TOCs in documents. Alternatively, you can use a set of commands and API provided by RichEditControl to work with TOCs.
This topic covers the following areas.
Mark Entries
Before creating a TOC, it is necessary to specify items that should be collected in the TOC. There are several ways of marking entries to appear in the TOC.
Assigning Built-in Heading Styles
The easiest way to mark TOC entries is to use built-in heading styles (RichEditControl provides nine different built-in heading styles).
- Select the text (heading) that you want to appear in the TOC.
- Click Add Text either in the Table of Contents Ribbon page group located on the References tab (Ribbon UI) or on the Table of Contents toolbar (Bars UI), and then select the required level. If you change your mind and decide not to include the selected text in the TOC, click Do Not Show in Table of Contents.
Ribbon UI | Bars UI |
---|---|
After you have applied any kind of levels once in a newly created document or if you have opened a document with specified TOC entries using heading styles, the corresponding heading styles (Heading 1, Heading 2, etc.) are automatically added to the list of available styles accessed via the Styles Ribbon page group on the Home tab or Styles toolbar. In this case, you can mark TOC entries by choosing these heading styles.
Ribbon UI | Bars UI |
---|---|
To programmatically apply built-in heading styles, use the SetParagraphHeading1LevelCommand, …, SetParagraphHeading9LevelCommand commands.
Applying Paragraph Outline Levels
If you want to include some text in the TOC without changing the text appearance, you can use outline levels. Unlike heading styles, outline levels applied to text do not affect text formatting characteristics. To use outline levels to mark TOC entries, follow the steps below.
- Select the text that you want to appear in the table of contents.
- Invoke the Paragraph dialog (via the context menu or by using Ribbon or Bars UI).
- In this dialog, use the Outline level combo box to specify the outline level for the selected text. If you change your mind and decide not to include the selected text in the TOC, click Body Text.
To programmatically set an outline level of a paragraph, use the Paragraph.OutlineLevel property. You can also increase and decrease the paragraph outline level using the IncrementParagraphOutlineLevelCommand and DecrementParagraphOutlineLevelCommand commands.
Using Fields
Along with built-in heading styles and outline levels, there is another way to label text so as to include it in a TOC - via TC fields. Sometimes it can be quicker and easier to add TC fields to mark TOC entries rather than format the document using heading styles or outline levels. TC fields can be also helpful if you want to capture a portion of a long heading that should not be entirely included in the TOC and include only that portion in the TOC. In addition, 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, which is specific for each TOC.
To set up a TC field, do the following.
- Click within a document where you wish to add a TC field (for example, right below an abstract heading).
- Insert an empty field wherein you can write a field code (TC in this case) and set required switches.
Write the following:
{TC “Entry Text” \f A \l 1 }
This will add the “Entry Text” first-level item (the \l switch sets the level of the TC entry) to the TOC with an \f switch and the A identifier. The \f switch of the TC field is used to include the TC field in the corresponding TOC. A TC field identifier (A in this case) must exactly match the text in the argument of the TOC field’s \f switch. For example, the {TOC \f A} table of contents will be created from TC fields like {TC “Entry Text” \f A}.
Note
TC fields display no result in the document. To view field codes, click Show All Field Codes on the Preview Results Ribbon page group or toolbar.
To programmatically add TC fields to a document, use the InsertFieldCommand command or FieldCollection.Create method (for details, refer to How to: Insert a Field to a Document).
Build Table of Contents
After you have specified all required TOC entries, everything is ready to generate a TOC.
Build a TOC from Built-In Heading Styles
- Click within the document where you want to insert a TOC.
Click the Table of Contents in the Table of Contents Ribbon page group located on the References tab (Ribbon UI) or on the Table of Contents toolbar (Bars UI).
Create TOC via Ribbon UI Create TOC via Bars UI This will automatically generate a TOC that consists of entries marked by the use of heading styles.
To review the TOC field code that represents the newly created table of contents, click the Show All Field Codes button on the Preview Results Ribbon page group or toolbar; or select the TOC, right-click it and choose Toggle Field Codes from the context menu. The default TOC field code is { TOC \h }. The \h switch inserts all TOC entries as hyperlinks. You can use other TOC field switches to modify the TOC to fit your needs.
To programmatically create a TOC as described above, use one of the available methods described in How to: Insert a Field to a Document - by using the InsertTableOfContentsCommand command or FieldCollection.Create method.
Build a TOC from Outline Levels
- Click within the document where you want to insert a TOC.
- Insert an empty field.
- In this field, write the { TOC \u } field code. Use the \u switch to include text marked with outline levels in the TOC. You can also use other TOC field switches to modify the TOC as required.
To show the result TOC, place the cursor in the TOC field, right-click it and select the Update Field item from the context menu, or click the Update Table button on the Table of Contents Ribbon page group or toolbar. To programmatically update a field’s result, use the UpdateFieldCommand command, the Field.Update or FieldCollection.Update method.
To programmatically create a TOC from outline levels, insert the {TOC \u} field code in one of the ways described in How to: Insert a Field to a Document - using the InsertTableOfContentsCommand command or FieldCollection.Create method.
Build a TOC from TC Fields
- Click within the document where you wish to insert a TOC.
- Insert an empty field.
Write the following:
{TOC \f A}
The \f switch collects the TC field entries in the TOC. This switch’s field-argument (A in this case) specifies which TC fields should be included in the TOC (TC fields with the same identifier - A). You can also use other TOC field switches to modify the TOC as required.
- To show the resulting TOC, place the cursor in the TOC field, right-click it and select the Update Field item from the context menu, or click the Update Table button on the Table of Contents Ribbon page group or toolbar. To programmatically update a field’s result, use the UpdateFieldCommand command.
You can add a TOC field with the \f switch in code by using the InsertFieldCommand command or the FieldCollection.Create method (see the How to: Insert a Field to a Document document).
Update Table of Contents
If you have added, removed or modified TOC entries in your document, you can quickly update the TOC in one of the following ways.
- Place the cursor in the TOC and press F9.
- Place the cursor in the TOC and click the Update Table button in the Table of Contents Ribbon group located on the References tab (Ribbon UI) or on the Table of Contents toolbar (Bar UI).
- Select the TOC, right-click it and select Update Field from the context menu.
To programmatically update a table of contents, use the UpdateTableOfContentsCommand command, or call the Field.Update or FieldCollection.Update method.
Format Table of Contents
After the table of contents is created, the document contains several styles named “TOC 1”, “TOC 2”, etc., depending on how many levels the table of contents includes. You can modify these styles to change the formatting applied to different levels.