Aspose::Words::Fields::FieldToa class

FieldToa class

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

class FieldToa : public Aspose::Words::Fields::Field,
                 public Aspose::Words::Fields::IFieldCodeTokenInfoProvider

Methods

Method	Description
get_BookmarkName()	Gets or sets the name of the bookmark that marks the portion of the document used to build the table.
get_DisplayResult()	Gets the text that represents the displayed field result.
get_End() const	Gets the node that represents the field end.
get_EntryCategory()	Gets or sets the integral category for entries included in the table.
get_EntrySeparator()	Gets or sets the character sequence that is used to separate a table of authorities 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_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_PageNumberListSeparator()	Gets or sets the character sequence that is used to separate two page numbers in a page number list.
get_PageRangeSeparator()	Gets or sets the character sequence that is used to separate the start and end of a page range.
get_RemoveEntryFormatting()	Gets or sets whether to remove the formatting of the entry text in the document from the entry in the table of authorities.
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_SequenceName()	Gets or sets the name of a sequence whose number is included with the page number.
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.
virtual get_Type() const	Gets the Microsoft Word field type.
get_UseHeading()	Gets or sets whether to include the category heading for the entries in a table of authorities.
get_UsePassim()	Gets or sets whether to replace five or more different page references to the same authority with “passim”, which is used to indicate that a word or passage occurs frequently in the work cited.
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::FieldToa::get_BookmarkName.
set_EntryCategory(const System::String&)	Setter for Aspose::Words::Fields::FieldToa::get_EntryCategory.
set_EntrySeparator(const System::String&)	Setter for Aspose::Words::Fields::FieldToa::get_EntrySeparator.
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_PageNumberListSeparator(const System::String&)	Setter for Aspose::Words::Fields::FieldToa::get_PageNumberListSeparator.
set_PageRangeSeparator(const System::String&)	Setter for Aspose::Words::Fields::FieldToa::get_PageRangeSeparator.
set_RemoveEntryFormatting(bool)	Setter for Aspose::Words::Fields::FieldToa::get_RemoveEntryFormatting.
set_Result(const System::String&)	Setter for Aspose::Words::Fields::Field::get_Result.
set_SequenceName(const System::String&)	Setter for Aspose::Words::Fields::FieldToa::get_SequenceName.
set_SequenceSeparator(const System::String&)	Setter for Aspose::Words::Fields::FieldToa::get_SequenceSeparator.
set_UseHeading(bool)	Setter for Aspose::Words::Fields::FieldToa::get_UseHeading.
set_UsePassim(bool)	Setter for Aspose::Words::Fields::FieldToa::get_UsePassim.
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.

Examples

Shows how to build and customize a table of authorities using TOA and TA fields.

void FieldTOA_()
{
    auto doc = MakeObject<Document>();
    auto builder = MakeObject<DocumentBuilder>(doc);

    // Insert a TOA field, which will create an entry for each TA field in the document,
    // displaying long citations and page numbers for each entry.
    auto fieldToa = System::ExplicitCast<FieldToa>(builder->InsertField(FieldType::FieldTOA, false));

    // Set the entry category for our table. This TOA will now only include TA fields
    // that have a matching value in their EntryCategory property.
    fieldToa->set_EntryCategory(u"1");

    // Moreover, the Table of Authorities category at index 1 is "Cases",
    // which will show up as our table's title if we set this variable to true.
    fieldToa->set_UseHeading(true);

    // We can further filter TA fields by naming a bookmark that they will need to be within the TOA bounds.
    fieldToa->set_BookmarkName(u"MyBookmark");

    // By default, a dotted line page-wide tab appears between the TA field's citation
    // and its page number. We can replace it with any text we put on this property.
    // Inserting a tab character will preserve the original tab.
    fieldToa->set_EntrySeparator(u" \t p.");

    // If we have multiple TA entries that share the same long citation,
    // all their respective page numbers will show up on one row.
    // We can use this property to specify a string that will separate their page numbers.
    fieldToa->set_PageNumberListSeparator(u" & p. ");

    // We can set this to true to get our table to display the word "passim"
    // if there are five or more page numbers in one row.
    fieldToa->set_UsePassim(true);

    // One TA field can refer to a range of pages.
    // We can specify a string here to appear between the start and end page numbers for such ranges.
    fieldToa->set_PageRangeSeparator(u" to ");

    // The format from the TA fields will carry over into our table.
    // We can disable this by setting the RemoveEntryFormatting flag.
    fieldToa->set_RemoveEntryFormatting(true);
    builder->get_Font()->set_Color(System::Drawing::Color::get_Green());
    builder->get_Font()->set_Name(u"Arial Black");

    ASSERT_EQ(u" TOA  \\c 1 \\h \\b MyBookmark \\e \" \t p.\" \\l \" & p. \" \\p \\g \" to \" \\f", fieldToa->GetFieldCode());

    builder->InsertBreak(BreakType::PageBreak);

    // This TA field will not appear as an entry in the TOA since it is outside
    // the bookmark's bounds that the TOA's BookmarkName property specifies.
    SharedPtr<FieldTA> fieldTA = InsertToaEntry(builder, u"1", u"Source 1");

    ASSERT_EQ(u" TA  \\c 1 \\l \"Source 1\"", fieldTA->GetFieldCode());

    // This TA field is inside the bookmark,
    // but the entry category does not match that of the table, so the TA field will not include it.
    builder->StartBookmark(u"MyBookmark");
    fieldTA = InsertToaEntry(builder, u"2", u"Source 2");

    // This entry will appear in the table.
    fieldTA = InsertToaEntry(builder, u"1", u"Source 3");

    // A TOA table does not display short citations,
    // but we can use them as a shorthand to refer to bulky source names that multiple TA fields reference.
    fieldTA->set_ShortCitation(u"S.3");

    ASSERT_EQ(u" TA  \\c 1 \\l \"Source 3\" \\s S.3", fieldTA->GetFieldCode());

    // We can format the page number to make it bold/italic using the following properties.
    // We will still see these effects if we set our table to ignore formatting.
    fieldTA = InsertToaEntry(builder, u"1", u"Source 2");
    fieldTA->set_IsBold(true);
    fieldTA->set_IsItalic(true);

    ASSERT_EQ(u" TA  \\c 1 \\l \"Source 2\" \\b \\i", fieldTA->GetFieldCode());

    // We can configure TA fields to get their TOA entries to refer to a range of pages that a bookmark spans across.
    // Note that this entry refers to the same source as the one above to share one row in our table.
    // This row will have the page number of the entry above and the page range of this entry,
    // with the table's page list and page number range separators between page numbers.
    fieldTA = InsertToaEntry(builder, u"1", u"Source 3");
    fieldTA->set_PageRangeBookmarkName(u"MyMultiPageBookmark");

    builder->StartBookmark(u"MyMultiPageBookmark");
    builder->InsertBreak(BreakType::PageBreak);
    builder->InsertBreak(BreakType::PageBreak);
    builder->InsertBreak(BreakType::PageBreak);
    builder->EndBookmark(u"MyMultiPageBookmark");

    ASSERT_EQ(u" TA  \\c 1 \\l \"Source 3\" \\r MyMultiPageBookmark", fieldTA->GetFieldCode());

    // If we have enabled the "Passim" feature of our table, having 5 or more TA entries with the same source will invoke it.
    for (int i = 0; i < 5; i++)
    {
        InsertToaEntry(builder, u"1", u"Source 4");
    }

    builder->EndBookmark(u"MyBookmark");

    doc->UpdateFields();
    doc->Save(ArtifactsDir + u"Field.TOA.TA.docx");
}

static SharedPtr<FieldTA> InsertToaEntry(SharedPtr<DocumentBuilder> builder, String entryCategory, String longCitation)
{
    auto field = System::ExplicitCast<FieldTA>(builder->InsertField(FieldType::FieldTOAEntry, false));
    field->set_EntryCategory(entryCategory);
    field->set_LongCitation(longCitation);

    builder->InsertBreak(BreakType::PageBreak);

    return field;
}

Aspose::Words::Fields::FieldToa class

FieldToa class

Methods

Examples

See Also