Specify annotation appearance streams in UWP

An annotation or form element in a PDF can specify an appearance stream, which allows the annotation to be rendered differently than its default annotation rendering. Each appearance stream is a self-contained PDF object that will be rendered inside the annotation bounding box. (See also: What Are Appearance Streams?)

Most appearance streams are just a visual representation of an annotation’s properties. This helps third-party PDF viewers that may be unable to directly generate a visual representation of those properties; these viewers can render the appearance stream instead. Appearance streams also ensure that the annotations in a document are displayed exactly as they were created in the source PDF editor, without subtle differences that could occur if the third-party PDF viewer had to recreate the annotations from raw annotation data.

However, sometimes appearance streams contain surprises. For example, square annotations may have an appearance stream with a photograph. There are a lot of edge cases out there, so one cannot disable appearance stream rendering and assume the annotation will look the same or even close to it.

ℹ️ Note: If you’re using Document Engine, please note that appearance stream rendering only works for documents uploaded after upgrading to 2020.3.0.

PSPDFKit for Windows lets you render existing appearance streams by setting PSPDFKit.UI.ViewState.AppearanceStreamTypes before loading a document with the relevant ViewState:

await PDFView.Controller.ShowDocumentWithViewStateAsync(documentSource, new ViewState
{
    AppearanceStreamTypes = new[]
    {
        AnnotationType.Highlight,
        AnnotationType.Text,
        AnnotationType.Note
    }
});

The annotation types contained in AppearanceStreamTypes will be rendered using their respective appearance streams, if they exist. Otherwise, the rendering will use the default PSPDFKit appearance for the respective annotation type. When an annotation’s appearance has been customized (like in the square annotation with a photograph example above), this setting allows for a visual result closer to the original.

Only annotations that were present in the document when it was opened may be rendered using their AP streams. If any visual property of an annotation is modified, its appearance stream will be considered invalidated, meaning it no longer reflects the annotation’s properties and therefore won’t be used.

Image and stamp annotations, as well as digitally signed signature form field widgets, are an exception to this; they will always be rendered using their AP streams, and they won’t need to be added to the AppearanceStreamTypes property.

Keep in mind that enabling this feature may affect performance, as each annotation appearance needs to be rendered separately. Moreover, the original appearance will still be hidden while the annotation is being resized, modified, or edited, and it may be removed completely if the annotation is modified.

A list of all annotation types can be found within the AnnotationType enumerator, listed here for the sake of convenience:

AppearanceStreamTypes = new[]
{
    AnnotationType.Highlight,
    AnnotationType.Squiggly,
    AnnotationType.Strikeout,
    AnnotationType.Underline,
    AnnotationType.Text,
    AnnotationType.Note,
    AnnotationType.Link,
    AnnotationType.Ink,
    AnnotationType.Ellipse,
    AnnotationType.Line,
    AnnotationType.Polygon,
    AnnotationType.Polyline,
    AnnotationType.Rectangle,
    AnnotationType.Image,
    AnnotationType.Stamp,
    AnnotationType.Widget,
    AnnotationType.Redaction
}

ℹ️ Note: Syncing appearance streams is currently not supported by PSPDFKit Instant.