Appearance streams for PDF form fields

A form field must have an appearance stream associated with it in the PDF in order for the form field to be visible when the PDF is viewed or printed. Appearance streams control the appearance of widget annotations and allow them to be presented in visually different ways to reflect user interactions. When creating form fields in Foxit Quick PDF Library you need to decide whether you want to generate the appearance streams for the form fields in advance or whether you want to instruct the PDF viewer to generate the appearance streams when the PDF with the form fields is loaded.

Special note with regards to printing using Foxit Quick PDF Library: If a PDF form doesn’t have appearance streams but the fields have values in them then the PrintDocument function will not print the field values. The UpdateAppearanceStreams function will need to be called before printing. See option 2 below for more details.

Option 1: Don’t generate appearance streams

(In short: this covers not generating appearances streams using Foxit Quick PDF Library but instead relies on the conforming PDF reader to generate the appearance streams. The downside to this option is that the conforming PDF reader will modify the PDF as soon as it is opened and as a result the Save button will most likely be enabled.)

If you want to leave the generation of appearance streams for form fields to the conforming PDF reader then you need to call the SetNeedAppearances function and pass “1” as the value in the parameter field. This sets the NeedAppearances entry in the interactive form dictionary to true and as a result conforming PDF readers will try to generate appearance streams. The SetNeedAppearances function only needs to be called once for every PDF being generated. Call the SetNeedAppearances function at the start of your form field related code. The NeedAppearances entry in the interactive form dictionary will default to true if not set, but it is better to be explicit as not all PDF readers work in the same way as applications such as Adobe Reader.

Option 2: Generate appearance streams

(In short: this covers generating appearances streams using Foxit Quick PDF Library instead of relying on the conforming PDF reader to generate the appearance streams. If all of the appearance streams are generated for the form fields then the Save button should not be enabled when you open it in your conforming PDF reader.)

If you want to generate the appearance streams for the form fields before saving the PDF then before saving your PDF you will need to call the UpdateAppearanceStream function for each form field in your PDF. It is also advisable that you call the  SetNeedAppearances function and pass “0” as the value in the parameter field so that the confirming PDF reader knows that it should not attempt to generate appearance streams. As a side note, often users will report that a product such as Adobe Reader will have it’s Save button enabled after a PDF form is loaded, indicating that a change has occurred to the PDF. This is generally because Adobe Reader has generated an appearance stream for one or more of the form fields in the PDF.  Setting the NeedAppearances entry in the interactive form dictionary to false will stop this from happening.  The  SetNeedAppearances function only needs to be called once for every PDF being generated. Call the SetNeedAppearances function at the start of your form field related code. Here is some sample code which demonstrates how to call the  UpdateAppearanceStream function for each form field in the PDF.

for (int i = 1; i >= DPL.FormFieldCount(); i++)
     DPL.UpdateAppearanceStream(i);

Currently the generation of appearance streams is only supported for text, checkbox, radiobutton, choice and button form fields. If you are using other form field types you will need to rely on the conforming PDF reader to generate the appearance stream.

This article refers to a deprecated product. If you are looking for support for Foxit PDF SDK, please click here.