v0.12.0

What's Changed

• Add descriptions to AddImage parameters to documentation by @tmheath in #175
• Add ability to add TextBox to Word Document (new class WordTextBox) by @PrzemyslawKlys in #180
• BREAKING CHANGE Improve Watermark with colors, rotation and other settings by @PrzemyslawKlys in #181
• Word table cell paragraph add image fix by @tmheath in #176
• Add support for WriteProtection (Always Read Only) and MarkAsFinal settings by @PrzemyslawKlys in #163

New Contributors

• @tmheath made their first contribution in #175

More details. This change adds:

• Ability to modify watermark (colors, text, rotation, width, height)
• Ability to remove watermark
• Ability to find watermarks in document, sections, headers
• Ability to add watermark to document/section which makes watermark show up only on single page
• Ability to add watermark to headers/footers which makes watermark show up on whole section

Breaking changes

• This change breaks how watermarks are added. If you add them directly within section/document it will only apply to single page/pages as the SdtBlock gets added to body directly. If you need watermark for the whole section/document you need to add watermark to header/footer for it to apply to given section.

This example shows per section in header:

public static void Watermark_Sample1(string folderPath, bool openWord) {
    Console.WriteLine("[*] Creating standard document with Watermark 2");
    string filePath = System.IO.Path.Combine(folderPath, "Basic Document with Watermark 4.docx");

    using (WordDocument document = WordDocument.Create(filePath)) {
        document.AddParagraph("Section 0");
        document.AddHeadersAndFooters();
        document.Sections[0].Header.Default.AddParagraph("Section 0 - In header");
        document.Sections[0].SetMargins(WordMargin.Normal);

        Console.WriteLine(document.Sections[0].Margins.Left.Value);
        Console.WriteLine(document.Sections[0].Margins.Right.Value);

        Console.WriteLine(document.Sections[0].Margins.Type);

        document.Sections[0].Margins.Type = WordMargin.Wide;

        Console.WriteLine(document.Sections[0].Margins.Type);

        Console.WriteLine("----");
        var watermark = document.Sections[0].Header.Default.AddWatermark(WordWatermarkStyle.Text, "Watermark");
        watermark.Color = Color.Red;

        // ColorHex normally returns hex colors, but for watermark it returns string as the underlying value is in string name, not hex
        Console.WriteLine(watermark.ColorHex);

        Console.WriteLine(watermark.Rotation);

        watermark.Rotation = 180;

        Console.WriteLine(watermark.Rotation);

        watermark.Stroked = true;

        Console.WriteLine(watermark.Height);
        Console.WriteLine(watermark.Width);

        // width and height in points (HTML wise)
        watermark.Height = 100.15;
        watermark.Width = 500.18;

        document.AddPageBreak();
        document.AddPageBreak();

        document.AddSection();

        document.AddParagraph("Section 1");

        document.Sections[1].AddHeadersAndFooters();
        document.Sections[1].Header.Default.AddParagraph("Section 1 - In header");
        document.Sections[1].Margins.Type = WordMargin.Narrow;
        Console.WriteLine("----");

        Console.WriteLine("Section 0 - Paragraphs Count: " + document.Sections[0].Header.Default.Paragraphs.Count);
        Console.WriteLine("Section 1 - Paragraphs Count: " + document.Sections[1].Header.Default.Paragraphs.Count);

        Console.WriteLine("----");
        document.Sections[1].AddParagraph("Test");
        document.Sections[1].Header.Default.AddWatermark(WordWatermarkStyle.Text, "Draft");

        Console.WriteLine(document.Sections[0].Margins.Left.Value);
        Console.WriteLine(document.Sections[0].Margins.Right.Value);

        Console.WriteLine(document.Sections[1].Margins.Left.Value);
        Console.WriteLine(document.Sections[1].Margins.Right.Value);

        Console.WriteLine(document.Sections[1].Margins.Type);


        document.Settings.SetBackgroundColor(Color.Azure);

        Console.WriteLine("----");

        Console.WriteLine("Watermarks in default header: " + document.Header.Default.Watermarks.Count);

        Console.WriteLine("Watermarks in default footer: " + document.Footer.Default.Watermarks.Count);

        Console.WriteLine("Watermarks in section 0: " + document.Sections[0].Watermarks.Count);
        Console.WriteLine("Watermarks in section 0 (header): " + document.Sections[0].Header.Default.Watermarks.Count);
        Console.WriteLine("Paragraphs in section 0 (header): " + document.Sections[0].Header.Default.Paragraphs.Count);

        Console.WriteLine("Watermarks in section 1: " + document.Sections[1].Watermarks.Count);
        Console.WriteLine("Watermarks in section 1 (header): " + document.Sections[1].Header.Default.Watermarks.Count);
        Console.WriteLine("Paragraphs in section 1 (header): " + document.Sections[1].Header.Default.Paragraphs.Count);

        Console.WriteLine("Watermarks in document: " + document.Watermarks.Count);

        document.Save(false);
    }

    using (WordDocument document = WordDocument.Load(filePath)) {
        //Console.WriteLine("----");
        //Console.WriteLine("Watermarks in default header: " + document.Header.Default.Watermarks.Count);

        //Console.WriteLine("Watermarks in default footer: " + document.Footer.Default.Watermarks.Count);

        //Console.WriteLine("Watermarks in section 0: " + document.Sections[0].Watermarks.Count);
        //Console.WriteLine("Watermarks in section 0 (header): " + document.Sections[0].Header.Default.Watermarks.Count);
        //Console.WriteLine("Paragraphs in section 0 (header): " + document.Sections[0].Header.Default.Paragraphs.Count);

        //Console.WriteLine("Watermarks in section 1: " + document.Sections[1].Watermarks.Count);

        //Console.WriteLine("Paragraphs in section 1 (header): " + document.Sections[1].Header.Default.Paragraphs.Count);

        //Console.WriteLine("Watermarks in document: " + document.Watermarks.Count);

        document.Save(openWord);
    }
}

This example shows per page:

public static void Watermark_Sample3(string folderPath, bool openWord) {
    Console.WriteLine("[*] Creating standard document with watermark");
    string filePath = System.IO.Path.Combine(folderPath, "Basic Document with watermark and sections.docx");

    using (WordDocument document = WordDocument.Create(filePath)) {

        document.AddParagraph("Section 0");
        document.Sections[0].AddWatermark(WordWatermarkStyle.Text, "Confidential");

        document.AddPageBreak();
        document.AddPageBreak();

        var section = document.AddSection();
        section.AddWatermark(WordWatermarkStyle.Text, "Second Mark");

        document.AddParagraph("Section 1");

        document.AddPageBreak();
        document.AddPageBreak();

        var section1 = document.AddSection();

        document.AddParagraph("Section 2");

        document.Sections[2].AddWatermark(WordWatermarkStyle.Text, "New");

        document.AddPageBreak();
        document.AddPageBreak();

        Console.WriteLine("----");
        Console.WriteLine("Watermarks: " + document.Watermarks.Count);
        Console.WriteLine("Watermarks section 0: " + document.Sections[0].Watermarks.Count);
        Console.WriteLine("Watermarks section 1: " + document.Sections[1].Watermarks.Count);
        Console.WriteLine("Watermarks section 2: " + document.Sections[2].Watermarks.Count);

        Console.WriteLine("Paragraphs: " + document.Paragraphs.Count);

        Console.WriteLine("Removing last watermark");

        document.Sections[2].Watermarks[0].Remove();

        Console.WriteLine("Watermarks: " + document.Watermarks.Count);
        Console.WriteLine("Watermarks section 0: " + document.Sections[0].Watermarks.Count);
        Console.WriteLine("Watermarks section 1: " + document.Sections[1].Watermarks.Count);
        Console.WriteLine("Watermarks section 2: " + document.Sections[2].Watermarks.Count);
        Console.WriteLine("Paragraphs: " + document.Paragraphs.Count);

        document.Save(openWord);
    }
}

• Adds WordBordersParagraph type and allows setting borders for paragraphs
• Adds ability to add TextBox

internal static void Example_AddingTextbox2(string folderPath, bool openWord) {
    Console.WriteLine("[*] Creating standard document with some textbox");

    var filePath = System.IO.Path.Combine(folderPath, "BasicDocumentWithTextBox3.docx");

    using (WordDocument document = WordDocument.Create(filePath)) {
        var paragraph = document.AddParagraph("Adding paragraph with some text");

        var textBox = document.AddTextBox("My textbox on the left");

        textBox.HorizontalPositionRelativeFrom = HorizontalRelativePositionValues.Page;
        // horizontal alignment overwrites the horizontal position offset so only one will work
        textBox.HorizontalAlignment = HorizontalAlignmentValues.Left;
        textBox.VerticalPositionOffsetCentimeters = 3;

        var textBox2 = document.AddTextBox("My textbox on the right");
        textBox2.HorizontalPositionRelativeFrom = HorizontalRelativePositionValues.Page;
        textBox2.WordParagraph.ParagraphAlignment = JustificationValues.Right;
        // horizontal alignment overwrites the horizontal position offset so only one will work
        textBox2.HorizontalAlignment = HorizontalAlignmentValues.Right;
        textBox2.VerticalPositionOffsetCentimeters = 3;

        Console.WriteLine(textBox.VerticalPositionOffsetCentimeters);

        Console.WriteLine(document.TextBoxes[0].VerticalPositionOffsetCentimeters);

        Console.WriteLine(document.TextBoxes[1].VerticalPositionOffsetCentimeters);

        document.Save(openWord);
    }
}

• Allow setting document to AlwaysOpenReadOnly

internal static void Example_ProtectAlwaysReadOnly(string folderPath, bool openWord) {
    Console.WriteLine("[*] Creating standard document with protection 'Always Read Only'");
    string filePath = System.IO.Path.Combine(folderPath, "Basic Document with always read only protection.docx");
    using (WordDocument document = WordDocument.Create(filePath)) {
        var paragraph = document.AddParagraph("Basic paragraph - Page 4");
        paragraph.ParagraphAlignment = JustificationValues.Center;
        paragraph.Color = SixLabors.ImageSharp.Color.Blue;
        paragraph.AddText(" This is continutation in the same line");

        Console.WriteLine("Always read only: " + document.Settings.AlwaysOpenReadOnly);

        document.Settings.AlwaysOpenReadOnly = true;

        Console.WriteLine("Always read only: " + document.Settings.AlwaysOpenReadOnly);

        document.Save(true);
    }
}

• Allow setting document to FinalDocument

internal static void Example_ProtectFinalDocument(string folderPath, bool openWord) {
    Console.WriteLine("[*] Creating basic document with protection - Final Document");
    string filePath = System.IO.Path.Combine(folderPath, "Basic Document with setting Word to Final Document.docx");
    using (WordDocument document = WordDocument.Create(filePath)) {
        var paragraph = document.AddParagraph("Basic paragraph - Page 1");
        paragraph.ParagraphAlignment = JustificationValues.Center;
        paragraph.Color = SixLabors.ImageSharp.Color.Blue;
        paragraph.AddText(" This is continutation in the same line");
        paragraph.AddBreak(BreakValues.TextWrapping);

        Console.WriteLine("Final document: " + document.Settings.FinalDocument);

        document.Settings.FinalDocument = true;

        Console.WriteLine("Final document: " + document.Settings.FinalDocument);

        document.Save(openWord);
    }
}

Full Changelog: v0.11.0...v0.12.0