Aspose::Words::Fields::FieldSeq class
Contents
[
Hide
]FieldSeq class
Implements the SEQ field. To learn more, visit the Working with Fields documentation article.
class FieldSeq : public Aspose::Words::Fields::Field,
public Aspose::Words::Fields::IFieldCodeTokenInfoProvider
Methods
| Method | Description |
|---|---|
| get_BookmarkName() | Gets or sets a bookmark name that refers to an item elsewhere in the document rather than in the current location. |
| get_DisplayResult() | Gets the text that represents the displayed field result. |
| get_End() const | Gets the node that represents the field end. |
| 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_InsertNextNumber() | Gets or sets whether to insert the next sequence number for the specified item. |
| 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_ResetHeadingLevel() | Gets or sets an integer number representing a heading level to reset the sequence number to. Returns -1 if the number is absent. |
| get_ResetNumber() | Gets or sets an integer number to reset the sequence number to. Returns -1 if the number is absent. |
| 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_SequenceIdentifier() | Gets or sets the name assigned to the series of items that are to be numbered. |
| get_Start() const | Gets the node that represents the start of the field. |
| virtual get_Type() const | Gets the Microsoft Word field type. |
| 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::FieldSeq::get_BookmarkName. |
| set_InsertNextNumber(bool) | Setter for Aspose::Words::Fields::FieldSeq::get_InsertNextNumber. |
| set_IsDirty(bool) | Setter for Aspose::Words::Fields::Field::get_IsDirty. |
| set_IsLocked(bool) | Setter for Aspose::Words::Fields::Field::get_IsLocked. |
| set_LocaleId(int32_t) | Setter for Aspose::Words::Fields::Field::get_LocaleId. |
| set_ResetHeadingLevel(const System::String&) | Setter for Aspose::Words::Fields::FieldSeq::get_ResetHeadingLevel. |
| set_ResetNumber(const System::String&) | Setter for Aspose::Words::Fields::FieldSeq::get_ResetNumber. |
| set_Result(const System::String&) | Setter for Aspose::Words::Fields::Field::get_Result. |
| set_SequenceIdentifier(const System::String&) | Setter for Aspose::Words::Fields::FieldSeq::get_SequenceIdentifier. |
| 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 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(Aspose::Words::Fields::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(Aspose::Words::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(Aspose::Words::Fields::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<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::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(Aspose::Words::BreakType::PageBreak);
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"PrefixSequence");
builder->InsertParagraph();
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::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");
Shows create numbering using SEQ fields.
auto doc = System::MakeObject<Aspose::Words::Document>();
auto builder = System::MakeObject<Aspose::Words::DocumentBuilder>(doc);
// 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.
// Insert a SEQ field that will display the current count value of "MySequence",
// after using the "ResetNumber" property to set it to 100.
builder->Write(u"#");
auto fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");
fieldSeq->set_ResetNumber(u"100");
fieldSeq->Update();
ASSERT_EQ(u" SEQ MySequence \\r 100", fieldSeq->GetFieldCode());
ASSERT_EQ(u"100", fieldSeq->get_Result());
// Display the next number in this sequence with another SEQ field.
builder->Write(u", #");
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");
fieldSeq->Update();
ASSERT_EQ(u"101", fieldSeq->get_Result());
// Insert a level 1 heading.
builder->InsertBreak(Aspose::Words::BreakType::ParagraphBreak);
builder->get_ParagraphFormat()->set_Style(doc->get_Styles()->idx_get(u"Heading 1"));
builder->Writeln(u"This level 1 heading will reset MySequence to 1");
builder->get_ParagraphFormat()->set_Style(doc->get_Styles()->idx_get(u"Normal"));
// Insert another SEQ field from the same sequence and configure it to reset the count at every heading with 1.
builder->Write(u"\n#");
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");
fieldSeq->set_ResetHeadingLevel(u"1");
fieldSeq->Update();
// The above heading is a level 1 heading, so the count for this sequence is reset to 1.
ASSERT_EQ(u" SEQ MySequence \\s 1", fieldSeq->GetFieldCode());
ASSERT_EQ(u"1", fieldSeq->get_Result());
// Move to the next number of this sequence.
builder->Write(u", #");
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");
fieldSeq->set_InsertNextNumber(true);
fieldSeq->Update();
ASSERT_EQ(u" SEQ MySequence \\n", fieldSeq->GetFieldCode());
ASSERT_EQ(u"2", fieldSeq->get_Result());
doc->UpdateFields();
doc->Save(get_ArtifactsDir() + u"Field.SEQ.ResetNumbering.docx");
Shows how to combine table of contents and sequence 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 contains the SEQ field,
// and the number of the page that the field appears on.
auto fieldToc = System::ExplicitCast<Aspose::Words::Fields::FieldToc>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldTOC, true));
// Configure this TOC field to have a SequenceIdentifier property with a value of "MySequence".
fieldToc->set_TableOfFiguresLabel(u"MySequence");
// Configure this TOC field to only pick up SEQ fields that are within the bounds of a bookmark
// named "TOCBookmark".
fieldToc->set_BookmarkName(u"TOCBookmark");
builder->InsertBreak(Aspose::Words::BreakType::PageBreak);
ASSERT_EQ(u" TOC \\c MySequence \\b TOCBookmark", fieldToc->GetFieldCode());
// 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.
// Insert a SEQ field that has a sequence identifier that matches the TOC's
// TableOfFiguresLabel property. This field will not create an entry in the TOC since it is outside
// the bookmark's bounds designated by "BookmarkName".
builder->Write(u"MySequence #");
auto fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");
builder->Writeln(u", will not show up in the TOC because it is outside of the bookmark.");
builder->StartBookmark(u"TOCBookmark");
// This SEQ field's sequence matches the TOC's "TableOfFiguresLabel" property and is within the bookmark's bounds.
// The paragraph that contains this field will show up in the TOC as an entry.
builder->Write(u"MySequence #");
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");
builder->Writeln(u", will show up in the TOC next to the entry for the above caption.");
// This SEQ field's sequence does not match the TOC's "TableOfFiguresLabel" property,
// and is within the bounds of the bookmark. Its paragraph will not show up in the TOC as an entry.
builder->Write(u"MySequence #");
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"OtherSequence");
builder->Writeln(u", will not show up in the TOC because it's from a different sequence identifier.");
// This SEQ field's sequence matches the TOC's "TableOfFiguresLabel" property and is within the bounds of the bookmark.
// This field also references another bookmark. The contents of that bookmark will appear in the TOC entry for this SEQ field.
// The SEQ field itself will not display the contents of that bookmark.
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");
fieldSeq->set_BookmarkName(u"SEQBookmark");
ASSERT_EQ(u" SEQ MySequence SEQBookmark", fieldSeq->GetFieldCode());
// Create a bookmark with contents that will show up in the TOC entry due to the above SEQ field referencing it.
builder->InsertBreak(Aspose::Words::BreakType::PageBreak);
builder->StartBookmark(u"SEQBookmark");
builder->Write(u"MySequence #");
fieldSeq = System::ExplicitCast<Aspose::Words::Fields::FieldSeq>(builder->InsertField(Aspose::Words::Fields::FieldType::FieldSequence, true));
fieldSeq->set_SequenceIdentifier(u"MySequence");
builder->Writeln(u", text from inside SEQBookmark.");
builder->EndBookmark(u"SEQBookmark");
builder->EndBookmark(u"TOCBookmark");
doc->UpdateFields();
doc->Save(get_ArtifactsDir() + u"Field.SEQ.Bookmark.docx");
See Also
- Class Field
- Namespace Aspose::Words::Fields
- Library Aspose.Words for C++