Guides

Annotations

The ComPDF Flutter SDK supports multiple annotation event listeners. Below are commonly used annotation events:

Event Name	Description
onAnnotationCreationPreparedCallback	Triggered when user prepares to create signature, stamp, link, or image annotations. Returns annotation type.
annotationsCreated	Triggered when user creates annotations, returns created annotation data.
annotationsSelected	Triggered when user selects annotations, returns selected annotation data.
annotationsDeselected	Triggered when user deselects annotations, returns deselected annotation data.

Below is an explanation of the related callback events:

onAnnotationCreationPreparedCallback is triggered when clicking signature, stamp, link, or image tools in annotation mode, or when calling controller.setAnnotationMode() to enter annotation creation mode. Through this callback, you can display custom selection dialogs in your Flutter app instead of using ComPDF's built-in selection dialogs. This feature requires configuration in CPDFConfiguration to disable the default selection dialogs for these four annotation types:

CPDFConfiguration(
      annotationsConfig: const CPDFAnnotationsConfig(
          // Disable default selection dialogs for signature, stamp, link, and image annotations
          autoShowSignPicker: false,
          autoShowLinkDialog: false,
          autoShowPicPicker: false,
          autoShowStampPicker: false,
      ),
);

To listen to onAnnotationCreationPreparedCallback events, pass the corresponding callback function when creating CPDFReaderWidget. For example:

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onCreated: (controller) {},
  onAnnotationCreationPreparedCallback: (CPDFAnnotationType annotationType, CPDFAnnotation? annotation) {
    // Signature, stamp, and image annotations trigger this callback when entering creation mode
    // (clicking toolbar button or calling controller.setAnnotationMode()).
    // Link annotations trigger this callback after user draws a rectangle.
    debugPrint('Preparing to create annotation of type: $annotationType');
    // You can pop up custom selection dialogs here for user to choose signatures, stamps, images, etc.
  },
);

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 standard stamp, image stamp, or text stamp, call the following API to insert a stamp annotation:

// Insert standard stamp. Check CPDFStandardStamp enum for available stamp types.
await controller?.prepareNextStamp(standardStamp: stamp);

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

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

Using the above methods, you can customize the signature and stamp selection process in your Flutter app while leveraging ComPDF's powerful annotation creation features.

To listen to other annotation events, call the following function through CPDFReaderWidgetController after creating CPDFReaderWidget. For example:

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

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

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