Word Processing: WinForms, WPF, Office File API – Watermark API Enhancements (v21.2)

As you may know, we overhauled watermark support across our Word Processing product line (Document API and UI controls for WinForms and WPF) in our most recent release cycle (v21.2). Changes include an enhanced API and the ability to modify existing watermarks/add different watermarks to document sections.

In this blog, we’ll review two methods to process watermarks within a Word document.

Use WatermarkManager to Insert and Delete Watermarks

Our WatermarkManager– the main API object used to manage document watermarks – now ships with SetText and SetImage method overloads. These overloads allow you to insert text and image watermarks into the headers of individual document sections. If a section passed to these methods does not have a specified header type, WatermarkManager will create the header.

The code sample below adds different watermarks to document sections. Our sample document contains two sections: the first section occupies the first page, and the second section is located on the second page. Sections do not have headers. The SetImage method creates a primary header with an image watermark for the first section, and the SetText method adds a primary header with a text watermark to the second section.

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using System.Drawing;
// …

using (var wordProcessor = new RichEditDocumentServer())
{
    Document document = wordProcessor.Document;
    document.LoadDocument(@"Documents\Watermarks.docx");

    var firstSection = document.Sections[0];
    var secondSection = document.Sections[1];

    // Add image watermark to the first section's header.
    document.WatermarkManager.SetImage(firstSection, HeaderFooterType.Primary,
        Image.FromFile(@"Images\DevExpressLogo.png"),
        new ImageWatermarkOptions() { Washout = false });

    // Add text watermark to the second section's header.
    document.WatermarkManager.SetText(secondSection, HeaderFooterType.Primary, "DRAFT");

    document.SaveDocument(@"Documents\WatermarksUpd.docx", DocumentFormat.OpenXml);
}

In conjunction with the ability to insert watermarks into individual document sections, we also implemented a WatermarkManager.Remove method overload. This overload allows you to remove a watermark from the header of a specific section.

Use ShapeCollection to Insert, Modify, and Delete Watermarks

Watermarks are now stored in the SubDocument.Shapes collections of section headers. You can use shape collection members to add a text or image watermark to a specific section header (via the InsertTextWatermark or InsertImageWatermark method), retrieve an existing watermark (as a Shape object of type Watermark), or remove a watermark when necessary.

We also introduced a new Shape.WatermarkFormat property that allows you to obtain and modify watermark settings. With this option, you can execute the following actions:

• Change text watermark settings (font attributes, text color, and layout).
• Modify image watermark settings (change image scale percentage and apply/remove washout effects).
• Assign new text to a watermark.
• Replace an existing watermark image with another image.

You can use different properties of the Shape object to modify watermark position, resize the watermark, and customize its appearance (add a border to a watermark image, fill and outline watermark text).

The example below adds an image watermark to the first document section, customizes watermark appearance, and rotates the watermark counterclockwise by 45 degrees.

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using System.Drawing;
// …

using (var wordProcessor = new RichEditDocumentServer())
{
    Document document = wordProcessor.Document;
    document.LoadDocument(@"Documents\Watermarks.docx");

    Section firstSection = document.Sections[0];

    // Access the first section's primary header.
    var headerContent = firstSection.BeginUpdateHeader();
    // Add image watermark to the section.
    var watermark = headerContent.Shapes.InsertImageWatermark(headerContent.Range.End,
        Image.FromFile(@"Images\DevExpressLogo.png"));
    // Remove washout effect.
    watermark.WatermarkFormat.ImageOptions.Washout = false;
    // Add border to watermark image.
    watermark.Line.Thickness = 3;
    watermark.Line.Fill.SetSolidFill(Color.Gray);
    // Rotate watermark.
    watermark.RotationAngle = -45;
    firstSection.EndUpdateHeader(headerContent);

    document.SaveDocument(@"Documents\WatermarksUpd.docx", DocumentFormat.OpenXml);
}

Learn More

Refer to the following help topics for additional information on watermark support within our Word Processing products (WinForms-WPF-Office File API):

• Watermarks in the Word Document API
• Watermarks in the WinForms Rich Text Editor
• Watermarks in the WPF Rich Text Editor

Your Feedback Matters

As always, we welcome your thoughts and feedback. Please feel free to leave a “watermark-related” comment below or contact us via the DevExpress Support Center.