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.

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:

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:

CPDFAnnotationType currentType = await _controller?.getAnnotationMode();

The CPDFAnnotationType enum supports the following annotation types:

Annotation Type	Enum Value
Text Note	note
Highlight	highlight
Underline	underline
Squiggly	squiggly
Strikeout	strikeout
Ink	ink
Pencil	pencil
Circle	circle
Rectangle	square
Arrow	arrow
Line	line
Free Text	freetext
Signature	signature
Stamp	stamp
Link	link
Sound	sound
Exit Drawing Mode	unknown

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

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.

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.

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.

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

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

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

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

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);

• Create Link Annotations

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

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);

---