Configuring Annotation Presets in Our Viewer

Annotation presets (PSPDFKit.AnnotationPreset) are preconfigured settings for annotation buttons. They allow you to, for example, set the default color of an ink annotation.

PSPDFKit for Web includes presets for all annotations and annotation variants, which hold either the annotation’s default values for each annotation property or the modified property values that correspond to the variant.

For example, the default annotation preset for the arrow variant, which is a line annotation with an arrow on one end, includes the following property-value pairs:

{
  startPoint: new PSPDFKit.Geometry.Point(),
  endPoint: new PSPDFKit.Geometry.Point(),
  fillColor: null,
  strokeColor: new PSPDFKit.Color({
    r: 36,
    g: 131,
    b: 199
  })),
  strokeDashArray: null,
  strokeWidth: 5,
  lineCaps: {
    end: "openArrow"
  }
}

PSPDFKit.AnnotationPreset

Annotation presets are modified either when a user changes the settings using the annotation toolbar, or by programmatically using the API function PSPDFKit.setAnnotationPresets. You can opt out of the updates made using the toolbar by preventing them in the PSPDFKit.AnnotationPresetsUpdateEvent handler.

PSPDFKit for Web includes default annotation presets PSPDFKit.defaultAnnotationPresets for all the annotation buttons and their variants. These default presets can be overridden in the initial configuration before loading a PDF instance:

const annotationPresets = PSPDFKit.defaultAnnotationPresets;
annotationPresets.ink = {
  lineWidth: 10
};
PSPDFKit.load({ annotationPresets });

var annotationPresets = PSPDFKit.defaultAnnotationPresets;
annotationPresets.ink = {
  lineWidth: 10
};
PSPDFKit.load({ annotationPresets: annotationPresets });

Annotation presets can also be modified after the instance has been loaded.

In the example below, the line item preset is modified so that line annotations have a black color by default. If the user modifies the annotation settings via the toolbar, the corresponding annotation preset is updated, so these changes are persisted in the annotation preset by default. Preset updates can be prevented by intercepting annotationPresets.update and opting out of the update with event.preventDefault():

instance.setAnnotationPresets(presets => {
  presets.line = {
    ...presets.line,
    strokeColor: new PSPDFKit.Color({ r: 0, g: 0, b: 0 })
  };
  return presets;
});
instance.addEventListener("annotationPresets.update", event => {
  event.preventDefault();
});

instance.setAnnotationPresets(function(presets) {
  presets.line = Object.assign(presets.line, {
    strokeColor: new PSPDFKit.Color({ r: 0, g: 0, b: 0 })
  });
  return presets;
});
instance.addEventListener("annotationPresets.update", function(event) {
  event.preventDefault();
});

Annotation button variants can be modified as well. In this example, we modify the preset for the arrow variant of PSPDFKit.Annotations#LineAnnotation so that it uses a thicker stroke and a different title:

instance.setAnnotationPresets(presets => {
  presets.thick = {
    ...presets.arrow,
    strokeWidth: 15
  };
  return presets;
});
instance.setToolbarItems(items => {
  return items.map(i => {
    if (i.type === "arrow") {
      return {
        ...i,
        preset: "thick",
        title: "My thick arrow"

      };
    }
    return i;
  });
});

instance.setAnnotationPresets(function(presets) {
  presets.thick = Object.assign(presets.arrow, { strokeWidth: 15 });
  return presets;
});
instance.setToolbarItems(function(items) {
  return items.map(function(i) {
    if (i.type === "arrow") {
      return Object.assign(i, {
        preset: "thick",
        title: "My thick arrow"
      });
    }
    return i;
  });
});

Custom Annotation Presets

Custom annotation presets can also be created and used by annotation toolbar items (PSPDFKit.ToolbarItem). In the example below, a custom preset is created and associated with the line annotation toolbar item:

instance.setAnnotationPresets(presets => ({
  ...presets,
  customPreset: {
    strokeWidth: 15
  }
}));
instance.setToolbarItems(items =>
  items.map(item =>
    item.type === "line" ? { ...item, preset: "customPreset" } : item
  )
);

instance.setAnnotationPresets(function(presets) {
  presets.customPreset = {
    strokeWidth: 15
  };
  return presets;
});
instance.setToolbarItems(function(items) {
  return items.map(function(item) {
    if (item.type === "line") {
      item.preset = "customPreset";
    }
    return item;
  });
});

Setting the Current Annotation Preset

When the user presses one of the default toolbar annotation buttons to create annotations, PSPDFKit for Web automatically sets the current annotation preset to the default one for that annotation or the custom preset specified on the preset property of the toolbar item as described in the previous section. Notice that it is not automatically changed otherwise. However, it is possible to programmatically specify the current annotation preset to use and reset it by calling the PSPDFKit.Instance#setCurrentAnnotationPreset method.

One possible use case of this is changing the current annotation preset just before setting a different interaction mode (e.g. when implementing a custom toolbar item):

// Setting an annotation preset for a closed arrow line annotation.
let instance = null;

const annotationPresets = PSPDFKit.defaultAnnotationPresets;
annotationPresets.line = {
  ...annotationPresets.line,
  lineCaps: {
    end: "closedArrow"
  }
};

const customItem = {
  type: "custom",
  title: "Arrow",
  onPress() {
    instance.setCurrentAnnotationPreset("line");
    instance.setViewState(viewState =>
      viewState.set("interactionMode", PSPDFKit.InteractionMode.SHAPE_LINE)
    );
  }
};

PSPDFKit.load({
  annotationPresets,
  toolbarItems: [...PSPDFKit.defaultToolbarItems, customItem]
  // ...
}).then(_instance => {
  instance = _instance;
});

Please refer to the API documentation to learn more about annotation presets.