Guides

Annotations

The ComPDF Flutter SDK supports multiple annotation event listeners to help you customize annotation interaction behaviors in your Flutter application.

Event Overview

Event Name	Trigger Timing	Return Value
onAnnotationCreationPreparedCallback	When preparing to create signature, stamp, link, or image annotations	Annotation type
onInterceptAnnotationActionCallback	When clicking note or link annotations	CPDFAnnotation object
annotationsCreated	When creating annotations	Created annotation data
annotationsSelected	When selecting annotations	Selected annotation data
annotationsDeselected	When deselecting annotations	Deselected annotation data

Annotation Creation Prepared Callback

Callback method: onAnnotationCreationPreparedCallback

This callback is triggered when the user clicks signature, stamp, link, or image tools in the bottom toolbar, or calls controller.setAnnotationMode() to enter creation mode.

Through this callback, you can display custom selection dialogs in your Flutter application instead of using ComPDF's built-in selection dialogs.

Configuration

To use this feature, disable the default selection dialogs in CPDFConfiguration:

CPDFConfiguration(
  annotationsConfig: const CPDFAnnotationsConfig(
    autoShowSignPicker: false,   // Disable signature selection dialog
    autoShowLinkDialog: false,   // Disable link selection dialog
    autoShowPicPicker: false,    // Disable image selection dialog
    autoShowStampPicker: false,  // Disable stamp selection dialog
  ),
);

Listen to Callback

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onCreated: (controller) {},
  onAnnotationCreationPreparedCallback: (CPDFAnnotationType annotationType, CPDFAnnotation? annotation) {
    // Signature, stamp, image annotations: triggered when entering creation mode
    // Link annotations: triggered after user draws a rectangle on the page
    debugPrint('Preparing to create annotation of type: $annotationType');
    // Display custom selection dialog here
  },
);

Insert Signature

After selecting a signature image, call the following API to insert a signature annotation:

await controller?.prepareNextSignature(signImagePath);

Insert Stamp

After selecting a stamp, call the corresponding API based on stamp type:

// Standard stamp (see CPDFStandardStamp enum for available types)
await controller?.prepareNextStamp(standardStamp: stamp);

// Image stamp
await controller?.prepareNextStamp(imagePath: imagePath);

// Text stamp
await controller?.prepareNextStamp(
  textStamp: CPDFTextStamp(
    content: 'ComPDF-Flutter',
    date: CPDFDate.getTextStampDate(timeSwitch: false, dateSwitch: true),
    shape: CPDFTextStampShape.none,
    color: CPDFTextStampColor.white,
  ),
);

Annotation Action Intercept Callback

Callback method: onInterceptAnnotationActionCallback

This callback is triggered when the user clicks a note or link annotation, returning a CPDFAnnotation object. Through this callback, you can intercept the default click behavior in the Flutter layer to implement custom interaction logic.

Configuration

To use this feature, enable interception of default annotation click behaviors in CPDFConfiguration:

CPDFConfiguration(
  annotationsConfig: const CPDFAnnotationsConfig(
    interceptNoteAction: true,  // Intercept note default action
    interceptLinkAction: true,  // Intercept link default action
  ),
);

Listen to Callback

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onCreated: (controller) {},
  onInterceptAnnotationActionCallback: (CPDFAnnotation annotation) {
    debugPrint('Intercepted annotation action: ${annotation.type}');
    // Customize click behavior based on annotation type
    if (annotation is CPDFNoteAnnotation) {
      // Custom note click handling
    } else if (annotation is CPDFLinkAnnotation) {
      // Custom link click handling
    }
  },
);

Annotation Created Event

Event name: CPDFEvent.annotationsCreated

Triggered when the user creates an annotation, listen via CPDFReaderWidgetController.addEventListener():

controller.addEventListener(CPDFEvent.annotationsCreated, (event) {
  // event is CPDFAnnotation object or its subclass objects
  print(jsonEncode(event));
});

Annotation Selected Event

Event name: CPDFEvent.annotationsSelected

Triggered when the user selects an annotation:

controller.addEventListener(CPDFEvent.annotationsSelected, (event) {
  // event is CPDFAnnotation object or its subclass objects
  print(jsonEncode(event));
});

Annotation Deselected Event

Event name: CPDFEvent.annotationsDeselected

Triggered when the user deselects an annotation:

controller.addEventListener(CPDFEvent.annotationsDeselected, (event) {
  // event is CPDFAnnotation object or its subclass objects, may be null
  print(jsonEncode(event));
});