Caret Annotations

• Jul 21, 2026
• 2 minutes to read

A caret annotation marks the location where text should be inserted or revised. Unlike free text annotations, a caret annotation does not contain visible text on the page. It displays a caret symbol and stores a comment that explains the proposed change.

To create a caret annotation, do the following:

1. Create a CaretAnnotation object and specify annotation bounds.
2. Use the setContent(String value) method to specify the annotation comment.
3. (Optional) Specify additional markup annotation properties, such as the author, subject, opacity, etc.
4. Add the annotation to the page’s annotation collection.

The following code snippet creates a caret annotation, specifies its comment, and adds the annotation to a page:

package pdf;

import com.devexpress.docs.pdf.*;
import com.devexpress.system.drawing.*;

import java.nio.channels.*;
import java.nio.file.*;

public class Main {
    public static void main(String[] args) throws Exception {
        try (FileChannel fileChannel = FileChannel.open(Path.of("Document.pdf"));
             PdfDocument pdfDocument = new PdfDocument(fileChannel)) {

            Page page = pdfDocument.getPages().getFirst();

            createCaretAnnotation(page);

            // Save the document.
            try (WritableByteChannel channel =
                        FileChannel.open(Path.of("Result.pdf"),
                                StandardOpenOption.CREATE,
                                StandardOpenOption.WRITE,
                                StandardOpenOption.TRUNCATE_EXISTING)) {

                pdfDocument.save(channel);
            }
        }
    }

    static void createCaretAnnotation(Page page) {
        CaretAnnotation annotation =
                new CaretAnnotation(
                        new RectangleF(70, 350, 18, 18));

        annotation.setTitle("John Smith");
        annotation.setSubject("Editorial Review");
        annotation.setContent("Insert a new paragraph.");
        annotation.setColor(PdfColor.getGreen());
        annotation.setOpacity(0.8);

        page.getAnnotations().add(annotation);
    }
}

The following screenshot illustrates the result: