ComPDF
Contact Sales
DemoFAQ
、

PDF Generation Template Editor

Open-source visual PDF generation engine with customizable templates and developer-friendly APIs.

View on GitHub
Guides

Create Annotations ​

ComPDF supports a wide variety of annotation types, including text notes, links, shapes, highlights, stamps, freehand drawings, and audio annotations, fully meeting diverse annotation requirements.

Creating Annotations

The ComPDF Flutter SDK provides two ways to create annotations:

  1. Through the CPDFReaderWidget component's annotation mode (recommended).
  2. Through the CPDFDocument API for programmatic creation.

Interactive Annotation Creation ​

Using CPDFReaderWidget, users can enter annotation mode, select an annotation type from the bottom toolbar, and add annotations through touch interactions. You can also set the annotation type programmatically using the controller.setAnnotationMode(CPDFAnnotationType type) method.

dart
CPDFReaderWidgetController? _controller;

// Initialize CPDFReaderWidget and get the controller in the onCreated callback
CPDFReaderWidget(
  document: widget.documentPath,
  password: widget.password,
  configuration: widget.configuration,
  onCreated: (controller) {
    setState(() {
      _controller = controller;
    });
  },
);

await _controller?.setAnnotationMode(CPDFAnnotationType.highlight);

Exiting Annotation Mode ​

To exit annotation mode after finishing the operation, call:

dart
await _controller?.setAnnotationMode(CPDFAnnotationType.unknown);

Get Current Annotation Type ​

You can retrieve the current annotation type to check whether you are in annotation mode or determine the selected tool:

dart
CPDFAnnotationType currentType = await _controller?.getAnnotationMode();

The CPDFAnnotationType enum supports the following annotation types:

Annotation TypeEnum Value
Text Notenote
Highlighthighlight
Underlineunderline
Squigglysquiggly
Strikeoutstrikeout
Inkink
Pencilpencil
Circlecircle
Rectanglesquare
Arrowarrow
Lineline
Free Textfreetext
Signaturesignature
Stampstamp
Linklink
Soundsound
Exit Drawing Modeunknown

Programmatic Annotation Creation ​

ComPDF also supports creating annotations programmatically through the CPDFDocument API. The following examples demonstrate how to create various types of annotations on a specified page:

Note that the rect parameter defines the position and size of the annotation on the page. The coordinate system origin is located at the bottom-left corner of the page.

  • Create Note Annotation ​

dart
final annotations = [
  CPDFNoteAnnotation(
    page: 0,
    createDate: DateTime.now(),
    title: 'ComPDF-Flutter',
    content: 'This is Note Annotation',
    rect: const CPDFRectF(left: 260, top: 740, right: 300, bottom: 700),
    color: Colors.green,
    alpha: 255)
];
await controller.document.addAnnotations(annotations);

  • Create Markup Annotations ​

Markup annotations include Highlight, Underline, Squiggly, and Strikeout types.

dart
final annotations = [
  CPDFMarkupAnnotation(
    type: CPDFAnnotationType.highlight,
    page: 1,
    createDate: DateTime.now(),
    title: 'ComPDF-Flutter',
    content: 'This is Highlight Annotation',
    rect: const CPDFRectF(left: 55, top: 800, right: 180, bottom: 770),
    markedText: 'Annotations',
    color: Colors.green,
    alpha: 200),
];
await controller.document.addAnnotations(annotations);

  • Create Ink Annotations ​

Ink annotations do not require the rect parameter; instead, they determine position through the inkPath.

dart
final annotations = [
  CPDFInkAnnotation(
    page: 0,
    color: Colors.deepOrangeAccent,
    borderWidth: 10,
    inkPath: [
      [
        [176.43, 72.22],
        [206.94, 78.95],
        [217.57, 82.21],
        [227.0, 85.49],
        [232.42, 87.92],
        [243.73, 91.83],
        [254.87, 97.98],
        [269.0, 104.22],
        [281.4, 110.47],
        // ... more points
      ]
    ],
  )
];
await controller.document.addAnnotations(annotations);

  • Create Shape Annotations ​

The shape annotations include Square, Circle, Line, and Arrow types.

dart
final annotations = [
  CPDFSquareAnnotation( // Square annotation example
    page: 0,
    title: 'Square',
    content: 'This is a square annotation with long content. ',
    createDate: DateTime.now(),
    rect: const CPDFRectF(left: 20, top: 200, right: 200, bottom: 100),
    borderWidth: 5,
    borderColor: Colors.deepOrangeAccent,
    fillColor: Colors.lightGreenAccent,
    effectType: CPDFBorderEffectType.solid,
    borderAlpha: 255,
    dashGap: 0,
    fillAlpha: 100),
  CPDFCircleAnnotation( // Circle annotation example
    page: 0,
    title: 'Circle-A',
    content: 'This is a circle annotation.',
    createDate: DateTime.now(),
    rect: const CPDFRectF(left: 220, top: 200, right: 360, bottom: 100),
    borderWidth: 5,
    borderColor: Colors.blueAccent,
    fillColor: Colors.yellowAccent,
    effectType: CPDFBorderEffectType.solid,
    borderAlpha: 255,
    fillAlpha: 120,
    dashGap: 0),
  CPDFLineAnnotation( // Line annotation example, line annotations do not require rect parameter
    type: CPDFAnnotationType.line,
    title: 'Line-A',
    page: 1,
    createDate: DateTime.now(),
    content: 'This is a line annotation.',
    borderWidth: 6,
    borderColor: Colors.purple,
    borderAlpha: 255,
    fillColor: Colors.transparent,
    fillAlpha: 255,
    points: [
      [504, 219],   // Start point coordinates
      [320, 88],    // End point coordinates
    ]),
  CPDFLineAnnotation( // Arrow annotation example
    type: CPDFAnnotationType.arrow,
    title: 'Arrow-A',
    page: 1,
    createDate: DateTime.now(),
    content: 'This is an arrow annotation.',
    points: [
      [288, 342],   // Start point coordinates
      [159, 209]    // End point coordinates
    ],
    borderWidth: 6,
    borderColor: Colors.teal,
    borderAlpha: 255,
    fillColor: Colors.transparent,
    fillAlpha: 255,
    lineHeadType: CPDFLineType.square,
    lineTailType: CPDFLineType.openArrow,
    dashGap: 0)
];
await controller.document.addAnnotations(annotations);

  • Create Free Text Annotations ​

dart
final annotations = [
  CPDFFreeTextAnnotation(
    title: 'Freetext',
    page: 0,
    createDate: DateTime.now(),          
    content: 'Hello, ComPDF!',
    rect: const CPDFRectF(left: 30, top: 750, right: 230, bottom: 700),
    textAttribute: CPDFTextAttribute(
      color: Colors.black,
      familyName: 'Times',
      styleName: 'Bold',
      fontSize: 20,
    ),
    alpha: 255,
    alignment: CPDFAlignment.left)
];
await controller.document.addAnnotations(annotations);

The familyName and styleName parameters are optional. If not specified, the system default font will be used. You can use the ComPDFKit.getFonts() method to retrieve the list of system-supported fonts.

  • Create Stamp Annotations ​

dart
final annotations = [
  CPDFStampAnnotation(  // Standard stamp annotation example
    page: 0,
    title: 'Stamp-A',
    createDate: DateTime.now(),
    content: 'Approved',
    rect: const CPDFRectF(left: 20, top: 300, right: 200, bottom: 260),
    stampType: CPDFStampType.standard,
    standardStamp: CPDFStandardStamp.accepted),

  CPDFStampAnnotation(  // Custom text stamp annotation example
    page: 0,
    title: 'Stamp-A',
    createDate: DateTime.now(),
    content: 'Custom Text Stamp',
    rect: const CPDFRectF(left: 220, top: 300, right: 350, bottom: 260),
    stampType: CPDFStampType.text,
    textStamp: CPDFTextStamp(
      content: 'Test Text',
      date: CPDFDate.getTextStampDate(timeSwitch: false, dateSwitch: true),
      shape: CPDFTextStampShape.leftTriangle,
      color: CPDFTextStampColor.red))
];
await controller.document.addAnnotations(annotations);

  • Create Image Annotations ​

dart
final annotations = [
  CPDFImageAnnotation(
    page: 0,
    createDate: DateTime.now(),
    title: 'Stamp-Image',
    content: 'Custom Image Stamp',
    rect: const CPDFRectF(left: 380, top: 420, right: 550, bottom: 260),
    image: 'iVBORw0KGgoAAAANSUhEUgAAAgIAAABzCAY...') // Image data, supports Base64 encoded string
];
await controller.document.addAnnotations(annotations);

  • Create Signature Annotations ​

dart
final annotations = [
  CPDFSignatureAnnotation(
    page: 1,
    createDate: DateTime.now(),
    title: 'Stamp-Image',
    content: 'Signature',
    rect: const CPDFRectF(left: 380, top: 420, right: 550, bottom: 260),
    image: 'iVBORw0KGgoAAAANSUhEUgAAAg...') // Image data, supports Base64 encoded string
];
await controller.document.addAnnotations(annotations);
dart
final annotations = [
  CPDFLinkAnnotation(  // Link to webpage
    title: 'ComPDF-Flutter',
    page: 0,
    createDate: DateTime.now(),
    content: 'Link Annotation',
    rect: const CPDFRectF(left: 248, top: 799, right: 407, bottom: 732),
    action: CPDFUriAction(uri: 'https://www.compdf.com')),

  CPDFLinkAnnotation(  // Navigate to specific page
    title: 'ComPDF-Flutter',
    page: 0,
    createDate: DateTime.now(),
    content: 'Link Annotation',
    rect: const CPDFRectF(left: 374, top: 304, right: 530, bottom: 236),
    action: CPDFGoToAction(pageIndex: 2)),

  CPDFLinkAnnotation(  // Send email
    title: 'ComPDF-Flutter',
    page: 0,
    content: 'Link Annotation',
    createDate: DateTime.now(),
    rect: const CPDFRectF(left: 374, top: 199, right: 529, bottom: 121),
    action: CPDFUriAction.email(email: '[email protected]')),
];

await controller.document.addAnnotations(annotations);

  • Create Sound Annotations ​

dart
final annotations = [
  CPDFSoundAnnotation(
    title: 'ComPDF-Flutter',
    page: 0,
    content: 'Link Annotation',
    rect: const CPDFRectF(left: 75, top: 607, right: 119, bottom: 563),
    soundPath: soundPath.path), // Audio file path
];
await controller.document.addAnnotations(annotations);