Guides

Custom Annotation Creation Workflows

Several APIs relate to annotation events but serve different purposes:

Goal	API	Effect on SDK Default Behavior
Observe that an annotation was created	CPDFEvent.annotationsCreated	No change.
Replace the default Signature, Image, Stamp, Link, or Note creation UI	onAnnotationCreationPreparedCallback	After the matching automatic UI is disabled, the app must complete or cancel the creation workflow.
Handle taps on existing Note or Link annotations	onInterceptAnnotationActionCallback	After interception is enabled, the SDK no longer edits the Note or follows the Link.
Handle taps on selected form field types	onInterceptWidgetActionCallback	After interception is enabled, the SDK no longer performs its default action for those field types.

Customize Annotation Creation

Annotation Type	Configuration to Disable	annotation Parameter	Required App Action
CPDFAnnotationType.signature	autoShowSignPicker: false	null	Select an image, then call prepareNextSignature().
CPDFAnnotationType.stamp	autoShowStampPicker: false	null	Select a stamp, then call prepareNextStamp().
CPDFAnnotationType.pictures	autoShowPicPicker: false	null	Select an image, then call prepareNextImage().
CPDFAnnotationType.link	autoShowLinkDialog: false	Created CPDFLinkAnnotation	Set action, then call document.updateAnnotation(). Remove the annotation if the user cancels.
CPDFAnnotationType.note	autoShowNoteEditDialog: false	Created CPDFNoteAnnotation	Set content, then call document.updateAnnotation(). Remove the annotation if the user cancels.

final configuration = CPDFConfiguration(
  annotationsConfig: const CPDFAnnotationsConfig(
    autoShowSignPicker: false,
    autoShowStampPicker: false,
    autoShowPicPicker: false,
    autoShowLinkDialog: false,
    autoShowNoteEditDialog: false,
  ),
);

Signatures, stamps, and images have not yet been placed on the page when the callback runs:

await controller.prepareNextSignature(signaturePath);
await controller.prepareNextImage(imagePath);
await controller.prepareNextStamp(
  standardStamp: CPDFStandardStamp.approved,
);

Links and Notes already exist when the callback runs. Changing the Dart object alone does not write the change back to the PDF; update or remove it explicitly:

if (annotation is CPDFNoteAnnotation) {
  annotation.content = 'Updated note content';
  await controller.document.updateAnnotation(annotation);
}

// Remove the object if the user cancels the custom dialog.
if (annotation != null) {
  await controller.document.removeAnnotation(annotation);
}

For a complete Note create, confirm, and cancel workflow, see Create Annotations.

Intercept Actions on Existing Annotations

Set interceptNoteAction or interceptLinkAction to true in CPDFAnnotationsConfig. Flutter must then handle Note editing, web links, or page navigation in onInterceptAnnotationActionCallback. Do not enable interception if you only need to observe a tap without replacing the default behavior.

Intercept Form-Field Actions

List only the CPDFFormType values that require custom handling in CPDFFormsConfig.interceptFormWidgetActions. After changing the CPDFWidget received by the callback, call controller.document.updateWidget(widget) to write the result to the PDF. Use interceptAllFormWidgetActions: true only when the app implements complete behavior for every form field type.