DEV Community: Leon Davis

How to Convert XLS to XLSX and XLSX to XLS Using Python

Leon Davis — Wed, 09 Sep 2026 10:28:09 +0000

Excel files can be saved in different formats depending on the version of Microsoft Excel and the application that generates them. Among these formats, .xls and .xlsx are the two most commonly used.

The .xls format was used by older versions of Excel, while .xlsx became the default format after Excel 2007. Although .xlsx is now widely used, .xls files can still be found in many existing systems and applications.

When working with Excel files in Python, converting between these two formats is sometimes necessary, especially when dealing with legacy files or applications with specific format requirements.

This article shows how to convert .xls files to .xlsx and .xlsx files to .xls using Python.

Why Convert between XLS and XLSX?

The .xlsx format provides several improvements over the older .xls format:

Higher capacity: .xlsx supports more rows and columns than .xls.
Better compatibility: It works better with newer versions of Excel and other spreadsheet applications.
Smaller file sizes: .xlsx uses ZIP compression, which can reduce file size.
More features: Newer Excel functions, formulas, and formatting options are better supported.

However, .xls files are still required in some cases, especially when working with older software or systems. For these scenarios, converting .xlsx files back to .xls can also be useful.

Tools for Converting Excel Files in Python

There are several Python libraries available for working with Excel files. For example, pandas is commonly used for processing spreadsheet data, while openpyxl is mainly used for reading and writing .xlsx files. xlrd and xlwt can also be used when working with older .xls files.

In this article, we will use Spire.XLS for Python to perform the conversion. It provides APIs for loading Excel workbooks and saving them in different Excel formats.

Install the Required Library

Install the library with pip before starting:

pip install spire.xls

After installation, import the required classes in your Python project.

Convert XLS to XLSX Using Python

To convert an .xls file to .xlsx, load the workbook and save it with the target Excel format.

Example:

from spire.xls import *

# Create a workbook object
workbook = Workbook()

# Load the XLS file
workbook.LoadFromFile("input.xls")

# Save as XLSX format
workbook.SaveToFile("output.xlsx", ExcelVersion.Version2013)

# Release resources
workbook.Dispose()

The LoadFromFile() method loads the existing Excel file, and SaveToFile() saves the workbook in the specified format.

The ExcelVersion.Version2013 parameter indicates that the output file should be saved as an .xlsx file.

After running the code, the converted file will be saved as output.xlsx.

Convert XLSX to XLS Using Python

The conversion from .xlsx to .xls follows the same process. The only difference is the Excel version used when saving the file.

Example:

from spire.xls import *

# Create a workbook object
workbook = Workbook()

# Load the XLSX file
workbook.LoadFromFile("input.xlsx")

# Save as XLS format
workbook.SaveToFile("output.xls", ExcelVersion.Version97To2003)

# Release resources
workbook.Dispose()

Here, ExcelVersion.Version97To2003 specifies the older .xls format.

The workbook is loaded from input.xlsx and saved as output.xls.

Important Notes

XLS format limitations: The .xls format has several restrictions compared with .xlsx:
- Maximum of 65,536 rows.
- Maximum of 256 columns.
- Limited support for newer Excel features.

Because of these limitations, converting a large .xlsx file into .xls should be done carefully. Some data or features may not be preserved after conversion.

Formatting compatibility: When converting between .xls and .xlsx, some Excel features may not be fully supported by both formats. After conversion, check the workbook to ensure that formulas, formatting, and other features are preserved as expected.

Conclusion

Converting between .xls and .xlsx formats is a common task when processing Excel files in Python. By loading an existing workbook and saving it with the required Excel version, developers can convert files between the two formats with a small amount of code.

How to Extract Images from Word Documents with Python

Leon Davis — Fri, 04 Sep 2026 12:00:24 +0000

Word files may contain screenshots, product photos, diagrams, logos, and other embedded images. When these images need to be reused separately, saving them one by one from Microsoft Word is inefficient, especially when a document contains dozens of pictures.

This article shows how to extract images from Word documents with Python and save them as separate image files.

Prerequisites

Make sure Python is installed on your computer, then install the required package:

pip install Spire.Doc

Step 1: Load the Word Document in Python

First, import the required modules and load the document with the LoadFromFile method:

import queue
from spire.doc import *
from spire.doc.common import *

doc = Document()
doc.LoadFromFile("Sample.docx")

The document is now available for traversing its internal objects.

Step 2: Find Images in the Word Document

Images in a Word document are represented as DocPicture objects.

Because pictures may appear inside different document objects, you can use a queue to traverse the document structure and identify objects whose type is DocumentObjectType.Picture.

nodes = queue.Queue()
nodes.put(doc)

images = []

while not nodes.empty():
    node = nodes.get()

    for i in range(node.ChildObjects.Count):
        child = node.ChildObjects.get_Item(i)

        if child.DocumentObjectType == DocumentObjectType.Picture:
            picture = child if isinstance(child, DocPicture) else None

            if picture is not None:
                images.append(picture.ImageBytes)

        elif isinstance(child, ICompositeObject):
            nodes.put(child)

When a picture is found, its binary image data is retrieved through the ImageBytes property and stored in the images list.

Step 3: Save the Extracted Word Images

After collecting the image data, write each image to a separate file:

import os

output_folder = "ExtractedImages"
os.makedirs(output_folder, exist_ok=True)

for i, image_data in enumerate(images, start=1):
    output_path = os.path.join(
        output_folder,
        f"Image-{i}.png"
    )

    with open(output_path, "wb") as image_file:
        image_file.write(image_data)

For a document containing three pictures, the output folder will look like this:

ExtractedImages/
├── Image-1.png
├── Image-2.png
└── Image-3.png

Full Python Code to Extract Images from Word

Here is the complete example:

import os
import queue
from spire.doc import *
from spire.doc.common import *

input_file = "Sample.docx"
output_folder = "ExtractedImages"

os.makedirs(output_folder, exist_ok=True)

# Load the Word document
doc = Document()
doc.LoadFromFile(input_file)

# Traverse the document objects
nodes = queue.Queue()
nodes.put(doc)

images = []

while not nodes.empty():
    node = nodes.get()

    for i in range(node.ChildObjects.Count):
        child = node.ChildObjects.get_Item(i)

        # Get embedded pictures
        if child.DocumentObjectType == DocumentObjectType.Picture:
            picture = child if isinstance(child, DocPicture) else None

            if picture is not None:
                images.append(picture.ImageBytes)

        # Continue traversing nested objects
        elif isinstance(child, ICompositeObject):
            nodes.put(child)

# Save the extracted images
for i, image_data in enumerate(images, start=1):
    output_path = os.path.join(
        output_folder,
        f"Image-{i}.png"
    )

    with open(output_path, "wb") as image_file:
        image_file.write(image_data)

doc.Close()

The script scans the document, collects embedded pictures, and saves them to the ExtractedImages folder.

Extract Images from Multiple Word Documents with Python

If you have multiple Word files, the same extraction logic can be placed inside a function and applied to every .docx file in a folder.

For example:

for filename in os.listdir("WordFiles"):
    if filename.lower().endswith(".docx"):
        input_path = os.path.join("WordFiles", filename)

        # Run the image extraction logic for each document

For batch processing, it is usually better to create a separate output folder for each source document so images with the same file names do not overwrite one another.

Things to Know When Extracting Images from Word

The example extracts objects represented as DocPicture.
Charts, SmartArt, shapes, OLE objects, and other graphical elements may use different Word object types and are not necessarily extracted by this code.
The example saves the extracted image data with .png file names. If preserving the original image format is important, the source image format should be identified before assigning the output extension.
Always call Close() after processing the document to release its resources.

Conclusion

Extracting images from Word with Python is useful when documents contain many embedded pictures that need to be reused, archived, or processed separately.

By traversing the Word document objects, identifying DocPicture instances, and retrieving their image data, you can automate the extraction instead of saving each image manually.

How to Attach Files to a PDF with Python

Leon Davis — Thu, 03 Sep 2026 09:55:35 +0000

A PDF does not always have to contain everything directly on its pages.

A project report, for example, may need the original Excel data used to generate its charts. An invoice may need supporting documents, while a technical report may need to include configuration files, logs, or other reference material.

Instead of sending these files separately, they can be embedded directly in the PDF.

There are two useful ways to do this. A file can be attached to the PDF as a whole, or it can be placed at a specific location on a page as an attachment annotation.

This article shows how to handle both cases with Python.

Document Attachments vs. Attachment Annotations

Before adding a file, it helps to understand the difference between the two approaches.

A document-level attachment belongs to the PDF itself. It does not appear in the visible page content. Users typically access it through the Attachments panel in a PDF reader.

An attachment annotation, on the other hand, is placed on a particular page. It appears as a clickable attachment icon, which makes it useful when the attached file relates to a specific paragraph, chart, figure, or section.

For example:

Attach an Excel workbook to a financial report as a document-level attachment.
Place a source-data file next to a chart as an attachment annotation.
Include supporting Word documents with a submitted PDF package.
Attach a CSV or JSON file to a technical report while keeping the report itself easy to read.

The main question is whether the attachment needs a visible location within the document.

Environment Setup

To run the following code examples, install the required module for PDF processing:

pip install Spire.PDF

Add a File as a Document-Level Attachment

Suppose we have a PDF report named report.pdf and an Excel workbook named source-data.xlsx.

If the spreadsheet contains supplementary data for the entire report, attaching it at the document level is usually the cleaner option.

from spire.pdf import *

# Load the PDF
pdf = PdfDocument()
pdf.LoadFromFile("report.pdf")

# Create an attachment from an external file
attachment = PdfAttachment("source-data.xlsx")

# Add the attachment to the PDF
pdf.Attachments.Add(attachment)

# Save the result
pdf.SaveToFile("report-with-attachment.pdf")

The attachment itself is created with PdfAttachment:

attachment = PdfAttachment("source-data.xlsx")

It is then added to the document's attachment collection:

pdf.Attachments.Add(attachment)

Nothing is added to the visible PDF pages. In a PDF reader that supports embedded attachments, the spreadsheet can be accessed through the document's Attachments panel.

This makes document-level attachments particularly useful for supplementary material that belongs to the document as a whole.

Attach Multiple Files to a PDF

A PDF can also contain more than one document-level attachment.

For example, a project report could include its source spreadsheet, meeting notes, and an original diagram:

attachment1 = PdfAttachment("source-data.xlsx")
attachment2 = PdfAttachment("notes.docx")
attachment3 = PdfAttachment("diagram.png")

pdf.Attachments.Add(attachment1)
pdf.Attachments.Add(attachment2)
pdf.Attachments.Add(attachment3)

This can be useful when a PDF is intended to serve as a self-contained document package rather than being distributed together with several loose files.

Add an Attachment to a Specific PDF Page

Sometimes an attachment makes more sense when it is associated with a particular location in the document.

Consider a PDF report containing a chart generated from an Excel workbook. Instead of placing the workbook in the general attachment list, we can put an attachment icon next to the chart so readers immediately understand what the file relates to.

This is done with an attachment annotation.

from spire.pdf import *

# Load the PDF
pdf = PdfDocument()
pdf.LoadFromFile("report.pdf")

# Get the first page
page = pdf.Pages.get_Item(0)

# Read the file to be attached
data = Stream("source-data.xlsx")

# Define the position and size of the attachment icon
bounds = RectangleF(50.0, 100.0, 16.0, 16.0)

# Create the attachment annotation
annotation = PdfAttachmentAnnotation(
    bounds,
    "source-data.xlsx",
    data
)

# Set the appearance and tooltip text
annotation.Color = PdfRGBColor(Color.get_Blue())
annotation.Flags = PdfAnnotationFlags.Default
annotation.Icon = PdfAttachmentIcon.Graph
annotation.Text = "Open the source data"

# Add the annotation to the page
page.AnnotationsWidget.Add(annotation)

# Save the result
pdf.SaveToFile("report-with-page-attachment.pdf")

Here, RectangleF determines where the attachment icon appears:

bounds = RectangleF(50.0, 100.0, 16.0, 16.0)

The four values represent the X coordinate, Y coordinate, width, and height.

The file is then used to create a PdfAttachmentAnnotation:

annotation = PdfAttachmentAnnotation(
    bounds,
    "source-data.xlsx",
    data
)

Finally, the annotation is added to the page:

page.AnnotationsWidget.Add(annotation)

Unlike a document-level attachment, this file now has a visible entry point on the PDF page.

Add a Label Next to the Attachment

An attachment icon by itself may not always make its purpose obvious.

If the PDF will be shared with other users, adding a short label such as Source Data, Supporting File, or Download Spreadsheet can make the attachment easier to understand.

For example:

text = "Source data:"
font = PdfTrueTypeFont(
    "Arial",
    12.0,
    PdfFontStyle.Regular,
    True
)

x = 50.0
y = 100.0

page.Canvas.DrawString(
    text,
    font,
    PdfBrushes.get_Black(),
    x,
    y
)

text_size = font.MeasureString(text)

bounds = RectangleF(
    x + text_size.Width + 5.0,
    y,
    16.0,
    16.0
)

The width of the label is measured first, and the attachment icon is positioned a few points after the text.

The resulting layout can look something like this:

Source data: [attachment icon]

This is particularly useful when attachments are part of the document's normal reading flow rather than simply supplementary files stored with the PDF.

Which Type of PDF Attachment Should You Use?

Use a document-level attachment when the file relates to the PDF as a whole.

Typical examples include:

Raw datasets
Source spreadsheets
Supporting documents
Original images
Appendices
Configuration files
Other supplementary material

Use an attachment annotation when the file is directly related to something visible on a particular page.

For example:

Source data for a chart
An original image associated with a figure
Supporting evidence for a paragraph
A downloadable template referenced in the text
A file associated with a specific section of a report

For general document packages, document-level attachments are usually simpler because they do not affect the page layout.

Attachment annotations are more useful when the position of the file provides additional context to the reader.

A Note About PDF Viewers

Embedded attachments are part of the PDF, but how users access them can vary between PDF viewers.

Desktop PDF applications generally provide an Attachments panel and support attachment annotations. Browser-based PDF viewers may expose these features differently or support only part of the functionality.

If attachments are an important part of a document workflow, it is worth opening the finished PDF in the same viewer your recipients are likely to use.

Final Thoughts

Embedding supporting files can be cleaner than distributing a PDF together with a collection of separate documents.

For files that apply to the entire PDF, document-level attachments keep the page layout untouched while storing the supporting material inside the same file.

When an attachment belongs to a particular chart, paragraph, or section, an attachment annotation gives readers a visible and more contextual way to access it.

The coding difference between the two approaches is small, but choosing the right attachment type can make the finished PDF much easier to navigate.

How to Restrict Editing in Word and Allow Specific Editable Ranges in Java

Leon Davis — Fri, 28 Aug 2026 11:43:03 +0000

In contracts, application forms, report templates, and other Word documents, you may need to prevent users from changing certain content while still leaving selected areas editable.

For example, a document can be made read-only, restricted to tracked changes or comments, or configured so that only form fields can be filled in. You can also protect most of the document while leaving specific ranges open for editing.

These restrictions are different from a document open password. An open password controls whether someone can access the file at all, while editing restrictions control what users can do after the document has been opened.

This article shows how to apply editing restrictions to Word documents in Java and how to define editable exceptions inside a protected document.

Add the Dependency

The examples below use Spire.Doc for Java to work with Word documents. For Maven projects, add its repository and dependency to pom.xml:

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.doc</artifactId>
        <version>14.7.4</version>
    </dependency>
</dependencies>

Restrict Editing in a Word Document

Use Document.protect() to apply editing restrictions and ProtectionType to specify what users are still allowed to do.

Common protection types include:

ProtectionType	Allowed Action
`Allow_Only_Reading`	View the document without editing it
`Allow_Only_Revisions`	Edit the document with changes recorded as revisions
`Allow_Only_Comments`	Add or modify comments only
`Allow_Only_Form_Fields`	Fill in form fields only
`No_Protection`	No editing restriction

The following example makes a Word document read-only:

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.ProtectionType;

public class RestrictWordEditing {
    public static void main(String[] args) {

        // Load the Word document
        Document doc = new Document();
        doc.loadFromFile("Contract.docx");

        // Make the document read-only and set a password
        // for removing the restriction
        doc.protect(
                ProtectionType.Allow_Only_Reading,
                "123456"
        );

        // Save the document
        doc.saveToFile(
                "Contract_Protected.docx",
                FileFormat.Docx_2019
        );

        doc.close();
    }
}

To use another restriction mode, change the ProtectionType.

For example, to allow comments only:

doc.protect(
        ProtectionType.Allow_Only_Comments,
        "123456"
);

For documents that go through review, Allow_Only_Revisions is often more useful. Users can still edit the content, but their changes are recorded as revisions that can later be accepted or rejected.

For templates containing text form fields, check boxes, or similar controls, Allow_Only_Form_Fields can be used to limit editing to those fields.

The password passed to protect() is used to remove the editing restriction. It is not a password for opening the document. If the file itself should require a password before it can be opened, document encryption must be configured separately.

Allow a Specific Range to Remain Editable

Making the entire document read-only is not always enough. A common requirement is to lock standard contract clauses or instructions while leaving selected content editable.

Spire.Doc provides PermissionStart and PermissionEnd to mark a range that remains editable inside a protected document.

The following example protects the document while allowing the first six paragraphs to remain editable:

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.PermissionEnd;
import com.spire.doc.PermissionStart;
import com.spire.doc.ProtectionType;
import com.spire.doc.Section;

public class AllowEditingInSpecifiedRange {
    public static void main(String[] args) {

        // Load the Word document
        Document doc = new Document();
        doc.loadFromFile("ContractTemplate.docx");

        // Create a pair of permission markers
        PermissionStart start =
                new PermissionStart(doc, "EditableRange1");
        PermissionEnd end =
                new PermissionEnd(doc, "EditableRange1");

        // Get the target section
        Section section = doc.getSections().get(0);

        // Insert the start marker at the beginning
        // of the first paragraph
        section.getParagraphs()
                .get(0)
                .getChildObjects()
                .insert(0, start);

        // Insert the end marker at the end
        // of the sixth paragraph
        section.getParagraphs()
                .get(5)
                .getChildObjects()
                .add(end);

        // Make the rest of the document read-only
        doc.protect(
                ProtectionType.Allow_Only_Reading,
                "123456"
        );

        // Save the result
        doc.saveToFile(
                "ContractTemplate_Protected.docx",
                FileFormat.Docx_2019
        );

        doc.close();
    }
}

PermissionStart and PermissionEnd must use the same permission ID:

new PermissionStart(doc, "EditableRange1");
new PermissionEnd(doc, "EditableRange1");

Word uses this matching ID to identify the content between the two markers as one editable range.

In the example above, the start marker is inserted before the first child object of the first paragraph, while the end marker is appended to the sixth paragraph. Everything between those markers remains editable.

If only part of a paragraph should be editable, the markers can be inserted around specific TextRange objects instead of using entire paragraphs as boundaries.

For templates that change regularly, it is usually better to locate the target content through bookmarks, placeholder text, or another stable marker rather than relying on fixed paragraph indexes.

Use Unique IDs for Multiple Editable Ranges

A document can contain several editable areas, for example:

CustomerInfo
ContractAmount
Remarks

Each range should use its own permission ID, and every PermissionStart must have a matching PermissionEnd.

If the IDs do not match, or if a start marker is inserted without the correct end marker, the editable range may not behave as expected.

When editable ranges are created dynamically from business configuration, use clear and unique IDs instead of reusing the same hard-coded value for every range.

Remove Editing Restrictions from a Word Document

To restore normal editing, set the protection type to No_Protection:

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.ProtectionType;

public class RemoveEditingRestriction {
    public static void main(String[] args) {

        // Load the protected Word document
        Document doc = new Document();
        doc.loadFromFile("Contract_Protected.docx");

        // Remove the editing restriction
        doc.protect(ProtectionType.No_Protection);

        // Save the result
        doc.saveToFile(
                "Contract_Unprotected.docx",
                FileFormat.Docx_2019
        );

        doc.close();
    }
}

If the document only uses document-level protection, this is usually enough.

However, if PermissionStart and PermissionEnd were added to define editable exceptions, those markers remain part of the document structure.

If the output should be a fully cleaned document with no remaining permission markers, remove them as well:

import com.spire.doc.Document;
import com.spire.doc.DocumentObject;
import com.spire.doc.FileFormat;
import com.spire.doc.PermissionEnd;
import com.spire.doc.PermissionStart;
import com.spire.doc.ProtectionType;
import com.spire.doc.Section;
import com.spire.doc.documents.Paragraph;

public class RemoveEditingRestrictionAndPermissions {
    public static void main(String[] args) {

        Document doc = new Document();
        doc.loadFromFile("ContractTemplate_Protected.docx");

        // Remove document protection
        doc.protect(ProtectionType.No_Protection);

        // Remove permission markers
        for (int s = 0; s < doc.getSections().getCount(); s++) {
            Section section = doc.getSections().get(s);

            for (int p = 0; p < section.getParagraphs().getCount(); p++) {
                Paragraph paragraph = section.getParagraphs().get(p);

                for (int i = 0;
                     i < paragraph.getChildObjects().getCount();) {

                    DocumentObject obj =
                            paragraph.getChildObjects().get(i);

                    if (obj instanceof PermissionStart
                            || obj instanceof PermissionEnd) {

                        paragraph.getChildObjects().remove(obj);
                    } else {
                        i++;
                    }
                }
            }
        }

        doc.saveToFile(
                "ContractTemplate_Unprotected.docx",
                FileFormat.Docx_2019
        );

        doc.close();
    }
}

Notice that i is not incremented after an object is removed. Once the current item is deleted, the next object shifts into the same index. Incrementing immediately would skip that object, which matters if two permission markers appear next to each other.

Editing Restrictions Are Not the Same as Document Encryption

Editing restrictions control what users can do after the document is opened:

doc.protect(
        ProtectionType.Allow_Only_Reading,
        "123456"
);

Encryption controls whether the document can be opened without a password.

So "users can open the file but cannot edit it" and "users cannot open the file without a password" are separate requirements. A document can use both, but protect() should not be treated as file-access control.

Editing restrictions are also intended to control normal Word editing behavior rather than provide strong data security. If the content itself must be protected from unauthorized access, encryption or another access-control mechanism should be used.

Practical Considerations

For fixed templates, editable ranges can be defined directly around paragraphs, table cells, or other document objects.

For templates that change often, hard-coded indexes such as:

section.getParagraphs().get(5)

can become fragile. Adding a title or instruction paragraph may shift the target content and place the editable range in the wrong location.

Bookmarks, placeholder text, or other stable document markers usually make better anchors for editable ranges.

It is also worth checking whether the document already contains editing restrictions or permission markers before applying new ones. Reprocessing the same template without checking its existing structure can result in duplicate or overlapping permission ranges.

Conclusion

For Word templates that need to be maintained over time, the most important part is not the paragraph number used in the code, but how reliably the application can locate the content that should remain editable.

Stable anchors such as bookmarks or placeholders make the protection logic much less dependent on layout changes and help keep the code working when the template evolves.

How to Make PDF Form Fields Read-Only or Flatten Them in Java

Leon Davis — Fri, 28 Aug 2026 11:17:56 +0000

Once a PDF form has been completed, you may want to prevent further edits without losing the form structure, or remove the interactive fields entirely and produce a final version for delivery or archiving.

These two requirements are usually handled differently. A read-only field remains part of the PDF form and can still be accessed programmatically, while a flattened field is converted into static page content.

This article shows how to make an entire PDF form or an individual field read-only, how to flatten all or selected fields, and when each approach is more appropriate.

Add the Dependency

The examples below use Spire.PDF for Java to work with PDF forms. For Maven projects, add the following repository and dependency to pom.xml:

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.pdf</artifactId>
        <version>12.8.6</version>
    </dependency>
</dependencies>

Make an Entire PDF Form Read-Only

If the field values still need to be available to later code but users should no longer be able to change them, keep the form structure and mark the form as read-only.

Use PdfFormWidget.setReadOnly() to apply the setting to all fields:

import com.spire.pdf.PdfDocument;
import com.spire.pdf.widget.PdfFormWidget;

public class SetFormReadOnly {
    public static void main(String[] args) {

        // Load the PDF form
        PdfDocument pdf = new PdfDocument();
        pdf.loadFromFile("ApplicationForm.pdf");

        // Make all form fields read-only
        PdfFormWidget form = (PdfFormWidget) pdf.getForm();
        form.setReadOnly(true);

        // Save the result
        pdf.saveToFile("ApplicationForm_ReadOnly.pdf");
        pdf.close();
    }
}

The fields remain in the PDF after this operation, so the application can still retrieve their names and values or perform other form-related processing later.

Make a Specific PDF Form Field Read-Only

To lock only one field, retrieve the corresponding PdfField and call setReadOnly() on it:

import com.spire.pdf.PdfDocument;
import com.spire.pdf.fields.PdfField;
import com.spire.pdf.widget.PdfFormWidget;

public class SetFieldReadOnly {
    public static void main(String[] args) {

        PdfDocument pdf = new PdfDocument();
        pdf.loadFromFile("ApplicationForm.pdf");

        PdfFormWidget form = (PdfFormWidget) pdf.getForm();

        // Get the field by its internal name
        PdfField field = form.getFieldsWidget().get("RequestAmount");

        if (field != null) {
            field.setReadOnly(true);
        }

        pdf.saveToFile("ApplicationForm_PartiallyReadOnly.pdf");
        pdf.close();
    }
}

One detail that matters in real projects is that the name used in code is the field's internal PDF name, not necessarily the label visible on the page.

A field displayed as Request Amount, for example, may internally be named:

RequestAmount
amount
TextField12

If the template comes from another team or an external source, inspect the available field names first:

PdfFormWidget form = (PdfFormWidget) pdf.getForm();

for (int i = 0; i < form.getFieldsWidget().getCount(); i++) {
    PdfField field = form.getFieldsWidget().get(i);
    System.out.println(field.getName());
}

For templates that change over time, field names are also safer than hard-coded indexes. Once fields are added or reordered, an index may point to a different field without making the problem immediately obvious.

Flatten All PDF Form Fields

When the PDF no longer needs to behave as an interactive form, the fields can be flattened.

Use isFlatten(true) to flatten the entire form:

import com.spire.pdf.PdfDocument;

public class FlattenForm {
    public static void main(String[] args) {

        // Load the completed PDF form
        PdfDocument pdf = new PdfDocument();
        pdf.loadFromFile("ApprovedForm.pdf");

        // Flatten all form fields
        pdf.getForm().isFlatten(true);

        // Save the result
        pdf.saveToFile("ApprovedForm_Flattened.pdf");
        pdf.close();
    }
}

The current appearance of each field is preserved on the page, but text boxes, check boxes, drop-down lists, and other interactive controls are no longer available as fillable fields.

Any logic that still depends on the form structure should therefore run before flattening. This includes reading values, assigning data, validating fields, and exporting form data.

Flatten a Specific PDF Form Field

You can also flatten a single field while leaving the rest of the form interactive.

Retrieve the target PdfField and call setFlatten(true):

import com.spire.pdf.PdfDocument;
import com.spire.pdf.fields.PdfField;
import com.spire.pdf.widget.PdfFormWidget;

public class FlattenField {
    public static void main(String[] args) {

        PdfDocument pdf = new PdfDocument();
        pdf.loadFromFile("ApplicationForm.pdf");

        PdfFormWidget form = (PdfFormWidget) pdf.getForm();

        // Get the target field
        PdfField field = form.getFieldsWidget().get("RequestAmount");

        if (field != null) {
            field.setFlatten(true);
        }

        pdf.saveToFile("ApplicationForm_PartiallyFlattened.pdf");
        pdf.close();
    }
}

This is useful when one part of a form is final but other fields still need to remain editable.

Checking for null is worth keeping in production code. PDF templates are often updated independently of the application, and a renamed or removed field can otherwise turn a simple template change into a NullPointerException.

Read-Only vs. Flattened Form Fields

Both approaches can stop normal user input, but they leave the PDF in very different states.

Aspect	Read-Only	Flattened
Interactive field structure preserved	Yes	No
User can edit the field normally	No	No
Field can still be accessed by name	Yes	No longer appropriate
Field properties can be changed later	Yes	No
Suitable for ongoing form processing	Yes	Usually not
Suitable for final delivery or archiving	Yes	Usually better

Use read-only fields when the PDF is still part of a larger workflow and your code may need to inspect or process the form later.

Flatten the fields when the form itself is no longer needed and only the final rendered content matters.

Neither option should be treated as a PDF security feature. Setting a field to read-only or flattening it does not prevent the whole document from being edited, copied, or printed. Those requirements belong to PDF permission settings, while tamper detection is better handled with digital signatures.

Practical Considerations

For fixed templates, field names are generally more reliable than field indexes. If templates are maintained outside the development team, it is useful to inspect the internal field names during integration and keep those names in configuration or constants rather than scattering them throughout the codebase.

Flattening should also be one of the last steps in the processing pipeline. Once a final flattened file has been produced, later code should not assume that the original form structure is still available.

The rendered result deserves a quick check as well, especially when the form contains CJK text, custom fonts, symbols, check boxes, or drop-down fields. A server may not have the same fonts as a developer workstation, and that difference can affect how field content appears after flattening.

Conclusion

For production systems, keep the editable source form separate from the generated read-only or flattened output. That small separation makes template updates, data corrections, and troubleshooting much easier than trying to recover structure from a file that has already been finalized.

Convert Markdown to PDF in Java (with Advanced Settings)

Leon Davis — Fri, 21 Aug 2026 11:07:48 +0000

Markdown is widely used for writing technical documentation, project notes, README files, and online content. Its lightweight syntax makes documents easy to create, update, and manage.

However, Markdown is not always the best format for sharing. When a document needs to be printed, archived, or distributed to users who do not use Markdown tools, PDF is usually a better choice because it provides a fixed layout and consistent appearance.

In Java applications, automating Markdown-to-PDF conversion can be useful for documentation platforms, report generation systems, and publishing workflows.

This article explains how to convert Markdown files to PDF in Java and how to customize the page settings of the generated PDF document.

Why Convert Markdown to PDF?

Markdown and PDF serve different purposes.

Markdown is convenient during content creation because:

It is simple and readable.
It works well with version control systems.
It separates content from formatting.
It is easy to maintain.

PDF is more suitable for final distribution because:

The layout remains consistent across platforms.
The document can be printed directly.
It is easier to archive and share.
Users do not need Markdown editing tools.

Common use cases include:

Converting technical documentation into PDF manuals.
Generating reports from Markdown templates.
Creating downloadable documents automatically.
Publishing articles or internal knowledge-base content.

Prerequisites

Before converting Markdown files, prepare:

Java Development Kit (JDK).
A Java document processing library that supports Markdown loading and PDF export.

In this example, we will use Spire.Doc for Java to handle the document conversion.

Add the Required Dependency

For Maven projects, add the following dependency to your pom.xml file:

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.doc</artifactId>
        <version>14.7.4</version>
    </dependency>
</dependencies>

Convert Markdown to PDF in Java

After adding the dependency, you can load a Markdown file and save it as PDF.

The conversion process only requires a few steps:

Create a Document object.
Load the Markdown file.
Save the document using the PDF format.

import com.spire.doc.Document;
import com.spire.doc.FileFormat;

public class MarkdownToPDF {

    public static void main(String[] args) {

        Document doc = new Document();

        // Load Markdown file
        doc.loadFromFile("Sample.md");

        // Save as PDF
        doc.saveToFile(
                "output/MarkdownToPDF.pdf",
                FileFormat.PDF
        );

        doc.dispose();
    }
}

After running the code, the Markdown content will be converted into a PDF document.

Customize PDF Page Settings

For many documents, the default page layout may not be enough. Reports, manuals, and printed documents often require specific page settings, such as:

Page size.
Page orientation.
Page margins.

Before exporting the PDF, you can configure these settings through the document's PageSetup object.

The following example sets the page size, orientation, and margins before conversion:

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.PageSetup;
import com.spire.doc.Section;
import com.spire.doc.documents.MarginsF;
import com.spire.doc.documents.PageOrientation;
import com.spire.doc.documents.PageSize;

public class MarkdownPageSettings {

    public static void main(String[] args) {

        Document doc = new Document();

        // Load Markdown file
        doc.loadFromFile("Sample.md");

        // Get the document section
        Section section = doc.getSections().get(0);

        // Configure page settings
        PageSetup pageSetup = section.getPageSetup();

        pageSetup.setPageSize(PageSize.A4);

        pageSetup.setOrientation(
                PageOrientation.Portrait
        );

        pageSetup.setMargins(
                new MarginsF(72, 72, 72, 72)
        );

        // Save as PDF
        doc.saveToFile(
                "output/MarkdownToPDF_Custom.pdf",
                FileFormat.PDF
        );

        doc.dispose();
    }
}

With these settings, the generated PDF will use the specified page layout instead of the default configuration.

Additional Tips

Test complex Markdown content: Documents containing tables, images, or advanced formatting should be checked after conversion.
Configure page settings based on usage: A4 portrait may work well for articles, while landscape mode may be better for wide tables.
Keep the original Markdown files: Markdown is easy to update, so keeping the source files makes future modifications easier.
Release resources properly: When converting multiple files, dispose of document objects after each operation to avoid unnecessary resource usage.

Conclusion

Markdown is an efficient format for creating and maintaining structured content, while PDF is often preferred for final delivery and distribution.

By combining Markdown loading with PDF export capabilities, Java developers can automate the conversion process and integrate it into documentation systems, report generators, and publishing workflows.

Customizing page settings before export also provides more control over the final document layout, making the generated PDFs better suited for different business and publishing scenarios.

Add & Remove Watermarks in Word Using Java: A Step-by-Step Guide

Leon Davis — Fri, 21 Aug 2026 10:45:13 +0000

Watermarks are commonly used in Word documents to indicate document status, ownership, or confidentiality. For example, a report may need a “DRAFT” watermark during review, internal documents may require a “CONFIDENTIAL” label, and business templates may include a company logo watermark.

Adding or removing watermarks manually is simple for individual documents. However, it becomes inefficient when documents are generated automatically, processed in batches, or managed by enterprise document systems. In these scenarios, programmatic watermark management allows developers to apply consistent formatting across multiple Word files.

In this guide, we will show how to use Java to:

Add text watermarks to Word documents.
Add image watermarks to Word documents.
Remove existing watermarks from Word documents.

Why Manage Word Watermarks Programmatically?

Automated watermark processing is useful in many scenarios:

Document review workflows: Add a “DRAFT” watermark during review and remove it after approval.
Confidential document management: Mark sensitive files with labels such as “CONFIDENTIAL” or “INTERNAL USE ONLY”.
Automated report generation: Apply consistent watermarks when generating reports, contracts, or business documents.
Batch document processing: Update multiple Word files without manually opening each document.

Prerequisites

Before getting started, you need:

Java Development Kit (JDK): A Java development environment for building and running Java applications.
Spire.Doc for Java: A Java library for creating, reading, and modifying Word documents programmatically.

You can add the library to your project using Maven.

Maven Dependency

Add the following configuration to your pom.xml file:

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.doc</artifactId>
        <version>14.7.4</version>
    </dependency>
</dependencies>

Part 1: Add a Text Watermark to a Word Document

Text watermarks are the most common type of watermark. They are usually used to display document status, such as “DRAFT”, “CONFIDENTIAL”, or “APPROVED”.

Step 1: Load a Word Document

First, create a Document object and load the Word file that you want to modify.

Document document = new Document();

document.loadFromFile("input.docx");

The loadFromFile() method loads the Word document into memory, allowing you to modify its content.

Step 2: Create a Text Watermark

Use the TextWatermark class to create a text watermark and configure its content, font, and color.

import java.awt.*;

TextWatermark watermark = new TextWatermark(
        "CONFIDENTIAL",
        new Font("Arial", Font.PLAIN, 45),
        Color.GRAY
);

The parameters control the appearance of the watermark:

The first parameter defines the watermark text.
The second parameter specifies the font style and size.
The third parameter sets the watermark color.

You can replace "CONFIDENTIAL" with other labels depending on your requirements:

DRAFT
INTERNAL USE ONLY
APPROVED

Step 3: Configure the Text Watermark Layout

You can control how the watermark appears by setting its layout.

For example, create a diagonal watermark:

watermark.setLayout(WatermarkLayout.Diagonal);

A diagonal watermark is commonly used for document status labels because it is noticeable without covering the main content.

For a horizontal watermark, use:

watermark.setLayout(WatermarkLayout.Horizontal);

Step 4: Apply and Save the Text Watermark

After configuring the watermark, apply it to the document and save the result.

document.setWatermark(watermark);

document.saveToFile(
        "text-watermarked.docx",
        FileFormat.Docx
);

Full Code Example: Add a Text Watermark

The following example adds a diagonal “CONFIDENTIAL” watermark to a Word document.

import com.spire.doc.*;
import com.spire.doc.documents.*;
import java.awt.*;

public class AddTextWatermark {

    public static void main(String[] args) {

        Document document = new Document();

        // Load a Word document
        document.loadFromFile("input.docx");

        // Create a text watermark
        TextWatermark watermark = new TextWatermark(
                "CONFIDENTIAL",
                new Font("Arial", Font.PLAIN, 45),
                Color.GRAY
        );

        // Set watermark layout
        watermark.setLayout(WatermarkLayout.Diagonal);

        // Add watermark
        document.setWatermark(watermark);

        // Save the document
        document.saveToFile(
                "text-watermarked.docx",
                FileFormat.Docx
        );

        document.dispose();

        System.out.println("Text watermark added successfully!");
    }
}

Part 2: Add an Image Watermark to a Word Document

Besides text watermarks, Word documents often use image watermarks such as company logos, brand marks, or copyright images.

Image watermarks are useful when a visual identifier is needed, such as in company templates or official documents.

Step 1: Load a Word Document

First, load the Word document where you want to add the image watermark.

Document document = new Document();

document.loadFromFile("input.docx");

Step 2: Create an Image Watermark

Use the PictureWatermark class to create an image watermark.

PictureWatermark watermark = new PictureWatermark();

watermark.setPicture("logo.png");

The logo.png file is the image that will be displayed as the document watermark.

Step 3: Adjust the Image Watermark Appearance

You can customize the image watermark according to your needs.

For example, reduce the image intensity:

watermark.setWashout(true);

Adjust the image scale:

watermark.setScaling(100);

These settings help the image work better as a background element without affecting document readability.

Step 4: Apply and Save the Image Watermark

After configuring the image watermark, apply it to the document and save the result.

document.setWatermark(watermark);

document.saveToFile(
        "image-watermarked.docx",
        FileFormat.Docx
);

Full Code Example: Add an Image Watermark

The following example adds a logo image as a watermark to a Word document.

import com.spire.doc.*;

public class AddImageWatermark {

    public static void main(String[] args) {

        Document document = new Document();

        // Load a Word document
        document.loadFromFile("input.docx");

        // Create an image watermark
        PictureWatermark watermark = new PictureWatermark();

        watermark.setPicture("logo.png");

        // Configure watermark appearance
        watermark.setWashout(true);
        watermark.setScaling(100);

        // Add image watermark
        document.setWatermark(watermark);

        // Save the document
        document.saveToFile(
                "image-watermarked.docx",
                FileFormat.Docx
        );

        document.dispose();

        System.out.println("Image watermark added successfully!");
    }
}

Part 3: Remove a Watermark from a Word Document

After a document has been reviewed or approved, you may need to remove the watermark before publishing or sharing it.

Step 1: Load the Watermarked Document

First, load the Word document that contains the watermark.

Document document = new Document();

document.loadFromFile("watermarked.docx");

Step 2: Remove the Watermark

Use the removeWatermark() method to remove the existing watermark:

document.removeWatermark();

This removes the watermark previously applied to the document.

Step 3: Save the Document Without the Watermark

Finally, save the updated document:

document.saveToFile(
        "without-watermark.docx",
        FileFormat.Docx
);

Full Code Example: Remove a Watermark

The following example removes a watermark from an existing Word document.

import com.spire.doc.*;

public class RemoveWatermark {

    public static void main(String[] args) {

        Document document = new Document();

        // Load a watermarked document
        document.loadFromFile("watermarked.docx");

        // Remove watermark
        document.removeWatermark();

        // Save the document
        document.saveToFile(
                "without-watermark.docx",
                FileFormat.Docx
        );

        document.dispose();

        System.out.println("Watermark removed successfully!");
    }
}

Run the Program

Compile and run the Java programs:

The text watermark example generates a Word document with a text label.
The image watermark example adds a logo or image background.
The removal example creates a new document without the watermark.

You can open the generated .docx files in Microsoft Word to verify the results.

Additional Tips

Choose appropriate watermark settings: Use lighter colors and suitable font sizes so the watermark does not affect document readability.
Keep the original document: Adding or removing watermarks modifies the document, so keep a backup copy when processing important files.
Process multiple documents: For batch operations, place the document loading, modification, and saving logic inside a loop.
Test complex documents: Documents with multiple sections, images, or advanced formatting should be tested before large-scale processing.

Conclusion

Watermarks are widely used in Word document management to indicate document status, protect sensitive information, and maintain consistent branding.

While manual editing is sufficient for individual files, automated watermark management is more efficient for document generation systems and batch processing workflows.

With Spire.Doc for Java, developers can add text watermarks, add image watermarks, and remove existing watermarks from Word documents through simple API calls. This makes watermark handling easier to integrate into reporting systems, document management platforms, and enterprise applications.

How to Add, Read, and Remove Speaker Notes in PowerPoint Using Java

Leon Davis — Fri, 14 Aug 2026 11:30:18 +0000

Speaker notes are useful when the content shown on a PowerPoint slide is not enough for the presenter. They can contain talking points, explanations, reminders, references, or instructions that should not appear directly on the slide.

For presentations created or maintained by an application, these notes may also need to be generated automatically. For example, a training system can build slides from a template and insert instructor notes at the same time, while a document-processing workflow may need to extract existing notes for review, archiving, or migration.

This article shows how to use Java to add speaker notes to PowerPoint slides, read existing notes, remove them when they are no longer needed, and process notes across multiple slides.

Install the Java PowerPoint Library

This example uses Spire.Presentation for Java. If you use Maven, add the dependency to your pom.xml:

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.presentation</artifactId>
        <version>11.7.2</version>
    </dependency>
</dependencies>

You can also download the JAR package and add the required files to the project manually if Maven is not used.

Add Speaker Notes to a PowerPoint Slide

In PowerPoint, speaker notes are associated with individual slides. A slide can therefore have its own notes content without displaying that text during the normal slide show.

With Spire.Presentation for Java, you can access a slide through the presentation's slide collection, create its notes slide, and then append one or more paragraphs to the notes text frame.

The following example adds several speaker notes to the first slide:

import com.spire.presentation.*;

public class AddSpeakerNotes {

    public static void main(String[] args) throws Exception {

        // Load the PowerPoint presentation
        Presentation presentation = new Presentation();
        presentation.loadFromFile("input.pptx");

        // Get the first slide
        ISlide slide = presentation.getSlides().get(0);

        // Create a notes slide for the selected slide
        NotesSlide notesSlide = slide.addNotesSlide();

        // Add the first note paragraph
        ParagraphEx paragraph = new ParagraphEx();
        paragraph.setText("Key message:");
        notesSlide.getNotesTextFrame().getParagraphs().append(paragraph);

        // Add another note paragraph
        paragraph = new ParagraphEx();
        paragraph.setText(
                "Explain that the increase was mainly driven by enterprise customers."
        );
        notesSlide.getNotesTextFrame().getParagraphs().append(paragraph);

        // Add another note paragraph
        paragraph = new ParagraphEx();
        paragraph.setText(
                "Mention the regional breakdown before moving to the next slide."
        );
        notesSlide.getNotesTextFrame().getParagraphs().append(paragraph);

        // Save the result
        presentation.saveToFile(
                "PresentationWithNotes.pptx",
                FileFormat.PPTX_2013
        );

        presentation.dispose();
    }
}

The key step is creating a notes slide for the target slide:

NotesSlide notesSlide = slide.addNotesSlide();

Once the notes slide is available, its text frame can contain one or more paragraphs.

For example:

ParagraphEx paragraph = new ParagraphEx();
paragraph.setText("Key message:");

notesSlide.getNotesTextFrame()
        .getParagraphs()
        .append(paragraph);

Using separate paragraphs is useful when the notes contain several distinct talking points rather than one long block of text. It also makes the notes easier to update or remove individually later.

This approach works well for presentations generated from structured data. A reporting system, for example, might create a chart on the slide while storing the explanation of the chart in the corresponding notes section.

Read Speaker Notes from PowerPoint

Speaker notes are not always created by your own application. You may need to inspect a presentation uploaded by a user, collect presenter instructions from an existing slide deck, or export notes into another format.

To read the notes associated with a slide, first obtain its NotesSlide object:

NotesSlide notesSlide = slide.getNotesSlide();

Then retrieve the text from its notes text frame.

The following example loops through the entire presentation and prints the notes for each slide:

import com.spire.presentation.*;

public class ReadSpeakerNotes {

    public static void main(String[] args) throws Exception {

        // Load the PowerPoint presentation
        Presentation presentation = new Presentation();
        presentation.loadFromFile("PresentationWithNotes.pptx");

        // Loop through all slides
        for (int i = 0; i < presentation.getSlides().getCount(); i++) {

            ISlide slide = presentation.getSlides().get(i);
            NotesSlide notesSlide = slide.getNotesSlide();

            // Some slides may not contain speaker notes
            if (notesSlide != null) {

                String notes = notesSlide
                        .getNotesTextFrame()
                        .getText();

                System.out.println(
                        "Slide " + (i + 1) + ":\n" + notes
                );
            }
        }

        presentation.dispose();
    }
}

One detail worth keeping is the null check:

if (notesSlide != null) {
    // Read the notes
}

Not every slide in a presentation necessarily has speaker notes. When processing PowerPoint files from unknown sources, assuming that a notes slide always exists can cause the program to fail when it reaches a slide without notes.

For a presentation containing notes on only some slides, the output might look like this:

Slide 1:
Key message:
Explain that the increase was mainly driven by enterprise customers.
Mention the regional breakdown before moving to the next slide.

Slide 3:
Remind the audience that these figures are preliminary.

After extraction, the notes can be written to a text file, stored in a database, indexed for search, or passed to another part of the application.

This can be useful for reviewing large presentation libraries because the presenter instructions can be collected without opening every slide deck manually.

Remove Speaker Notes from PowerPoint

There are also situations where speaker notes should be removed before a presentation is distributed.

An internal presentation, for example, may contain reminders such as:

Do not discuss pricing unless the customer asks.

or:

Mention that these figures have not been approved yet.

Those notes may be useful during internal meetings but inappropriate in a presentation that will be shared with customers or external partners.

To remove all note paragraphs from a slide, clear the paragraph collection in the notes text frame:

notesSlide.getNotesTextFrame()
        .getParagraphs()
        .clear();

The following example removes speaker-note text from every slide in the presentation:

import com.spire.presentation.*;

public class RemoveSpeakerNotes {

    public static void main(String[] args) throws Exception {

        // Load the presentation
        Presentation presentation = new Presentation();
        presentation.loadFromFile("PresentationWithNotes.pptx");

        // Process all slides
        for (int i = 0; i < presentation.getSlides().getCount(); i++) {

            ISlide slide = presentation.getSlides().get(i);
            NotesSlide notesSlide = slide.getNotesSlide();

            if (notesSlide != null) {

                // Remove all note paragraphs
                notesSlide.getNotesTextFrame()
                        .getParagraphs()
                        .clear();
            }
        }

        // Save the cleaned presentation
        presentation.saveToFile(
                "PresentationWithoutNotes.pptx",
                FileFormat.PPTX_2013
        );

        presentation.dispose();
    }
}

If you only want to remove a specific paragraph rather than clearing all notes, use removeAt():

notesSlide.getNotesTextFrame()
        .getParagraphs()
        .removeAt(1);

The paragraph collection uses a zero-based index, so removeAt(1) removes the second paragraph.

This gives you more control when the notes contain multiple pieces of information and only part of them should be deleted.

Add Notes to Multiple Slides

When presentations are generated automatically, speaker notes often come from the same data source as the visible slide content.

Suppose each slide has a corresponding presenter instruction stored in an array:

String[] speakerNotes = {
        "Introduce the overall project status.",
        "Explain the reason for the schedule change.",
        "Review the three main risks with the audience."
};

You can loop through the slides and insert the corresponding note:

for (int i = 0;
     i < presentation.getSlides().getCount()
             && i < speakerNotes.length;
     i++) {

    ISlide slide = presentation.getSlides().get(i);

    NotesSlide notesSlide = slide.getNotesSlide();

    if (notesSlide == null) {
        notesSlide = slide.addNotesSlide();
    }

    ParagraphEx paragraph = new ParagraphEx();
    paragraph.setText(speakerNotes[i]);

    notesSlide.getNotesTextFrame()
            .getParagraphs()
            .append(paragraph);
}

Here, the code checks whether the slide already has a notes slide before creating one:

if (notesSlide == null) {
    notesSlide = slide.addNotesSlide();
}

This is useful when modifying existing presentations because some slides may already contain notes while others do not.

It also prevents the program from assuming that every presentation starts from a completely blank notes state.

In a real application, the notes do not have to come from an array. They could come from JSON data, a database, an Excel file, an API response, or the same template data used to generate the slide itself.

For example, a training platform might store:

Slide title
Slide content
Instructor note

as separate fields for each training section. The visible content can then be written to the slide while the instructor note is stored as speaker notes.

Speaker Notes vs. Comments

Speaker notes and PowerPoint comments may both contain information that is not part of the visible slide content, but they serve different purposes.

Speaker notes are generally intended for the person presenting the slide deck. They often contain:

Talking points
Additional explanations
Reminders
Supporting facts
Transition cues
Instructions for demonstrations

Comments are mainly used during editing and review. They are more appropriate for feedback such as:

Replace this chart with the latest version.

or:

Please verify the Q3 revenue figure.

So if the information describes what the presenter should say, speaker notes are usually the better place for it.

If the information describes what another editor should change, a comment is generally more appropriate.

Keeping the two types of information separate also helps when presentations are processed automatically. An application can extract presenter instructions without mixing them with review comments.

Things to Consider When Processing Existing Presentations

When working with PowerPoint files created by other users, there are a few practical details worth considering.

First, not every slide has a notes slide. Always check whether getNotesSlide() returns null before attempting to read or modify the notes.

Second, existing notes may contain multiple paragraphs. Calling clear() removes all of them, so use removeAt() instead if only a specific paragraph should be deleted.

Finally, speaker notes may contain information that is not visible during a normal slide show but is still stored in the presentation file. If a presentation is being prepared for external distribution, checking the notes before sharing the file can help prevent internal instructions or unfinished remarks from being included accidentally.

How to Add Page Numbers to PDF in Java (Step-by-Step)

Leon Davis — Fri, 14 Aug 2026 10:56:26 +0000

Page numbers are a small detail, but they become important in reports, contracts, manuals, and other multi-page PDFs. They make printed documents easier to navigate and give reviewers a simple way to refer to a specific page.

When PDFs are generated or processed in a Java application, adding page numbers manually is not practical. A better approach is to add them programmatically after the document has been created or assembled.

In this article, we'll use Spire.PDF for Java to add dynamic page numbers in the format Page 1 of 10 to an existing PDF.

Install Spire.PDF for Java

If you use Maven, add the repository and Spire.PDF dependency to your pom.xml:

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.pdf</artifactId>
        <version>12.8.1</version>
    </dependency>
</dependencies>

Add "Page X of Y" to a PDF in Java

Spire.PDF for Java provides three useful classes for dynamic page numbering:

PdfPageNumberField represents the current page number.
PdfPageCountField represents the total number of pages.
PdfCompositeField combines these values into text such as Page 2 of 10.

This means you don't need to create a different page-number string for every page manually.

The following example adds a centered page number near the bottom of every page:

import com.spire.pdf.PdfDocument;
import com.spire.pdf.PdfPageBase;
import com.spire.pdf.automaticfields.PdfCompositeField;
import com.spire.pdf.automaticfields.PdfPageCountField;
import com.spire.pdf.automaticfields.PdfPageNumberField;
import com.spire.pdf.graphics.PdfBrush;
import com.spire.pdf.graphics.PdfBrushes;
import com.spire.pdf.graphics.PdfTrueTypeFont;

import java.awt.Font;
import java.awt.geom.Dimension2D;
import java.awt.geom.Point2D;

public class AddPageNumbers {

    public static void main(String[] args) {

        // Load the PDF document
        PdfDocument document = new PdfDocument();
        document.loadFromFile("input.pdf");

        // Set the font and color of the page number
        PdfTrueTypeFont font = new PdfTrueTypeFont(
                new Font("Arial", Font.PLAIN, 10), true);
        PdfBrush brush = PdfBrushes.getBlack();

        // Create fields for the current page number and total page count
        PdfPageNumberField pageNumberField = new PdfPageNumberField();
        PdfPageCountField pageCountField = new PdfPageCountField();

        // Combine the fields into "Page X of Y"
        PdfCompositeField pageNumber = new PdfCompositeField(
                font,
                brush,
                "Page {0} of {1}",
                pageNumberField,
                pageCountField
        );

        // Add the page number to each page
        for (int i = 0; i < document.getPages().getCount(); i++) {

            PdfPageBase page = document.getPages().get(i);
            Dimension2D pageSize = page.getSize();

            // Measure the displayed text so it can be centered
            String text = String.format(
                    "Page %d of %d",
                    i + 1,
                    document.getPages().getCount()
            );

            Dimension2D textSize = font.measureString(text);

            // Calculate the position at the bottom center of the page
            double x = (pageSize.getWidth() - textSize.getWidth()) / 2;
            double y = pageSize.getHeight() - 30;

            // Draw the page number
            pageNumber.setLocation(
                    new Point2D.Float((float) x, (float) y)
            );
            pageNumber.draw(page.getCanvas());
        }

        // Save the result
        document.saveToFile("output.pdf");
        document.dispose();
    }
}

The implementation is fairly short, but there are a few details worth understanding.

Step 1: Load the Existing PDF

Start by creating a PdfDocument object and loading the source PDF:

PdfDocument document = new PdfDocument();
document.loadFromFile("input.pdf");

This approach works for an existing PDF as well as a document generated earlier in the same application. The page-numbering code only needs to run before the final PDF is saved.

Step 2: Define the Page Number Appearance

Next, create a font and brush:

PdfTrueTypeFont font = new PdfTrueTypeFont(
        new Font("Arial", Font.PLAIN, 10), true);

PdfBrush brush = PdfBrushes.getBlack();

These settings control the font, size, style, and color of the page number.

For most reports, a relatively small font works well in the footer. You can change the font and size to match the rest of the document.

If the application runs on Linux or a server, make sure the font specified in the code is available in that environment. Otherwise, use a font that is installed on the target system.

Step 3: Create Dynamic Page Number Fields

Instead of calculating the page number and total page count yourself, create two automatic fields:

PdfPageNumberField pageNumberField = new PdfPageNumberField();
PdfPageCountField pageCountField = new PdfPageCountField();

PdfPageNumberField supplies the current page number, while PdfPageCountField supplies the total number of pages. Spire.PDF provides these fields specifically for dynamic information added to PDF pages.

They can then be combined with PdfCompositeField:

PdfCompositeField pageNumber = new PdfCompositeField(
        font,
        brush,
        "Page {0} of {1}",
        pageNumberField,
        pageCountField
);

Here, {0} is replaced by the current page number and {1} by the total page count.

For an eight-page PDF, the result will look like:

Page 1 of 8
Page 2 of 8
Page 3 of 8
...
Page 8 of 8

This is more convenient than preparing a separate string for every page, especially when the final page count is not known in advance.

Step 4: Process Each Page Separately

Next, iterate through the PDF:

for (int i = 0; i < document.getPages().getCount(); i++) {

    PdfPageBase page = document.getPages().get(i);
    Dimension2D pageSize = page.getSize();

    // ...
}

The page size is read inside the loop instead of assuming that every page has identical dimensions.

That matters when a PDF contains a mix of portrait and landscape pages or pages with different sizes. Each page can then have its page-number position calculated independently.

Step 5: Center the Page Number at the Bottom

To center the page number properly, first measure the text that will appear on the current page:

String text = String.format(
        "Page %d of %d",
        i + 1,
        document.getPages().getCount()
);

Dimension2D textSize = font.measureString(text);

Then calculate its coordinates:

double x = (pageSize.getWidth() - textSize.getWidth()) / 2;
double y = pageSize.getHeight() - 30;

The X coordinate centers the text horizontally, while the Y coordinate places it near the bottom of the page.

For existing PDFs, Spire.PDF uses a coordinate system whose origin is at the top-left corner. X increases to the right and Y increases downward, which is why a value close to the page height places the page number near the footer.

Finally, set the position and draw the field:

pageNumber.setLocation(
        new Point2D.Float((float) x, (float) y)
);

pageNumber.draw(page.getCanvas());

Because the position is calculated for each page, the page number remains centered even when page dimensions vary.

Change the Page Number Format

The displayed format is controlled by the format string passed to PdfCompositeField.

For example:

"Page {0}"

produces:

Page 1
Page 2
Page 3

For a shorter style, use:

"{0} / {1}"

which produces:

1 / 10

You can also combine page numbers with fixed footer text:

"Project Report | Page {0} of {1}"

The dynamic fields remain the same, so changing the format does not require changing the rest of the page-numbering logic.

Make Sure the Footer Has Enough Space

When adding page numbers to an existing PDF, check whether the bottom of the page already contains text, tables, signatures, or other content.

Drawing a page number does not automatically create extra footer space. If the original content already extends close to the bottom edge, the page number may overlap it.

In that case, adjust the Y coordinate:

double y = pageSize.getHeight() - 30;

to place the page number in a clearer area.

If you also control how the PDF is originally generated, reserving some footer space from the beginning is usually a better solution.

Conclusion

Adding page numbers programmatically is useful when reports, contracts, manuals, or other PDFs are generated in batches or assembled dynamically.

With Spire.PDF for Java, PdfPageNumberField and PdfPageCountField provide the current page number and total page count, while PdfCompositeField combines them into formats such as Page X of Y.

By calculating the position for each page, the same approach also works with PDFs that contain different page sizes or orientations. From there, the footer can be further customized with different formats, fonts, positions, or additional text.

How to Add, Edit, and Remove PDF Bookmarks in Java

Leon Davis — Fri, 07 Aug 2026 11:32:29 +0000

In long PDF documents such as project reports, product manuals, technical specifications, or contract collections, navigating page by page can quickly become inconvenient.

Bookmarks provide a simple way to organize the document structure and let readers jump directly to important sections from the navigation panel. Existing PDFs may also need bookmark maintenance when chapter names change, sections are removed, or the original bookmark structure is no longer accurate.

This article shows how to manage PDF bookmarks in Java, including how to:

Add bookmarks to a PDF
Create multi-level bookmarks
Edit existing bookmarks
Remove individual or all bookmarks

Install the Required PDF Library

This article uses Spire.PDF for Java to read and modify PDF files. It provides APIs for creating top-level and child bookmarks, changing bookmark properties, and removing existing bookmarks.

If you are using Maven, add the repository and dependency to your pom.xml:

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.pdf</artifactId>
        <version>12.6.1</version>
    </dependency>
</dependencies>

You can replace the version number with the current version used in your project.

After installing the library, load an existing PDF with PdfDocument and work with its bookmark collection.

Add Bookmarks to a PDF

Suppose a project report contains the following major sections:

Project Overview
Implementation Plan
Data Analysis
Recommendations

You can create one top-level bookmark for each section and link it to the corresponding page.

The following example adds bookmarks for the first four pages of a PDF.

import com.spire.pdf.PdfDocument;
import com.spire.pdf.PdfPageBase;
import com.spire.pdf.actions.PdfGoToAction;
import com.spire.pdf.bookmarks.PdfBookmark;
import com.spire.pdf.bookmarks.PdfTextStyle;
import com.spire.pdf.general.PdfDestination;
import com.spire.pdf.graphics.PdfRGBColor;

import java.awt.Color;
import java.awt.geom.Point2D;

public class AddPdfBookmarks {
    public static void main(String[] args) {

        // Create a PdfDocument object
        PdfDocument pdf = new PdfDocument();

        // Load the source PDF
        pdf.loadFromFile("ProjectReport.pdf");

        // Define bookmark titles
        String[] bookmarkTitles = {
                "Project Overview",
                "Implementation Plan",
                "Data Analysis",
                "Recommendations"
        };

        // Add bookmarks for the first four pages
        for (int i = 0; i < bookmarkTitles.length; i++) {

            PdfPageBase page = pdf.getPages().get(i);

            // Add a bookmark
            PdfBookmark bookmark =
                    pdf.getBookmarks().add(bookmarkTitles[i]);

            // Set the bookmark destination
            PdfDestination destination =
                    new PdfDestination(
                            page,
                            new Point2D.Float(0, 0)
                    );

            bookmark.setAction(
                    new PdfGoToAction(destination)
            );

            // Set the bookmark color
            bookmark.setColor(
                    new PdfRGBColor(
                            new Color(47, 84, 150)
                    )
            );

            // Display the bookmark in bold
            bookmark.setDisplayStyle(
                    PdfTextStyle.Bold
            );
        }

        // Save the result
        pdf.saveToFile("ProjectReportWithBookmarks.pdf");

        pdf.close();
    }
}

The process consists of three main parts.

First, create a bookmark in the document bookmark collection:

pdf.getBookmarks().add("Project Overview");

Next, create a PdfDestination that identifies the target page and position:

PdfDestination destination =
        new PdfDestination(
                page,
                new Point2D.Float(0, 0)
        );

Finally, connect the bookmark to that destination:

bookmark.setAction(
        new PdfGoToAction(destination)
);

One detail worth noting is that PDF page indexes start from 0.

For example:

get(0) → Page 1
get(1) → Page 2
get(2) → Page 3

If the actual chapter starts on another page, adjust the page index accordingly.

Create Multi-Level PDF Bookmarks

A single level of bookmarks may not be enough for a document with multiple sections and subsections.

For example:

Implementation Plan
├── Project Schedule
├── Team Assignment
└── Risk Management

In this case, child bookmarks can be added under a parent bookmark.

The following example creates one top-level bookmark and three child bookmarks.

import com.spire.pdf.PdfDocument;
import com.spire.pdf.PdfPageBase;
import com.spire.pdf.actions.PdfGoToAction;
import com.spire.pdf.bookmarks.PdfBookmark;
import com.spire.pdf.general.PdfDestination;

import java.awt.geom.Point2D;

public class AddChildBookmarks {
    public static void main(String[] args) {

        PdfDocument pdf = new PdfDocument();
        pdf.loadFromFile("ProjectReport.pdf");

        // Create the parent bookmark
        PdfBookmark parentBookmark =
                pdf.getBookmarks().add("Implementation Plan");

        // Link the parent bookmark to page 2
        PdfPageBase parentPage =
                pdf.getPages().get(1);

        PdfDestination parentDestination =
                new PdfDestination(
                        parentPage,
                        new Point2D.Float(0, 0)
                );

        parentBookmark.setAction(
                new PdfGoToAction(parentDestination)
        );

        // Add child bookmark: Project Schedule
        PdfBookmark scheduleBookmark =
                parentBookmark.add("Project Schedule");

        PdfDestination scheduleDestination =
                new PdfDestination(
                        pdf.getPages().get(1),
                        new Point2D.Float(0, 120)
                );

        scheduleBookmark.setAction(
                new PdfGoToAction(scheduleDestination)
        );

        // Add child bookmark: Team Assignment
        PdfBookmark teamBookmark =
                parentBookmark.add("Team Assignment");

        PdfDestination teamDestination =
                new PdfDestination(
                        pdf.getPages().get(2),
                        new Point2D.Float(0, 0)
                );

        teamBookmark.setAction(
                new PdfGoToAction(teamDestination)
        );

        // Add child bookmark: Risk Management
        PdfBookmark riskBookmark =
                parentBookmark.add("Risk Management");

        PdfDestination riskDestination =
                new PdfDestination(
                        pdf.getPages().get(3),
                        new Point2D.Float(0, 0)
                );

        riskBookmark.setAction(
                new PdfGoToAction(riskDestination)
        );

        pdf.saveToFile("ProjectReportWithNestedBookmarks.pdf");

        pdf.close();
    }
}

The important difference is that child bookmarks are added to the parent bookmark:

parentBookmark.add("Project Schedule");

rather than directly to:

pdf.getBookmarks()

This creates a real hierarchical bookmark structure.

For reports and manuals that already follow a chapter-and-section structure, multi-level bookmarks are usually easier to navigate than a long flat list.

Edit Existing PDF Bookmarks

PDF content often changes over time.

For example, a section originally named:

Project Plan

may later be renamed to:

Project Implementation Plan

If the PDF pages have already been updated, the bookmark can be edited directly instead of rebuilding the entire file.

The following example changes the title, color, and display style of the first bookmark.

import com.spire.pdf.PdfDocument;
import com.spire.pdf.bookmarks.PdfBookmark;
import com.spire.pdf.bookmarks.PdfTextStyle;
import com.spire.pdf.graphics.PdfRGBColor;

import java.awt.Color;

public class EditPdfBookmark {
    public static void main(String[] args) {

        PdfDocument pdf = new PdfDocument();

        // Load a PDF that already contains bookmarks
        pdf.loadFromFile("ProjectReport.pdf");

        // Get the first bookmark
        PdfBookmark bookmark =
                pdf.getBookmarks().get(0);

        // Change the bookmark title
        bookmark.setTitle("Project Implementation Plan");

        // Change the bookmark color
        bookmark.setColor(
                new PdfRGBColor(
                        new Color(31, 78, 121)
                )
        );

        // Display it in bold
        bookmark.setDisplayStyle(
                PdfTextStyle.Bold
        );

        // Save the result
        pdf.saveToFile("ProjectReportWithUpdatedBookmark.pdf");

        pdf.close();
    }
}

If only the title needs to change, the essential code is simply:

bookmark.setTitle("New Section Title");

Changing the color or text style is optional and depends on how the bookmark panel should be presented.

Remove a Specific PDF Bookmark

If a section has been removed from the document, its bookmark should usually be removed as well.

Otherwise, the bookmark may still point to a page that no longer represents the expected content.

A top-level bookmark can be removed with:

pdf.getBookmarks().removeAt(0);

For example:

import com.spire.pdf.PdfDocument;

public class DeletePdfBookmark {
    public static void main(String[] args) {

        PdfDocument pdf = new PdfDocument();

        pdf.loadFromFile("ProjectReport.pdf");

        // Remove the first top-level bookmark
        pdf.getBookmarks().removeAt(0);

        pdf.saveToFile("ProjectReportAfterBookmarkRemoval.pdf");

        pdf.close();
    }
}

The index also starts from 0, so removeAt(0) removes the first top-level bookmark.

If that bookmark contains child bookmarks, removing the parent also removes the bookmarks under it.

Remove a Child Bookmark

Sometimes only one subsection needs to be removed while the parent bookmark should remain.

In that case, get the parent bookmark first and remove the required child bookmark from it.

PdfBookmark parentBookmark =
        pdf.getBookmarks().get(0);

// Remove the first child bookmark
parentBookmark.removeAt(0);

This changes a structure such as:

Implementation Plan
├── Project Schedule   ← removed
├── Team Assignment
└── Risk Management

without deleting the entire Implementation Plan bookmark.

This is useful when only part of the document structure changes.

Remove All Bookmarks from a PDF

If the existing bookmark structure is completely outdated, it may be simpler to remove all bookmarks and rebuild them from scratch.

Use:

pdf.getBookmarks().clear();

A complete example looks like this:

import com.spire.pdf.PdfDocument;

public class DeleteAllPdfBookmarks {
    public static void main(String[] args) {

        PdfDocument pdf = new PdfDocument();

        pdf.loadFromFile("ProjectReport.pdf");

        // Remove all bookmarks
        pdf.getBookmarks().clear();

        pdf.saveToFile("ProjectReportWithoutBookmarks.pdf");

        pdf.close();
    }
}

This approach is useful when:

The existing bookmark structure is no longer valid
The document has been reorganized significantly
Bookmarks need to be regenerated from a new table of contents
PDFs from different sources contain inconsistent bookmark structures

Practical Considerations

1. Remember That Page Indexes Start from 0

This is one of the easiest mistakes to make when assigning bookmark destinations.

If a business rule says that a bookmark should point to page 5, the corresponding code is:

pdf.getPages().get(4);

If page numbers are stored externally as normal one-based numbers, convert them before accessing the PDF page collection:

int pageIndex = pageNumber - 1;

This is particularly important when generating many bookmarks automatically.

2. Validate the Target Page Before Creating a Bookmark

If bookmark definitions come from a database, configuration file, or another external source, do not assume that every page number is valid.

For example:

int pageIndex = 10;

if (pageIndex >= 0 &&
        pageIndex < pdf.getPages().getCount()) {

    PdfPageBase page =
            pdf.getPages().get(pageIndex);

    // Create the bookmark here
}

This avoids failures caused by invalid page references.

3. Keep Bookmark Titles Consistent with the Document Structure

If a visible section heading is:

3. Project Implementation Plan

but the bookmark is simply:

Plan

the bookmark technically works, but the navigation structure becomes less clear.

For automatically generated reports, it is usually better to reuse the same chapter titles for both the document body and the bookmarks.

For example:

String[] chapterNames = {
        "1. Project Overview",
        "2. Implementation Plan",
        "3. Data Analysis",
        "4. Recommendations"
};

This makes the document body, table of contents, and bookmark panel easier to keep consistent.

4. Avoid Excessively Deep Bookmark Hierarchies

PDF bookmarks support nested levels, but a very deep structure can become difficult to use.

For many reports and manuals, a structure such as:

Chapter
└── Section

or:

Chapter
└── Section
    └── Subsection

is usually enough.

If the source data contains six or seven hierarchical levels, consider exposing only the most useful levels as PDF bookmarks rather than reproducing the full internal structure.

Conclusion

Bookmarks provide a practical navigation layer for long PDF documents such as reports, manuals, specifications, and contract collections.

This article covered how to use Java to:

Add top-level bookmarks to a PDF
Create parent-child bookmark structures
Edit bookmark titles and styles
Remove individual top-level or child bookmarks
Remove all bookmarks from a PDF

For automatically generated PDFs, bookmarks can be created from the same chapter names and page information used to build the document. For existing PDFs, outdated bookmark structures can be edited or rebuilt without recreating the entire file.

Keeping the bookmark structure aligned with the actual document makes long PDFs easier to navigate and easier to maintain.

How to Create Drop-Down Lists in Excel with C#

Leon Davis — Fri, 07 Aug 2026 11:26:36 +0000

In employee records, order forms, project trackers, and other Excel templates, some fields should only contain predefined values, such as departments, task statuses, approval results, or product categories.

If users enter these values manually, the same option can easily appear in different forms. For example, a task status might be entered as In Progress, In progress, or an abbreviated variation. This creates extra cleanup work later when the workbook is filtered, summarized, or imported into another system.

Adding drop-down lists to these cells gives users a controlled set of choices and helps reduce inconsistent data at the point of entry.

This article shows how to create Excel drop-down lists in C# in three common scenarios:

Use fixed values as drop-down options
Use a cell range in the current worksheet as the data source
Use data from another worksheet as the drop-down source

Install the Required Excel Library

This article uses Spire.XLS for .NET to create and modify Excel files. It supports Excel data validation, including list-based drop-downs, and does not require Microsoft Excel to be installed on the machine running the code.

You can install it through NuGet Package Manager Console:

Install-Package Spire.XLS

Then import the required namespace:

using Spire.Xls;

The implementation depends mainly on where the drop-down values come from.

Create an Excel Drop-Down List from Fixed Values

If the available options are limited and unlikely to change often, the simplest approach is to define them directly in a string array.

For example, a task management sheet may restrict the task status to:

Not Started
In Progress
Completed
On Hold

The following example creates a simple task table and adds a status drop-down list to cell D2.

using Spire.Xls;

namespace CreateExcelDropdown
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a Workbook object
            Workbook workbook = new Workbook();

            // Get the first worksheet
            Worksheet sheet = workbook.Worksheets[0];
            sheet.Name = "Task Management";

            // Add headers
            sheet.Range["A1"].Text = "Task ID";
            sheet.Range["B1"].Text = "Task Name";
            sheet.Range["C1"].Text = "Owner";
            sheet.Range["D1"].Text = "Status";

            // Add sample data
            sheet.Range["A2"].Text = "T001";
            sheet.Range["B2"].Text = "Prepare Project Plan";
            sheet.Range["C2"].Text = "Alice Johnson";

            // Define drop-down options
            string[] statusValues =
            {
                "Not Started",
                "In Progress",
                "Completed",
                "On Hold"
            };

            // Apply the drop-down list to D2
            sheet.Range["D2"].DataValidation.Values = statusValues;

            // Auto-fit columns
            sheet.AllocatedRange.AutoFitColumns();

            // Save the workbook
            workbook.SaveToFile(
                "TaskStatusDropdown.xlsx",
                ExcelVersion.Version2016);

            workbook.Dispose();
        }
    }
}

The key line is:

sheet.Range["D2"].DataValidation.Values = statusValues;

DataValidation.Values accepts a string array and uses the array items as the available list values.

This approach works well for fixed choices such as:

Status
Priority
Enabled / Disabled
Approval result
Fixed categories

If the options are numerous or change frequently, hard-coding them in the application is less convenient. In that case, storing the values in worksheet cells is usually easier to maintain.

Create a Drop-Down List from a Cell Range

Sometimes the available options already exist inside the workbook.

For example, an employee worksheet may contain a department list in F2:F5:

Cell	Value
F2	Sales
F3	Finance
F4	IT
F5	Human Resources

The Department field can then use that range as its drop-down source.

using Spire.Xls;

namespace CreateDropdownFromRange
{
    class Program
    {
        static void Main(string[] args)
        {
            Workbook workbook = new Workbook();

            Worksheet sheet = workbook.Worksheets[0];
            sheet.Name = "Employees";

            // Create the employee table
            sheet.Range["A1"].Text = "Employee ID";
            sheet.Range["B1"].Text = "Employee Name";
            sheet.Range["C1"].Text = "Department";

            sheet.Range["A2"].Text = "E001";
            sheet.Range["B2"].Text = "John Smith";

            // Create the department source list
            sheet.Range["F1"].Text = "Department List";
            sheet.Range["F2"].Text = "Sales";
            sheet.Range["F3"].Text = "Finance";
            sheet.Range["F4"].Text = "IT";
            sheet.Range["F5"].Text = "Human Resources";

            // Get the source range
            CellRange departmentRange = sheet.Range["F2:F5"];

            // Use the range as the drop-down source
            sheet.Range["C2"].DataValidation.DataRange =
                departmentRange;

            sheet.AllocatedRange.AutoFitColumns();

            workbook.SaveToFile(
                "DepartmentDropdown.xlsx",
                ExcelVersion.Version2016);

            workbook.Dispose();
        }
    }
}

The main difference here is:

sheet.Range["C2"].DataValidation.DataRange = departmentRange;

Using a worksheet range as the data source makes the list easier to maintain.

For example, if another department is added later, the source data can be updated in the workbook rather than duplicated as a long list of hard-coded values in C#.

This approach is useful when the source values already belong to the same worksheet.

In larger business templates, however, storing helper values beside the main data can make the sheet look cluttered. A more common design is to keep these values on a separate worksheet.

Create a Drop-Down List from Another Worksheet

In real-world templates, business data and lookup values are often stored separately.

For example, a workbook might contain:

Employees: stores employee information
Options: stores departments, job titles, statuses, and other lookup values

This keeps the main worksheet cleaner and makes the source values easier to manage.

The following example creates a drop-down list whose values come from another worksheet.

using Spire.Xls;

namespace CreateCrossSheetDropdown
{
    class Program
    {
        static void Main(string[] args)
        {
            Workbook workbook = new Workbook();

            // Get the employee worksheet
            Worksheet employeeSheet = workbook.Worksheets[0];
            employeeSheet.Name = "Employees";

            // Add the options worksheet
            Worksheet optionsSheet =
                workbook.Worksheets.Add("Options");

            // -------------------------
            // Employees worksheet
            // -------------------------

            employeeSheet.Range["A1"].Text = "Employee ID";
            employeeSheet.Range["B1"].Text = "Employee Name";
            employeeSheet.Range["C1"].Text = "Department";

            employeeSheet.Range["A2"].Text = "E001";
            employeeSheet.Range["B2"].Text = "John Smith";

            // -------------------------
            // Options worksheet
            // -------------------------

            optionsSheet.Range["A1"].Text = "Department List";
            optionsSheet.Range["A2"].Text = "Sales";
            optionsSheet.Range["A3"].Text = "Finance";
            optionsSheet.Range["A4"].Text = "IT";
            optionsSheet.Range["A5"].Text = "Human Resources";

            // Allow data validation to reference another worksheet
            workbook.Allow3DRangesInDataValidation = true;

            // Get the department source range
            CellRange departmentRange =
                optionsSheet.Range["A2:A5"];

            // Apply the source range to the Department field
            employeeSheet.Range["C2"]
                .DataValidation.DataRange = departmentRange;

            employeeSheet.AllocatedRange.AutoFitColumns();
            optionsSheet.AllocatedRange.AutoFitColumns();

            workbook.SaveToFile(
                "CrossSheetDropdown.xlsx",
                ExcelVersion.Version2016);

            workbook.Dispose();
        }
    }
}

One setting is easy to overlook when the validation source is on another worksheet:

workbook.Allow3DRangesInDataValidation = true;

This allows the data validation rule to reference a range outside the current worksheet.

After enabling it, you can set the source range normally:

employeeSheet.Range["C2"].DataValidation.DataRange =
    optionsSheet.Range["A2:A5"];

This layout works well for business templates that need centrally maintained lookup values.

A workbook might be organized like this:

Workbook
│
├── Employees
│   ├── Employee ID
│   ├── Employee Name
│   └── Department ▼
│
└── Options
    ├── Sales
    ├── Finance
    ├── IT
    └── Human Resources

If end users do not need to see the helper data, the Options worksheet can also be hidden.

Apply the Same Drop-Down List to Multiple Cells

The previous examples apply data validation to a single cell, but real templates usually need the same list across many rows.

For example, to apply the department list to C2:C100:

employeeSheet.Range["C2:C100"]
    .DataValidation.DataRange = departmentRange;

The same approach works with fixed values:

string[] statusValues =
{
    "Not Started",
    "In Progress",
    "Completed",
    "On Hold"
};

sheet.Range["D2:D100"].DataValidation.Values =
    statusValues;

Applying validation to a range is simpler than looping through cells one by one and is usually a better fit for generated Excel templates.

Which Approach Should You Use?

The main difference between the three approaches is where the drop-down values are stored.

Data Source	Implementation	Best For
Fixed strings	`DataValidation.Values`	Status, priority, approval results, and other fixed options
Current worksheet range	`DataValidation.DataRange`	Simple templates with a small amount of helper data
Another worksheet	`DataValidation.DataRange` + `Allow3DRangesInDataValidation`	Business templates with centrally managed lookup values

For a small fixed set such as Yes / No or Enabled / Disabled, a string array is usually the simplest choice.

If the values change regularly or come from business data, using a cell range is easier to maintain.

For long-lived templates such as employee forms, order forms, or project tracking workbooks, keeping lookup values on a dedicated worksheet is often the cleaner approach.

Practical Considerations

1. Avoid Hard-Coding Frequently Changing Options

Suppose a department list originally contains:

Sales
Finance
IT

and later needs:

Customer Service

If the entire list is hard-coded in C#, the application must be updated and redeployed.

If the values come from a database, configuration source, or admin system, a more maintainable workflow is:

Read the latest values from the business system
Write them to an Options worksheet
Point the data validation rule to that range

This keeps the generated workbook aligned with the current business data.

2. Keep the Source Range in Sync

If the drop-down list points to:

A2:A5

but the actual list later grows to A8, the new values will not appear unless the validation source range is updated.

For dynamic data, calculate the final row when generating the workbook.

For example:

int lastRow = 8;

employeeSheet.Range["C2:C100"]
    .DataValidation.DataRange =
    optionsSheet.Range["A2:A" + lastRow];

This makes the source range follow the actual number of available options.

3. Excel Drop-Down Lists Do Not Replace Server-Side Validation

Excel data validation helps reduce user input errors, but it should not be treated as the only validation layer if the data will later be imported into a database or business system.

For example, even if the Department field uses a drop-down list, the import process can still verify that the selected department is currently valid.

This is important because Excel validation can sometimes be bypassed through copy and paste, external editing tools, or direct file manipulation.

4. Dependent Drop-Down Lists Require Additional Logic

Some lists depend on a previous selection, for example:

Country → City
Product Category → Product
Department → Job Title

A simple fixed list is not enough in these cases.

Dependent drop-downs usually require a combination of:

Named ranges
Data validation formulas
Excel functions such as INDIRECT

It is therefore worth deciding whether the options are independent or hierarchical before designing the workbook template.

Conclusion

Drop-down lists are a practical way to improve data consistency in Excel templates generated with C#.

This article covered three common approaches:

Creating a drop-down list from fixed string values
Using a cell range in the current worksheet as the data source
Referencing values stored on another worksheet

For small and stable option sets, a string array is usually sufficient. For values that need regular maintenance or come from business systems, storing the options in worksheet cells and using them as the validation source is generally more flexible.

Choosing the data source based on how the options are maintained makes the resulting Excel file easier to use and easier to keep in sync with the rest of the application.

How to Create and Update a Table of Contents in Word Using Java

Leon Davis — Fri, 31 Jul 2026 12:57:03 +0000

Project reports, product manuals, technical documents, and other long-form Word files often contain multiple chapters and sections. As the content changes, section titles, chapter order, and page numbers may also change.

Maintaining the table of contents manually is repetitive and can easily result in missing headings or incorrect page numbers.

A Word table of contents is a field generated from the heading styles used in the document. As long as the document uses Heading 1, Heading 2, Heading 3, and other built-in heading styles correctly, the table of contents can be inserted programmatically and updated after the document changes.

This article demonstrates how to use Java to:

Create a Word document with multilevel headings
Generate a table of contents from Heading 1 through Heading 3
Insert a table of contents into an existing Word document
Update heading text and page numbers in an existing table of contents
Control which heading levels appear in the table of contents

How Word Identifies Headings for a Table of Contents

A Word table of contents normally uses paragraph styles to determine the heading hierarchy.

For example:

Document Content	Word Style	TOC Level
1. Project Overview	Heading 1	Level 1
1.1 Project Background	Heading 2	Level 2
1.1.1 Project Goals	Heading 3	Level 3

Making text bold or increasing its font size does not automatically make it a heading. The paragraph must use an actual Word heading style.

In Java, the following built-in styles can be applied:

BuiltinStyle.Heading_1
BuiltinStyle.Heading_2
BuiltinStyle.Heading_3

The appendTOC() method specifies the heading levels included in the table of contents, while updateTableOfContents() recalculates the entries and page numbers based on the current document structure.

Install the Word Library

The examples below use Spire.Doc for Java to create and edit Word documents.

Add the following repository and dependency to the pom.xml file of a Maven project:

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>
            https://repo.e-iceblue.com/nexus/content/groups/public/
        </url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.doc</artifactId>
        <version>14.6.0</version>
    </dependency>
</dependencies>

The version number can be changed to the version currently used in your project.

Import the required classes:

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.Section;
import com.spire.doc.documents.BreakType;
import com.spire.doc.documents.BuiltinStyle;
import com.spire.doc.documents.HorizontalAlignment;
import com.spire.doc.documents.Paragraph;
import com.spire.doc.fields.TextRange;

Create a Word Document with a Table of Contents in Java

The following example creates a Word document from scratch and inserts a table of contents containing Heading 1 through Heading 3.

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.Section;
import com.spire.doc.documents.BreakType;
import com.spire.doc.documents.BuiltinStyle;
import com.spire.doc.documents.HorizontalAlignment;
import com.spire.doc.documents.Paragraph;
import com.spire.doc.fields.TextRange;

public class CreateWordWithToc {

    public static void main(String[] args) {

        // Create a Word document
        Document document = new Document();

        try {
            // Add a section
            Section section = document.addSection();

            // Add the table of contents title
            Paragraph tocTitle = section.addParagraph();
            TextRange titleText = tocTitle.appendText(
                    "Table of Contents"
            );

            titleText.getCharacterFormat().setBold(true);
            titleText.getCharacterFormat().setFontSize(18);

            tocTitle.getFormat().setHorizontalAlignment(
                    HorizontalAlignment.Center
            );

            // Insert a table of contents containing
            // Heading 1 through Heading 3
            Paragraph tocParagraph = section.addParagraph();
            tocParagraph.appendTOC(1, 3);

            // Insert a page break after the table of contents
            tocParagraph.appendBreak(BreakType.Page_Break);

            // Add a level-one heading
            addHeading(
                    section,
                    "1. Project Overview",
                    BuiltinStyle.Heading_1
            );

            addBodyText(
                    section,
                    "This chapter introduces the project background, "
                            + "main objectives, and implementation scope."
            );

            // Add level-two headings
            addHeading(
                    section,
                    "1.1 Project Background",
                    BuiltinStyle.Heading_2
            );

            addBodyText(
                    section,
                    "As the scale of the business grows, the existing "
                            + "management approach is no longer sufficient "
                            + "for centralized operations."
            );

            addHeading(
                    section,
                    "1.2 Project Objectives",
                    BuiltinStyle.Heading_2
            );

            addBodyText(
                    section,
                    "The project will establish a unified platform for "
                            + "data management and business collaboration."
            );

            // Add level-three headings
            addHeading(
                    section,
                    "1.2.1 Business Objectives",
                    BuiltinStyle.Heading_3
            );

            addBodyText(
                    section,
                    "Standardize business processes and improve "
                            + "cross-department collaboration."
            );

            addHeading(
                    section,
                    "1.2.2 Technical Objectives",
                    BuiltinStyle.Heading_3
            );

            addBodyText(
                    section,
                    "Create a scalable and maintainable system architecture."
            );

            // Add another level-one heading
            addHeading(
                    section,
                    "2. Implementation Plan",
                    BuiltinStyle.Heading_1
            );

            addBodyText(
                    section,
                    "This chapter describes the implementation stages "
                            + "and major project tasks."
            );

            addHeading(
                    section,
                    "2.1 Implementation Stages",
                    BuiltinStyle.Heading_2
            );

            addBodyText(
                    section,
                    "The project includes requirements analysis, "
                            + "system design, development, testing, "
                            + "and deployment."
            );

            // Update the table of contents based on
            // the current headings and pagination
            document.updateTableOfContents();

            // Save the document
            document.saveToFile(
                    "WordDocumentWithTOC.docx",
                    FileFormat.Docx_2019
            );

        } finally {
            document.dispose();
        }
    }

    /**
     * Add a heading paragraph.
     */
    private static void addHeading(
            Section section,
            String text,
            BuiltinStyle style
    ) {
        Paragraph paragraph = section.addParagraph();
        paragraph.appendText(text);
        paragraph.applyStyle(style);
    }

    /**
     * Add a body paragraph.
     */
    private static void addBodyText(
            Section section,
            String text
    ) {
        Paragraph paragraph = section.addParagraph();
        paragraph.appendText(text);
        paragraph.getFormat().setAfterSpacing(10);
    }
}

After the code runs, it creates:

WordDocumentWithTOC.docx

The first page contains the table of contents, while the main document starts on the next page. The table of contents includes level-one, level-two, and level-three headings together with their page numbers.

Understanding the appendTOC() Parameters

The following code creates a table of contents containing Heading 1 through Heading 3:

tocParagraph.appendTOC(1, 3);

The two parameters represent:

Starting heading level
Ending heading level

For example, to include only Heading 1 and Heading 2:

tocParagraph.appendTOC(1, 2);

To include only Heading 1:

tocParagraph.appendTOC(1, 1);

For most project reports and technical documents, three heading levels are usually sufficient. Including too many levels may make the table of contents difficult to scan and unnecessarily long.

Insert a Table of Contents into an Existing Word Document

In many cases, the Word document already contains the main content and only needs a table of contents added at the beginning.

The following example loads an existing Word file and inserts the table of contents at the beginning of the first section.

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.Section;
import com.spire.doc.documents.BreakType;
import com.spire.doc.documents.HorizontalAlignment;
import com.spire.doc.documents.Paragraph;
import com.spire.doc.fields.TextRange;

public class AddTocToExistingDocument {

    public static void main(String[] args) {

        Document document = new Document();

        try {
            // Load an existing Word document
            document.loadFromFile("ProjectReport.docx");

            // Get the first section
            Section firstSection =
                    document.getSections().get(0);

            // Create the table of contents title
            Paragraph tocTitle = new Paragraph(document);
            TextRange titleText = tocTitle.appendText(
                    "Table of Contents"
            );

            titleText.getCharacterFormat().setBold(true);
            titleText.getCharacterFormat().setFontSize(18);

            tocTitle.getFormat().setHorizontalAlignment(
                    HorizontalAlignment.Center
            );

            // Create the table of contents paragraph
            Paragraph tocParagraph = new Paragraph(document);
            tocParagraph.appendTOC(1, 3);

            // Insert a page break after the table of contents
            tocParagraph.appendBreak(BreakType.Page_Break);

            // Insert the title and table of contents
            // at the beginning of the first section
            firstSection.getParagraphs().insert(
                    0,
                    tocTitle
            );

            firstSection.getParagraphs().insert(
                    1,
                    tocParagraph
            );

            // Update the table of contents
            document.updateTableOfContents();

            // Save the result as a new file
            document.saveToFile(
                    "ProjectReportWithTOC.docx",
                    FileFormat.Docx_2019
            );

        } finally {
            document.dispose();
        }
    }
}

The result is saved as a new file instead of overwriting the source document:

ProjectReport.docx
ProjectReportWithTOC.docx

The headings in the original document must already use styles such as Heading 1, Heading 2, and Heading 3. Otherwise, the table of contents field may be inserted successfully but contain few or no entries.

Apply Heading Styles to Ordinary Paragraphs

If the section titles in an existing document are ordinary paragraphs, heading styles can be applied before generating the table of contents.

For example, suppose the third paragraph in the first section is a level-one heading and the fifth paragraph is a level-two heading:

Section section = document.getSections().get(0);

section.getParagraphs()
        .get(2)
        .applyStyle(BuiltinStyle.Heading_1);

section.getParagraphs()
        .get(4)
        .applyStyle(BuiltinStyle.Heading_2);

After applying the styles, insert and update the table of contents:

Paragraph tocParagraph = new Paragraph(document);
tocParagraph.appendTOC(1, 3);

section.getParagraphs().insert(
        0,
        tocParagraph
);

document.updateTableOfContents();

This approach works well with documents that follow a fixed template.

For documents with an unpredictable structure, relying entirely on paragraph indexes is risky. Adding or removing a paragraph changes the indexes of all subsequent paragraphs.

A more reliable approach is to identify headings by their text, existing styles, bookmarks, or other document markers.

Update an Existing Word Table of Contents

When section titles, chapter order, or document length changes, the table of contents should be updated.

The following example changes a heading and then refreshes the table of contents:

import com.spire.doc.Document;
import com.spire.doc.FileFormat;

public class UpdateWordToc {

    public static void main(String[] args) {

        Document document = new Document();

        try {
            // Load a Word document containing a table of contents
            document.loadFromFile(
                    "WordDocumentWithTOC.docx"
            );

            // Change a heading
            document.replace(
                    "2. Implementation Plan",
                    "2. Project Implementation Plan",
                    false,
                    true
            );

            // Update the TOC entries and page numbers
            document.updateTableOfContents();

            // Save the updated document
            document.saveToFile(
                    "UpdatedWordTOC.docx",
                    FileFormat.Docx_2019
            );

        } finally {
            document.dispose();
        }
    }
}

After the update, the table of contents entry:

2. Implementation Plan

becomes:

2. Project Implementation Plan

If the document changes cause a heading to move to another page, the corresponding page number is recalculated as well.

Prevent the TOC Title from Appearing in the Table of Contents

The table of contents page often includes a title such as “Table of Contents.”

That title should not use the Heading 1 style unless it is intended to appear as an entry inside the table of contents.

Instead, format it manually:

Paragraph tocTitle = section.addParagraph();

TextRange textRange =
        tocTitle.appendText("Table of Contents");

textRange.getCharacterFormat().setBold(true);
textRange.getCharacterFormat().setFontSize(18);

tocTitle.getFormat().setHorizontalAlignment(
        HorizontalAlignment.Center
);

Avoid applying a heading style like this:

tocTitle.applyStyle(BuiltinStyle.Heading_1);

Otherwise, “Table of Contents” may appear as a level-one entry inside the table itself.

Common Problems When Updating a Table of Contents

The Table of Contents Is Empty

This usually means the section headings do not use formal Word heading styles.

Bold text, larger font sizes, or different colors do not make a paragraph part of the heading hierarchy.

Apply an actual heading style:

paragraph.applyStyle(BuiltinStyle.Heading_1);

The same applies to Heading 2, Heading 3, and other levels.

Level-Three Headings Are Missing

Check the ending level passed to appendTOC().

The following code includes only Heading 1 and Heading 2:

tocParagraph.appendTOC(1, 2);

To include Heading 3 as well, use:

tocParagraph.appendTOC(1, 3);

Page Numbers Have Not Changed

After modifying the document content, call:

document.updateTableOfContents();

If the document is saved without updating the table of contents, it may continue to display outdated entries or page numbers.

The Table of Contents Appears Before the Cover Page

If the document contains a cover page, place the table of contents in a separate section after the cover instead of inserting it at the first paragraph of the document.

A suitable document structure is:

Section 1: Cover page
Section 2: Table of contents
Section 3: Main content

This approach is more appropriate for formal reports, proposals, and product manuals.

Heading Numbers Are Duplicated

Heading styles define the hierarchy but do not automatically guarantee that manually entered chapter numbers are correct.

For example:

1. Project Overview
1.1 Project Background

If the numbers are written directly in the heading text, the program must ensure that they match the actual heading hierarchy.

When Word multilevel lists are used for automatic numbering, both the list formatting and heading styles need to be maintained.

Practical Considerations

Use a Consistent Heading Structure

A reliable table of contents depends on a consistent document hierarchy.

For example:

Heading 1: Main chapters
Heading 2: Sections
Heading 3: Subsections

Avoid using the same heading level for unrelated structural purposes.

Save the Output as a New File

When adding or updating a table of contents in an existing document, save the result as a new file:

ProjectReport.docx
ProjectReportWithTOC.docx

This keeps the source document available in case the heading styles, pagination, or table of contents layout need to be adjusted.

Keep the Number of TOC Levels Reasonable

Although Word supports several heading levels, including too many levels may reduce readability.

For most business and technical documents, one to three levels are enough.

Check the Result in Word

Automatic generation can handle the heading entries and page numbers, but the result should still be reviewed in Word.

Pay particular attention to:

Long heading text
Page breaks
Section breaks
Headers and footers
Landscape pages
Tables that affect pagination

Conclusion

Java can be used to automate common Word table of contents operations, including:

Creating Heading 1 through Heading 3 paragraphs
Generating a table of contents from heading styles
Inserting a table of contents into an existing Word document
Updating heading text and page numbers
Controlling which heading levels appear
Placing the table of contents between the cover page and main content

The most important part of the process is not the table of contents field itself, but the document’s heading structure.

When headings use the correct Word styles, updateTableOfContents() can regenerate the entries and page numbers after the document changes, reducing the need for manual maintenance.