FieldRef
Contents
[
Hide
]FieldRef class
Implements the REF field.
To learn more, visit the Working with Fields documentation article.
public class FieldRef : Field
Constructors
Name | Description |
---|---|
FieldRef() | The default constructor. |
Properties
Name | Description |
---|---|
BookmarkName { get; set; } | Gets or sets the referenced bookmark’s name. |
DisplayResult { get; } | Gets the text that represents the displayed field result. |
End { get; } | Gets the node that represents the field end. |
Format { get; } | Gets a FieldFormat object that provides typed access to field’s formatting. |
IncludeNoteOrComment { get; set; } | Gets or sets whether to increment footnote, endnote, and annotation numbers that are marked by the bookmark, and insert the corresponding footnote, endnote, and comment text. |
InsertHyperlink { get; set; } | Gets or sets whether to create a hyperlink to the bookmarked paragraph. |
InsertParagraphNumber { get; set; } | Gets or sets whether to insert the paragraph number of the referenced paragraph exactly as it appears in the document. |
InsertParagraphNumberInFullContext { get; set; } | Gets or sets whether to insert the paragraph number of the referenced paragraph in full context. |
InsertParagraphNumberInRelativeContext { get; set; } | Gets or sets whether to insert the paragraph number of the referenced paragraph in relative context. |
InsertRelativePosition { get; set; } | Gets or sets whether to insert the relative position of the referenced paragraph. |
IsDirty { get; set; } | Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document. |
IsLocked { get; set; } | Gets or sets whether the field is locked (should not recalculate its result). |
LocaleId { get; set; } | Gets or sets the LCID of the field. |
NumberSeparator { get; set; } | Gets or sets the character sequence that is used to separate sequence numbers and page numbers. |
Result { get; set; } | Gets or sets text that is between the field separator and field end. |
Separator { get; } | Gets the node that represents the field separator. Can be null . |
Start { get; } | Gets the node that represents the start of the field. |
SuppressNonDelimiters { get; set; } | Gets or sets whether to suppress non-delimiter characters. |
virtual Type { get; } | Gets the Microsoft Word field type. |
Methods
Name | Description |
---|---|
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). |
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. |
Remarks
Inserts the text or graphics represented by the specified bookmark.
Examples
Shows how to create bookmarked text with a SET field, and then display it in the document using a REF field.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Name bookmarked text with a SET field.
// This field refers to the "bookmark" not a bookmark structure that appears within the text, but a named variable.
FieldSet fieldSet = (FieldSet)builder.InsertField(FieldType.FieldSet, false);
fieldSet.BookmarkName = "MyBookmark";
fieldSet.BookmarkText = "Hello world!";
fieldSet.Update();
Assert.AreEqual(" SET MyBookmark \"Hello world!\"", fieldSet.GetFieldCode());
// Refer to the bookmark by name in a REF field and display its contents.
FieldRef fieldRef = (FieldRef)builder.InsertField(FieldType.FieldRef, true);
fieldRef.BookmarkName = "MyBookmark";
fieldRef.Update();
Assert.AreEqual(" REF MyBookmark", fieldRef.GetFieldCode());
Assert.AreEqual("Hello world!", fieldRef.Result);
doc.Save(ArtifactsDir + "Field.SET.REF.docx");
Shows how to insert REF fields to reference bookmarks.
public void FieldRef()
{
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.StartBookmark("MyBookmark");
builder.InsertFootnote(FootnoteType.Footnote, "MyBookmark footnote #1");
builder.Write("Text that will appear in REF field");
builder.InsertFootnote(FootnoteType.Footnote, "MyBookmark footnote #2");
builder.EndBookmark("MyBookmark");
builder.MoveToDocumentStart();
// We will apply a custom list format, where the amount of angle brackets indicates the list level we are currently at.
builder.ListFormat.ApplyNumberDefault();
builder.ListFormat.ListLevel.NumberFormat = "> \x0000";
// Insert a REF field that will contain the text within our bookmark, act as a hyperlink, and clone the bookmark's footnotes.
FieldRef field = InsertFieldRef(builder, "MyBookmark", "", "\n");
field.IncludeNoteOrComment = true;
field.InsertHyperlink = true;
Assert.AreEqual(" REF MyBookmark \\f \\h", field.GetFieldCode());
// Insert a REF field, and display whether the referenced bookmark is above or below it.
field = InsertFieldRef(builder, "MyBookmark", "The referenced paragraph is ", " this field.\n");
field.InsertRelativePosition = true;
Assert.AreEqual(" REF MyBookmark \\p", field.GetFieldCode());
// Display the list number of the bookmark as it appears in the document.
field = InsertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number is ", "\n");
field.InsertParagraphNumber = true;
Assert.AreEqual(" REF MyBookmark \\n", field.GetFieldCode());
// Display the bookmark's list number, but with non-delimiter characters, such as the angle brackets, omitted.
field = InsertFieldRef(builder, "MyBookmark", "The bookmark's paragraph number, non-delimiters suppressed, is ", "\n");
field.InsertParagraphNumber = true;
field.SuppressNonDelimiters = true;
Assert.AreEqual(" REF MyBookmark \\n \\t", field.GetFieldCode());
// Move down one list level.
builder.ListFormat.ListLevelNumber++;
builder.ListFormat.ListLevel.NumberFormat = ">> \x0001";
// Display the list number of the bookmark and the numbers of all the list levels above it.
field = InsertFieldRef(builder, "MyBookmark", "The bookmark's full context paragraph number is ", "\n");
field.InsertParagraphNumberInFullContext = true;
Assert.AreEqual(" REF MyBookmark \\w", field.GetFieldCode());
builder.InsertBreak(BreakType.PageBreak);
// Display the list level numbers between this REF field, and the bookmark that it is referencing.
field = InsertFieldRef(builder, "MyBookmark", "The bookmark's relative paragraph number is ", "\n");
field.InsertParagraphNumberInRelativeContext = true;
Assert.AreEqual(" REF MyBookmark \\r", field.GetFieldCode());
// At the end of the document, the bookmark will show up as a list item here.
builder.Writeln("List level above bookmark");
builder.ListFormat.ListLevelNumber++;
builder.ListFormat.ListLevel.NumberFormat = ">>> \x0002";
doc.UpdateFields();
doc.Save(ArtifactsDir + "Field.REF.docx");
}
/// <summary>
/// Get the document builder to insert a REF field, reference a bookmark with it, and add text before and after it.
/// </summary>
private static FieldRef InsertFieldRef(DocumentBuilder builder, string bookmarkName, string textBefore, string textAfter)
{
builder.Write(textBefore);
FieldRef field = (FieldRef)builder.InsertField(FieldType.FieldRef, true);
field.BookmarkName = bookmarkName;
builder.Write(textAfter);
return field;
}
See Also
- class Field
- namespace Aspose.Words.Fields
- assembly Aspose.Words