Appearance of annotations and form fields

Annotations (for example notes, stamps or lines) and form fields (for example check boxes or list boxes) can come without an appearance of their own. A PDF viewer then has to draw them itself. webPDF has to do the same whenever it needs the visual result: when rendering pages (image export, OCR, barcode recognition), when converting pages to HTML or SVG, when rasterizing pages while redacting (sanitize/pages of the redact operation), when flattening annotations and forms, when importing form data and when refreshing the appearance of form fields.

webPDF draws them like Adobe Acrobat.

What webPDF draws

• Notes, attachment and sound icons
• Clouded polygons
• Lines with leader lines and captions
• Highlights as plain rectangles
• Smoothed ink strokes
• Free text with rich text (/RC); free text without rich text is drawn as before
• Stamps, with the label as an outline and with the Acrobat colors
• Check boxes, radio buttons and push buttons, with border styles and icon
• Unsigned signature fields
• List boxes
• Rich text values of text fields

Links keep the border the PDF engine draws for them. Acrobat writes no appearance for a link and draws the border itself when it displays the page; an image or HTML page created by webPDF would otherwise lose it.

The annotations that the "Toolbox" web service creates as rectangle, circle and line are drawn by the generator of the PDF engine.

Appearances a document already has are kept where the server kept them before: rendering and flattening draw only what is missing. Filling a form field or refreshing its appearance creates the field's appearance anew, as in previous releases, but in the Acrobat style.

When form data with a rich text value is imported into a rich text field, webPDF draws the value with its formatting in the appearance of the field.

Characters the font does not have

The text of an annotation or form field is drawn with the font of its appearance, for example the font of the default appearance (/DA) of a form field. A character that this font does not have is not left out. webPDF draws it with a substitute font from the font directories of the web service that does the work (see fonts): first the default font of that web service, then the further fonts of the substitution chain, including "Go Noto Current" and the CJK and emoji fonts installed with webPDF. The substitute font is embedded as a subset in the appearance; the rest of the text keeps its font.

This applies to free text, line captions, push button captions, text fields, combo boxes and list boxes, when flattening annotations and forms, when redacting and when rendering pages (images, transcribe, OCR, barcode recognition).

• Line breaks: words break at the line break opportunities of Unicode, so text in Chinese, Japanese or Thai, which has no spaces, wraps correctly. A word stays together across a change of font or style. A vertical tab, a form feed and the NEL character count as a line break.
• Font selection in rich text: an entry of font-family that is longer than 256 characters is ignored. Of a very long value only the beginning counts (the first 64 entries), and at most 16 families are searched.
• Overflow: text that is longer than its box is written completely below the edge of the box. It is not visible, as before, but it is part of the content of the page and can be extracted.
• Right to left and shaping: a character of a script that is written from right to left or needs shaping (for example Hebrew, Arabic and the Indian scripts) that the font of the appearance does not have is not drawn with a substitute font, because the result would be mirrored or unshaped. It ends the operation as described under "Errors".

Form fields

Filling a form field with a value that the font of the field does not have now succeeds: the value is drawn with a substitute font. Before, such a value ended the operation with TOOLBOX_FORMS_INVALID_FIELD_VALUE = -1016. This error remains if no font has the character, for the scripts mentioned above and if the value of a comb field is longer than its /MaxLen.

A form with NeedAppearances is handled when it is loaded: every field that can be drawn receives its appearance. The flag is removed only if no problem occurred. A field that cannot be drawn keeps the flag set and is reported when that field is rendered or flattened (-1213 or -1205, see below). Filling the field again with a value that can be drawn solves it.

Every widget of a form field counts, also one that is hidden (Hidden) or invisible (Invisible): a widget whose appearance cannot be created completely when filling, importing or redrawing ends the operation with an error, because a hidden widget could be shown later with an incomplete or old appearance. This includes a widget whose own default appearance (/DA) names a font that cannot be loaded: the operation ends with TOOLBOX_ANNOTATION_CONTENT_CREATION_ERROR = -1205, and the other widgets are drawn.

A caption of a push button that cannot be drawn ends the operation with TOOLBOX_ANNOTATION_INVALID_CHAR_IN_TEXT = -1213, also if this is noticed when the fields are redrawn after an import into another field. A value of a text field or a choice field that cannot be drawn remains -1016.

When documents are merged and the target document has a form of its own, it takes over NeedAppearances from an attached file. A field that could not be drawn when the attached file was loaded therefore does not end up in the result without an appearance and without a flag: a later step, such as flattening, draws the field again or reports the error.

Errors

An annotation or form field without an appearance that webPDF cannot draw completely fails the operation instead of being left out silently (see error codes):

• If no font has a character of the text, the operation fails with TOOLBOX_ANNOTATION_INVALID_CHAR_IN_TEXT = -1213. The annotation is not removed silently. When a form field is filled, the error is -1016.
• TOOLBOX_ANNOTATION_CONTENT_CREATION_ERROR = -1205 ends the operation if the appearance cannot be created, in particular if
  • a drawing step fails;
  • rich text exceeds a limit: more than 2^20 (1,048,576) characters, or nested deeper than 100 levels;
  • rich text cannot be read and there is no plain text (/Contents) of the annotation;
  • a text has more than 10,000 sections that need a substitute font;
  • an unbreakable piece of text has more than 10,000 characters between two line break opportunities;
  • the value of a comb field in the document is longer than its /MaxLen (when filling the field: -1016).

This applies to every operation that draws pages or flattens annotations and forms:

• "Toolbox" web service: flattening annotations and forms (forms with flattening), images (raster images and SVG), transcribe and redact (rasterizing pages with sanitize/pages)
• "OCR" web service
• "Barcode" web service

The import of form data in the format fdf reports the same error codes as the import in the formats xml and xfdf.

The reason is the same everywhere: an image, text or barcode value without the missing character would be a silent wrong result. With OCR, the generated appearance is also stored in the result PDF, so an incomplete appearance would stay in the document. In barcode recognition, every annotation of a scanned page counts, also one outside the scan area, because the whole page is drawn before the scan area is cut out.

Rich text that cannot be read (not well-formed) costs only the formatting if the annotation has plain text: the plain text is drawn completely, and only the server log notes it.

Transcribe

In the transcribe operation, the error occurs at every failureLevel, because the conversion does not deliver a result that lacks the annotation. The result depends on errorReport:

errorReport	Result
none	Error -1213 or -1205, the message contains the report
message	Error -1213 or -1205, the message contains the report as XML
file	As for every conversion error, the report file is the result. It holds an error entry with code 14 (an annotation is not drawn completely) and the webPDF code in its text, see XML report

note

For each document, the first 20 problems of this kind are logged as warnings. Later problems of the same document are logged at DEBUG level only, after one warning that announces this limit. The log lines contain no document content.