FieldLink

Implements the LINK field.

public class FieldLink : Field

Constructors

Name Description
FieldLink() The default constructor.

Properties

Name Description
AutoUpdate { get; set; } Gets or sets whether to update this field automatically.
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.
FormatUpdateType { get; set; } Gets or sets a way the linked object updates its formatting.
InsertAsBitmap { get; set; } Gets or sets whether to insert the linked object as a bitmap.
InsertAsHtml { get; set; } Gets or sets whether to insert the linked object as HTML format text.
InsertAsPicture { get; set; } Gets or sets whether to insert the linked object as a picture.
InsertAsRtf { get; set; } Gets or sets whether to insert the linked object in rich-text format (RTF).
InsertAsText { get; set; } Gets or sets whether to insert the linked object in text-only format.
InsertAsUnicode { get; set; } Gets or sets whether to insert the linked object as Unicode text.
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.
IsLinked { get; set; } Gets or sets whether to reduce the file size by not storing graphics data with 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.
ProgId { get; set; } Gets or sets the application type of the link information.
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.
SourceFullName { get; set; } Gets or sets the name and location of the source file.
SourceItem { get; set; } Gets or sets the portion of the source file that’s being linked.
Start { get; } Gets the node that represents the start of the field.
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

For information copied from another application, this field links that information to its original source file.

Examples

Shows how to use various field types to link to other documents in the local file system, and display their contents.

{
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    // Below are three types of fields we can use to display contents from a linked document in the form of text.
    // 1 -  A LINK field:
    builder.Writeln("FieldLink:\n");
    InsertFieldLink(builder, insertLinkedObjectAs, "Word.Document.8", MyDir + "Document.docx", null, true);

    // 2 -  A DDE field:
    builder.Writeln("FieldDde:\n");
    InsertFieldDde(builder, insertLinkedObjectAs, "Excel.Sheet", MyDir + "Spreadsheet.xlsx",
        "Sheet1!R1C1", true, true);

    // 3 -  A DDEAUTO field:
    builder.Writeln("FieldDdeAuto:\n");
    InsertFieldDdeAuto(builder, insertLinkedObjectAs, "Excel.Sheet", MyDir + "Spreadsheet.xlsx",
        "Sheet1!R1C1", true);

    doc.UpdateFields();
    doc.Save(ArtifactsDir + "Field.LINK.DDE.DDEAUTO.docx");
}

{
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    // Below are three types of fields we can use to display contents from a linked document in the form of an image.
    // 1 -  A LINK field:
    builder.Writeln("FieldLink:\n");
    InsertFieldLink(builder, insertLinkedObjectAs, "Excel.Sheet", MyDir + "MySpreadsheet.xlsx",
        "Sheet1!R2C2", true);

    // 2 -  A DDE field:
    builder.Writeln("FieldDde:\n");
    InsertFieldDde(builder, insertLinkedObjectAs, "Excel.Sheet", MyDir + "Spreadsheet.xlsx",
        "Sheet1!R1C1", true, true);

    // 3 -  A DDEAUTO field:
    builder.Writeln("FieldDdeAuto:\n");
    InsertFieldDdeAuto(builder, insertLinkedObjectAs, "Excel.Sheet", MyDir + "Spreadsheet.xlsx",
        "Sheet1!R1C1", true);

    doc.UpdateFields();
    doc.Save(ArtifactsDir + "Field.LINK.DDE.DDEAUTO.AsImage.docx");
}

/// <summary>
/// Use a document builder to insert a LINK field and set its properties according to parameters.
/// </summary>
private static void InsertFieldLink(DocumentBuilder builder, InsertLinkedObjectAs insertLinkedObjectAs,
    string progId, string sourceFullName, string sourceItem, bool shouldAutoUpdate)
{
    FieldLink field = (FieldLink)builder.InsertField(FieldType.FieldLink, true);

    switch (insertLinkedObjectAs)
    {
        case InsertLinkedObjectAs.Text:
            field.InsertAsText = true;
            break;
        case InsertLinkedObjectAs.Unicode:
            field.InsertAsUnicode = true;
            break;
        case InsertLinkedObjectAs.Html:
            field.InsertAsHtml = true;
            break;
        case InsertLinkedObjectAs.Rtf:
            field.InsertAsRtf = true;
            break;
        case InsertLinkedObjectAs.Picture:
            field.InsertAsPicture = true;
            break;
        case InsertLinkedObjectAs.Bitmap:
            field.InsertAsBitmap = true;
            break;
    }

    field.AutoUpdate = shouldAutoUpdate;
    field.ProgId = progId;
    field.SourceFullName = sourceFullName;
    field.SourceItem = sourceItem;

    builder.Writeln("\n");
}

/// <summary>
/// Use a document builder to insert a DDE field, and set its properties according to parameters.
/// </summary>
private static void InsertFieldDde(DocumentBuilder builder, InsertLinkedObjectAs insertLinkedObjectAs, string progId,
    string sourceFullName, string sourceItem, bool isLinked, bool shouldAutoUpdate)
{
    FieldDde field = (FieldDde)builder.InsertField(FieldType.FieldDDE, true);

    switch (insertLinkedObjectAs)
    {
        case InsertLinkedObjectAs.Text:
            field.InsertAsText = true;
            break;
        case InsertLinkedObjectAs.Unicode:
            field.InsertAsUnicode = true;
            break;
        case InsertLinkedObjectAs.Html:
            field.InsertAsHtml = true;
            break;
        case InsertLinkedObjectAs.Rtf:
            field.InsertAsRtf = true;
            break;
        case InsertLinkedObjectAs.Picture:
            field.InsertAsPicture = true;
            break;
        case InsertLinkedObjectAs.Bitmap:
            field.InsertAsBitmap = true;
            break;
    }

    field.AutoUpdate = shouldAutoUpdate;
    field.ProgId = progId;
    field.SourceFullName = sourceFullName;
    field.SourceItem = sourceItem;
    field.IsLinked = isLinked;

    builder.Writeln("\n");
}

/// <summary>
/// Use a document builder to insert a DDEAUTO, field and set its properties according to parameters.
/// </summary>
private static void InsertFieldDdeAuto(DocumentBuilder builder, InsertLinkedObjectAs insertLinkedObjectAs,
    string progId, string sourceFullName, string sourceItem, bool isLinked)
{
    FieldDdeAuto field = (FieldDdeAuto)builder.InsertField(FieldType.FieldDDEAuto, true);

    switch (insertLinkedObjectAs)
    {
        case InsertLinkedObjectAs.Text:
            field.InsertAsText = true;
            break;
        case InsertLinkedObjectAs.Unicode:
            field.InsertAsUnicode = true;
            break;
        case InsertLinkedObjectAs.Html:
            field.InsertAsHtml = true;
            break;
        case InsertLinkedObjectAs.Rtf:
            field.InsertAsRtf = true;
            break;
        case InsertLinkedObjectAs.Picture:
            field.InsertAsPicture = true;
            break;
        case InsertLinkedObjectAs.Bitmap:
            field.InsertAsBitmap = true;
            break;
    }

    field.ProgId = progId;
    field.SourceFullName = sourceFullName;
    field.SourceItem = sourceItem;
    field.IsLinked = isLinked;
}

public enum InsertLinkedObjectAs
{
    // LinkedObjectAsText
    Text,
    Unicode,
    Html,
    Rtf,
    // LinkedObjectAsImage
    Picture,
    Bitmap
}

See Also