Aspose::Words::Fields::FieldToc class

FieldToc class

Implements the TOC field. To learn more, visit the Working with Fields documentation article.

class FieldToc : public Field,
                 public IFieldCodeTokenInfoProvider

Methods

MethodDescription
FieldToc()
UpdatePageNumbers()Updates the page numbers for items in this table of contents.
get_BookmarkName()Gets the name of the bookmark that marks the portion of the document used to build the table.
get_CaptionlessTableOfFiguresLabel()Gets or sets the name of the sequence identifier used when building a table of figures that does not include caption’s label and number.
get_CustomStyles()Gets a list of styles other than the built-in heading styles to include in the table of contents.
get_EntryIdentifier()Gets a string that should match type identifiers of TC fields being included.
get_EntryLevelRange()Gets a range of levels of the table of contents entries to be included.
get_EntrySeparator()Gets a sequence of characters that separate an entry and its page number.
get_HeadingLevelRange()Gets a range of heading levels to include.
get_HideInWebLayout()Gets whether to hide tab leader and page numbers in Web layout view.
get_InsertHyperlinks()Gets whether to make the table of contents entries hyperlinks.
get_PageNumberOmittingLevelRange()Gets a range of levels of the table of contents entries from which to omits page numbers.
get_PrefixedSequenceIdentifier()Gets or sets the identifier of a sequence for which a prefix should be added to the entry’s page number.
get_PreserveLineBreaks()Gets whether to preserve newline characters within table entries.
get_PreserveTabs()Gets whether to preserve tab entries within table entries.
get_SequenceSeparator()Gets or sets the character sequence that is used to separate sequence numbers and page numbers.
get_TableOfFiguresLabel()Gets or sets the name of the sequence identifier used when building a table of figures.
get_UseParagraphOutlineLevel()Gets whether to use the applied paragraph outline level.
set_BookmarkName(const System::String &)Sets the name of the bookmark that marks the portion of the document used to build the table.
set_CaptionlessTableOfFiguresLabel(const System::String &)Sets the name of the sequence identifier used when building a table of figures that does not include caption’s label and number.
set_CustomStyles(const System::String &)Sets a list of styles other than the built-in heading styles to include in the table of contents.
set_EntryIdentifier(const System::String &)Sets a string that should match type identifiers of TC fields being included.
set_EntryLevelRange(const System::String &)Sets a range of levels of the table of contents entries to be included.
set_EntrySeparator(const System::String &)Sets a sequence of characters that separate an entry and its page number.
set_HeadingLevelRange(const System::String &)Sets a range of heading levels to include.
set_HideInWebLayout(bool)Sets whether to hide tab leader and page numbers in Web layout view.
set_InsertHyperlinks(bool)Sets whether to make the table of contents entries hyperlinks.
set_PageNumberOmittingLevelRange(const System::String &)Sets a range of levels of the table of contents entries from which to omits page numbers.
set_PrefixedSequenceIdentifier(const System::String &)Sets the identifier of a sequence for which a prefix should be added to the entry’s page number.
set_PreserveLineBreaks(bool)Sets whether to preserve newline characters within table entries.
set_PreserveTabs(bool)Sets whether to preserve tab entries within table entries.
set_SequenceSeparator(const System::String &)Sets the character sequence that is used to separate sequence numbers and page numbers.
set_TableOfFiguresLabel(const System::String &)Sets the name of the sequence identifier used when building a table of figures.
set_UseParagraphOutlineLevel(bool)Sets whether to use the applied paragraph outline level.
GetFieldCode()Returns text between field start and field separator (or field end if there is no separator). Both field code and field result of child fields are included.
GetFieldCode(bool)Returns text between field start and field separator (or field end if there is no separator).
virtual Remove()Removes the field from the document. Returns a node right after the field. If the field’s end is the last child of its parent node, returns its parent paragraph. If the field is already removed, returns null.
Unlink()Performs the field unlink.
Update()Performs the field update. Throws if the field is being updated already.
Update(bool)Performs a field update. Throws if the field is being updated already.
get_DisplayResult()Gets the text that represents the displayed field result.
get_End() constGets the node that represents the field end.
get_Format()Gets a FieldFormat object that provides typed access to field’s formatting.
get_IsDirty()Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
get_IsLocked()Gets or sets whether the field is locked (should not recalculate its result).
get_LocaleId()Gets or sets the LCID of the field.
get_Result()Gets or sets text that is between the field separator and field end.
get_Separator()Gets the node that represents the field separator. Can be null.
get_Start() constGets the node that represents the start of the field.
virtual get_Type() constGets the Microsoft Word field type.
set_IsDirty(bool)Sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
set_IsLocked(bool)Sets whether the field is locked (should not recalculate its result).
set_LocaleId(int32_t)Sets the LCID of the field.
set_Result(const System::String &)Sets text that is between the field separator and field end.

Remarks

Builds a table of contents (which can also be a table of figures) using the entries specified by TC fields, their heading levels, and specified styles, and inserts that table at this place in the document.

Examples

Shows how to populate a TOC field with entries using SEQ fields.

auto doc = System::MakeObject<Aspose::Words::Document>();
auto builder = System::MakeObject<Aspose::Words::DocumentBuilder>(doc);

// A TOC field can create an entry in its table of contents for each SEQ field found in the document.
// Each entry contains the paragraph that includes the SEQ field and the page's number that the field appears on.
auto fieldToc = System::ExplicitCast<Aspose::Words::Fields::FieldToc>(builder->InsertField(FieldType::FieldTOC, true));

// SEQ fields display a count that increments at each SEQ field.
// These fields also maintain separate counts for each unique named sequence
// identified by the SEQ field's "SequenceIdentifier" property.
// Use the "TableOfFiguresLabel" property to name a main sequence for the TOC.
// Now, this TOC will only create entries out of SEQ fields with their "SequenceIdentifier" set to "MySequence".
fieldToc->set_TableOfFiguresLabel(u"MySequence");

// We can name another SEQ field sequence in the "PrefixedSequenceIdentifier" property.
// SEQ fields from this prefix sequence will not create TOC entries.
// Every TOC entry created from a main sequence SEQ field will now also display the count that
// the prefix sequence is currently on at the primary sequence SEQ field that made the entry.
fieldToc->set_PrefixedSequenceIdentifier(u"PrefixSequence");

// Each TOC entry will display the prefix sequence count immediately to the left
// of the page number that the main sequence SEQ field appears on.
// We can specify a custom separator that will appear between these two numbers.
fieldToc->set_SequenceSeparator(u">");

ASSERT_EQ(fieldToc->GetFieldCode(), u" TOC  \\c MySequence \\s PrefixSequence \\d >");

builder->InsertBreak(BreakType::PageBreak);

// There are two ways of using SEQ fields to populate this TOC.
// 1 -  Inserting a SEQ field that belongs to the TOC's prefix sequence:
// This field will increment the SEQ sequence count for the "PrefixSequence" by 1.
// Since this field does not belong to the main sequence identified
// by the "TableOfFiguresLabel" property of the TOC, it will not appear as an entry.
auto fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"PrefixSequence");
builder->InsertParagraph();

ASSERT_EQ(fieldSeq->GetFieldCode(), u" SEQ  PrefixSequence");

// 2 -  Inserting a SEQ field that belongs to the TOC's main sequence:
// This SEQ field will create an entry in the TOC.
// The TOC entry will contain the paragraph that the SEQ field is in and the number of the page that it appears on.
// This entry will also display the count that the prefix sequence is currently at,
// separated from the page number by the value in the TOC's SeqenceSeparator property.
// The "PrefixSequence" count is at 1, this main sequence SEQ field is on page 2,
// and the separator is ">", so entry will display "1>2".
builder->Write(u"First TOC entry, MySequence #");
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");

ASSERT_EQ(fieldSeq->GetFieldCode(), u" SEQ  MySequence");

// Insert a page, advance the prefix sequence by 2, and insert a SEQ field to create a TOC entry afterwards.
// The prefix sequence is now at 2, and the main sequence SEQ field is on page 3,
// so the TOC entry will display "2>3" at its page count.
builder->InsertBreak(BreakType::PageBreak);
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"PrefixSequence");
builder->InsertParagraph();
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(FieldType::FieldSequence, true));
builder->Write(u"Second TOC entry, MySequence #");
fieldSeq->set_SequenceIdentifier(u"MySequence");

doc->UpdateFields();
doc->Save(get_ArtifactsDir() + u"Field.TOC.SEQ.docx");

See Also