QR Code Form Fields

CPDFQRCodeWidget creates, reads, and modifies QR code fields in a PDF page. The content is supplied as an ordinary Java string and encoded as UTF-8; ComPDFKit then draws the QR code into the field appearance stream (/AP) as vector rectangles. Because nothing is rasterized, the QR code prints and zooms cleanly at any resolution and the document does not carry an extra image resource.

A QR code field is a standard AcroForm Widget annotation. It requires neither JavaScript nor XFA, so the saved document opens in any conforming PDF reader.

Error Correction Levels

The error correction level decides how much of the QR code can be damaged, dirty, or obscured while still being readable. ComPDFKit exposes the four levels defined by the QR code specification through CPDFQRCodeWidget.ErrorCorrectionLevel:

Value	Recoverable damage	Recommended for
`ErrorCorrectionLevel.L`	About 7%	Long content, clean and controlled scanning conditions.
`ErrorCorrectionLevel.M`	About 15%	General purpose. This is the default.
`ErrorCorrectionLevel.Q`	About 25%	Codes that may pick up light wear or smudging.
`ErrorCorrectionLevel.H`	About 30%	Printed labels, logistics, or anything placed over a background.

A higher level costs capacity: the same field can hold less text, and the generated code usually contains more modules, so each module is drawn smaller within the same rectangle. Raise the level when the code will be printed or handled, and keep it at M when the content is long.

Quiet Zone

The quiet zone is the plain white margin that scanners rely on to locate the code. setQuietZoneModules(int) sets its width in QR modules, not in PDF points, so the margin scales with the code instead of with the page. Valid values are 4 to 64, and the default is 4 — the minimum required by the specification.

Since the quiet zone is drawn inside the field rectangle, increasing it shrinks the code itself. Enlarge it when the QR code sits on a dark or busy background and needs more separation, and leave it at the default otherwise.

Generate and Regenerate the Appearance

updateQRCodeAppearance() encodes the current content and redraws the appearance from the current error correction level, quiet zone, and field rectangle. Calling updateAp() on a QR code field does the same thing, so the field behaves like every other widget in a generic form loop.

Any successful call to setContent(), setErrorCorrectionLevel(), setQuietZoneModules(), or setRect() discards the existing appearance. Always finish a batch of property changes with a single updateQRCodeAppearance() call — there is no need to regenerate after every setter.

Note that setContent() only validates the string. Whether the text actually fits is decided during encoding, so updateQRCodeAppearance() is the call that reports a content-too-long failure.

Read an Existing QR Code

Open the document, walk the annotations of a page, and pick out the QR code fields. Both a type check and the widget type enumeration work:

java

CPDFDocument document = new CPDFDocument();
document.open(pdfPath);
CPDFPage page = document.pageAtIndex(0);

for (CPDFAnnotation annotation : page.getAnnotations()) {
  if (annotation instanceof CPDFQRCodeWidget) {
    CPDFQRCodeWidget qrCodeWidget = (CPDFQRCodeWidget) annotation;
    String content = qrCodeWidget.getContent();
    CPDFQRCodeWidget.ErrorCorrectionLevel level = qrCodeWidget.getErrorCorrectionLevel();
    int quietZone = qrCodeWidget.getQuietZoneModules();
    boolean hasAppearance = qrCodeWidget.hasAp();
  }
}

getContent() returns null when the widget is invalid; getErrorCorrectionLevel() and getQuietZoneModules() fall back to the defaults M and 4 when the document carries no valid setting.

Update an Existing QR Code

Change the properties you need and regenerate the appearance once at the end:

java

qrCodeWidget.setContent("https://www.compdf.com/contact-us");
qrCodeWidget.setErrorCorrectionLevel(CPDFQRCodeWidget.ErrorCorrectionLevel.Q);
// setContent and setErrorCorrectionLevel both invalidate the old appearance.
qrCodeWidget.updateQRCodeAppearance();

Delete a QR Code

A QR code field is deleted the same way as any other form field, through the annotation interface:

java

qrCodeWidget.removeFromPage();

The object must not be used again after it has been removed.

API Summary

Method	Description
`setContent(String content)`	Sets the text to encode. Fails on `null` or empty content.
`getContent()`	Returns the encoded text, or `null` if the widget is invalid.
`setErrorCorrectionLevel(ErrorCorrectionLevel level)`	Sets the error correction level. The default is `M`.
`getErrorCorrectionLevel()`	Returns the current level, or `M` if none is set.
`setQuietZoneModules(int modules)`	Sets the white margin in QR modules, from `4` to `64`.
`getQuietZoneModules()`	Returns the quiet zone width, or `4` if none is set.
`updateQRCodeAppearance()`	Encodes the content and redraws the vector appearance.
`addToAcroFormFields()`	Registers the field in the document AcroForm fields array.
`setRect(RectF rect)`	Sets the position on the page. Inherited, invalidates the appearance.
`setFieldName(String name)`	Sets the AcroForm field name. Inherited.
`hasAp()`	Reports whether an appearance stream is currently present. Inherited.
`removeFromPage()`	Removes the field from the page. Inherited.

Error Handling

Every setter and generator returns a boolean, so a failure can be traced to the exact step:

Step	Common cause of failure
`addFormWidget(Widget_QRCode, document)`	The page is invalid, or the license does not include form permissions.
`setRect()`	The widget is invalid.
`setContent()`	The content is `null` or empty.
`setErrorCorrectionLevel()`	The level is `null`.
`setQuietZoneModules()`	The value is outside `[4, 64]`.
`updateQRCodeAppearance()`	The content is empty or exceeds the capacity of the code, or the rectangle has a width or height of zero.
`addToAcroFormFields()`	The document or its AcroForm is in an invalid state.

If a step fails and the new field is no longer wanted, call removeFromPage() to undo the creation before saving.

Notes and Limitations

The API generates QR codes only. It does not recognize or decode QR codes from an existing page or image.
The content must be a non-empty string without an embedded NUL character.
The usable content length depends on both the character set and the error correction level; a higher level leaves room for less text.
A square rectangle is recommended. A non-square rectangle is accepted — the code is scaled to the shorter side and centred — but it wastes space.
After changing content, error correction level, quiet zone, or rectangle, the appearance must be regenerated before saving, otherwise the field is written without a visible QR code.
Call addToAcroFormFields() once the field is configured so that it is saved as a standard form field and stays compatible with common PDF readers.
Flattening the document turns the QR code into static page content, which is a convenient way to lock it before distribution. See Flatten Forms.

QR Code Form Fields ​

QR Code Form Fields