Aspose::Words::Fields::FieldToc class
Contents
[
Hide
]FieldToc class
Implements the TOC field. To learn more, visit the Working with Fields documentation article.
class FieldToc : public Aspose::Words::Fields::Field,
public Aspose::Words::Fields::IFieldCodeTokenInfoProvider
Methods
| Method | Description |
|---|---|
| FieldToc() | |
| get_BookmarkName() | Gets or sets the name of the bookmark that marks the portion of the document used to build the table. |
| get_CaptionlessTableOfFiguresLabel() | Gets 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 or sets a list of styles other than the built-in heading styles to include in the table of contents. |
| get_DisplayResult() | Gets the text that represents the displayed field result. |
| get_End() const | Gets the node that represents the field end. |
| get_EntryIdentifier() | Gets or sets a string that should match type identifiers of TC fields being included. |
| get_EntryLevelRange() | Gets or sets a range of levels of the table of contents entries to be included. |
| get_EntrySeparator() | Gets or sets a sequence of characters that separate an entry and its page number. |
| get_FieldEnd() const | Gets the node that represents the field end. |
| get_FieldStart() const | Gets the node that represents the start of the field. |
| get_Format() | Gets a FieldFormat object that provides typed access to field’s formatting. |
| get_HeadingLevelRange() | Gets or sets a range of heading levels to include. |
| get_HideInWebLayout() | Gets or sets whether to hide tab leader and page numbers in Web layout view. |
| get_InsertHyperlinks() | Gets or sets whether to make the table of contents entries hyperlinks. |
| get_IsDirty() | Gets 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_PageNumberOmittingLevelRange() | Gets or sets 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 or sets whether to preserve newline characters within table entries. |
| get_PreserveTabs() | Gets or sets whether to preserve tab entries within table entries. |
| 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_SequenceSeparator() | Gets or sets the character sequence that is used to separate sequence numbers and page numbers. |
| get_Start() const | Gets the node that represents the start of the field. |
| get_TableOfFiguresLabel() | Gets or sets the name of the sequence identifier used when building a table of figures. |
| virtual get_Type() const | Gets the Microsoft Word field type. |
| get_UseParagraphOutlineLevel() | Gets or 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). |
| GetType() const override | |
| Is(const System::TypeInfo&) const override | |
| 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. |
| set_BookmarkName(const System::String&) | Setter for Aspose::Words::Fields::FieldToc::get_BookmarkName. |
| 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&) | Setter for Aspose::Words::Fields::FieldToc::get_CustomStyles. |
| set_EntryIdentifier(const System::String&) | Setter for Aspose::Words::Fields::FieldToc::get_EntryIdentifier. |
| set_EntryLevelRange(const System::String&) | Setter for Aspose::Words::Fields::FieldToc::get_EntryLevelRange. |
| set_EntrySeparator(const System::String&) | Setter for Aspose::Words::Fields::FieldToc::get_EntrySeparator. |
| set_HeadingLevelRange(const System::String&) | Setter for Aspose::Words::Fields::FieldToc::get_HeadingLevelRange. |
| set_HideInWebLayout(bool) | Setter for Aspose::Words::Fields::FieldToc::get_HideInWebLayout. |
| set_InsertHyperlinks(bool) | Setter for Aspose::Words::Fields::FieldToc::get_InsertHyperlinks. |
| 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) | Setter for Aspose::Words::Fields::Field::get_IsLocked. |
| set_LocaleId(int32_t) | Setter for Aspose::Words::Fields::Field::get_LocaleId. |
| set_PageNumberOmittingLevelRange(const System::String&) | Setter for Aspose::Words::Fields::FieldToc::get_PageNumberOmittingLevelRange. |
| set_PrefixedSequenceIdentifier(const System::String&) | Setter for Aspose::Words::Fields::FieldToc::get_PrefixedSequenceIdentifier. |
| set_PreserveLineBreaks(bool) | Setter for Aspose::Words::Fields::FieldToc::get_PreserveLineBreaks. |
| set_PreserveTabs(bool) | Setter for Aspose::Words::Fields::FieldToc::get_PreserveTabs. |
| set_Result(const System::String&) | Setter for Aspose::Words::Fields::Field::get_Result. |
| set_SequenceSeparator(const System::String&) | Setter for Aspose::Words::Fields::FieldToc::get_SequenceSeparator. |
| set_TableOfFiguresLabel(const System::String&) | Setter for Aspose::Words::Fields::FieldToc::get_TableOfFiguresLabel. |
| set_UseParagraphOutlineLevel(bool) | Setter for Aspose::Words::Fields::FieldToc::get_UseParagraphOutlineLevel. |
| static Type() | |
| 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. |
| UpdatePageNumbers() | Updates the page numbers for items in this table of contents. |
Examples
Shows how to insert a TOC, and populate it with entries based on heading styles.
void FieldToc_()
{
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->StartBookmark(u"MyBookmark");
// Insert a TOC field, which will compile all headings into a table of contents.
// For each heading, this field will create a line with the text in that heading style to the left,
// and the page the heading appears on to the right.
auto field = System::ExplicitCast<FieldToc>(builder->InsertField(FieldType::FieldTOC, true));
// Use the BookmarkName property to only list headings
// that appear within the bounds of a bookmark with the "MyBookmark" name.
field->set_BookmarkName(u"MyBookmark");
// Text with a built-in heading style, such as "Heading 1", applied to it will count as a heading.
// We can name additional styles to be picked up as headings by the TOC in this property and their TOC levels.
field->set_CustomStyles(u"Quote; 6; Intense Quote; 7");
// By default, Styles/TOC levels are separated in the CustomStyles property by a comma,
// but we can set a custom delimiter in this property.
doc->get_FieldOptions()->set_CustomTocStyleSeparator(u";");
// Configure the field to exclude any headings that have TOC levels outside of this range.
field->set_HeadingLevelRange(u"1-3");
// The TOC will not display the page numbers of headings whose TOC levels are within this range.
field->set_PageNumberOmittingLevelRange(u"2-5");
// Set a custom string that will separate every heading from its page number.
field->set_EntrySeparator(u"-");
field->set_InsertHyperlinks(true);
field->set_HideInWebLayout(false);
field->set_PreserveLineBreaks(true);
field->set_PreserveTabs(true);
field->set_UseParagraphOutlineLevel(false);
InsertNewPageWithHeading(builder, u"First entry", u"Heading 1");
builder->Writeln(u"Paragraph text.");
InsertNewPageWithHeading(builder, u"Second entry", u"Heading 1");
InsertNewPageWithHeading(builder, u"Third entry", u"Quote");
InsertNewPageWithHeading(builder, u"Fourth entry", u"Intense Quote");
// These two headings will have the page numbers omitted because they are within the "2-5" range.
InsertNewPageWithHeading(builder, u"Fifth entry", u"Heading 2");
InsertNewPageWithHeading(builder, u"Sixth entry", u"Heading 3");
// This entry does not appear because "Heading 4" is outside of the "1-3" range that we have set earlier.
InsertNewPageWithHeading(builder, u"Seventh entry", u"Heading 4");
builder->EndBookmark(u"MyBookmark");
builder->Writeln(u"Paragraph text.");
// This entry does not appear because it is outside the bookmark specified by the TOC.
InsertNewPageWithHeading(builder, u"Eighth entry", u"Heading 1");
ASSERT_EQ(u" TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field->GetFieldCode());
field->UpdatePageNumbers();
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.TOC.docx");
}
void InsertNewPageWithHeading(SharedPtr<DocumentBuilder> builder, String captionText, String styleName)
{
builder->InsertBreak(BreakType::PageBreak);
String originalStyle = builder->get_ParagraphFormat()->get_StyleName();
builder->get_ParagraphFormat()->set_Style(builder->get_Document()->get_Styles()->idx_get(styleName));
builder->Writeln(captionText);
builder->get_ParagraphFormat()->set_Style(builder->get_Document()->get_Styles()->idx_get(originalStyle));
}
Shows how to populate a TOC field with entries using SEQ fields.
auto doc = MakeObject<Document>();
auto builder = MakeObject<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<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(u" TOC \\c MySequence \\s PrefixSequence \\d >", fieldToc->GetFieldCode());
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<FieldSeq>(builder->InsertField(FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"PrefixSequence");
builder->InsertParagraph();
ASSERT_EQ(u" SEQ PrefixSequence", fieldSeq->GetFieldCode());
// 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<FieldSeq>(builder->InsertField(FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");
ASSERT_EQ(u" SEQ MySequence", fieldSeq->GetFieldCode());
// 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<FieldSeq>(builder->InsertField(FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"PrefixSequence");
builder->InsertParagraph();
fieldSeq = System::ExplicitCast<FieldSeq>(builder->InsertField(FieldType::FieldSequence, true));
builder->Write(u"Second TOC entry, MySequence #");
fieldSeq->set_SequenceIdentifier(u"MySequence");
doc->UpdateFields();
doc->Save(ArtifactsDir + u"Field.TOC.SEQ.docx");
See Also
- Class Field
- Namespace Aspose::Words::Fields
- Library Aspose.Words for C++