STImgCtl – Form Fields

Overview and notes

When form field mode is enabled, the user can edit form fields in the document. Filling out form fields only works for PDF documents.

The following elements are supported:

• Text box

• Checkbox.

• Radio button.

• Drop-down list

• Combobox

Changes made in form field mode can be applied using the SaveDocument method.

Form field mode can be activated and deactivated using the corresponding button in the toolbar or the EnablePDFFormularMode function.

If you want to prevent users from changing the form field mode, you can hide the toolbar.

While form mode is active, the use of other methods may be limited or not possible. Equally, some functions in the component’s toolbar are deactivated (e.g. printing). Highlighting regions by means of SetSelection or AllowMouseSelection is not possible. Instead, you can use SetHighlightFields to highlight form fields.

Form fields in PDF documents can be restricted to the input of particular data types. This makes it possible to specify that only data with a particular syntax can be entered in a form field, for example, or that a field can accept numbers but not letters. This syntax check of the form field data is performed by JavaScript.
The following JavaScript commands for syntax checking of the form field data are supported by this component:

• AFDate_FormatEx (formatting as date)

• AFNumber_Format (formatting as a number)

Examples of formatting in PDF:

AFDate_FormatEx("ddmmyyyy");
AFDate_FormatEx("mm");
AFDate_FormatEx("d mmmm, yyyy");
AFNumber_Format(0, 3, 0, 0, "", false);
AFNumber_Format(2, 2, 0, 0, "", false);

EnablePDFFormularMode method

This method can be used to activate and deactivate form mode for actively filling out PDF documents. This mode is disabled by default.

The return value of this method corresponds to the PDFFormularMode property at the time of the call.

int EnablePDFFormularMode(int nOptions);

long EnablePDFFormularMode(long nOptions);

SetHighlightFields method

This method changes the visual appearance of form fields in form field mode. Changes can be made even if a PDF document has not been loaded.

int SetHighlightFields(short nMode);

long SetHighlightFields(short nMode);

SetRenderInternal method

This method can be used to set whether the tab key can be used to navigate between form fields while form field mode is active.

sbyte SetRenderInternal(int nOptions);

char SetRenderInternal(long nOptions);

IsModified method

This method returns whether a PDF document was changed in form field mode.

int IsModified();

long IsModified();

GetEmptyMandatoryField method

This method searches for empty editable required form fields in a PDF document. This allows you to check whether there are any mandatory fields that have not yet been filled in. It can return the number of unfilled mandatory fields or the index of such a field in the internal list of form fields. (If the PDF form field index is required instead, it can be queried afterwards with MapFieldIndex2PDFIndex.)

To jump directly to a field in the display that has not yet been filled in, use the SelectFormfield method.

int GetEmptyMandatoryField(int nOption);

long GetEmptyMandatoryField(long nOption);

Code example for finding all unfilled mandatory fields:

int requiredCount = axSTImgCtl1.GetEmptyMandatoryField(-1);
if (requiredCount > 0)
{
  List<int> requiredIndices = new List<int>();
  for (int i = 0; i < requiredCount; i++)
  {
    requiredIndices.Add(axSTImgCtl1.GetEmptyMandatoryField(i));
  }
}

Code example for testing whether there are any mandatory fields that have not been filled in:

if (axSTImgCtl1.GetEmptyMandatoryField(0) >=0)
{
  MessageBox.Show("Es liegen unausgefüllte Pflichtfelder vor!");
}

GetEmptyOptionalField method

This method searches for empty editable optional form fields in a PDF document. This allows you to check whether there are any optional fields that have not yet been filled in. The number of unfilled optional fields can be returned, or the index of such a field in the internal list of form fields. (If the PDF form field index is required instead, it can be queried afterwards with MapFieldIndex2PDFIndex.)

To jump directly to a field in the display that has not yet been filled in, use the SelectFormfield method.

int GetEmptyOptionaField(int nReserved);

long GetEmptyOptionaField(long nReserved);

For a code example, see the GetEmptyMandatoryField method, which is applied in an equivalent manner.

SelectFormfield method

This method sets the focus of the display to the desired form field element. To do this, the position index of the field in the internal list of form fields must be transferred, which can be obtained from the methods GetEmptyMandatoryField and GetEmptyOptionalField.

int SelectFormfield(int nIndex, int nReserved);

long SelectFormfield(long nIndex, long nReserved);

MapFieldIndex2PDFIndex method

This method is used to acquire the index of a field in the currently opened PDF document as a PDF-compatible field index. This requires the internal field index, which is provided by the methods GetEmptyMandatoryField and GetEmptyOptionalField.

int MapFieldIndex2PDFIndex(int nIndex);

long MapFieldIndex2PDFIndex(long nIndex);

PDFFormularMode property

This property can be used to query the form field mode status.

int PDFFormularMode;

long PDFFormularMode;

PDFTotalFormularFields property

This property can be used to query the number of form fields in the loaded document that can be edited by means of the form field mode.

int PDFTotalFormularFields;

long PDFTotalFormularFields;

FormFieldClicked event

This event signals that a form field button has been clicked with the mouse or that the text in a text field has changed. Form field mode must be active for this. The type of form field, its index position and its subindex are returned in PDF-compatible format. Signature fields are ignored by this event.

The following shows an example implementation in which user-defined names have been replaced by placeholders (%…%).

public class _DSTImgCtlEvents_FormFieldClickedEvent
{
    public int nType;
    public int nIndex;
    public int nSubIndex;

    public _DSTImgCtlEvents_FormFieldClickedEvent(int nType, int nIndex, int nSubIndex)
    {
        this.nType = nType;
        this.nIndex = nIndex;
        this.nSubIndex = nSubIndex;
    }
}

this.%COMPONENT_NAME%.FormFieldClicked += new AxSTIMGCTLLib._DSTImgCtlEvents_FormFieldClickedEventHandler(this.%CALLBACK_FUNCTION%);

private void %CALLBACK_FUNCTION%(object sender, AxSTIMGCTLLib._DSTImgCtlEvents_FormFieldClickedEvent e);

BEGIN_EVENTSINK_MAP(%CLASS_NAME%, CDialogEx)
    ON_EVENT(%CLASS_NAME%, %COMPONENT_ID%, 4, %CALLBACK_FUNCTION%, VTS_I4 VTS_I4 VTS_I4)
END_EVENTSINK_MAP()

void %CALLBACK_FUNCTION%(long nType, long nIndex, long nSubIndex);

Event FormFieldTouched event

This event signals that a form field button has been clicked with the mouse. Neither form field mode nor mouse selection (see AllowMouseSelection) may be active for this. The type of form field, its index position and its subindex are returned in PDF-compatible format. Signature fields are ignored by this event.

The following shows an example implementation in which user-defined names have been replaced by placeholders (%…%).

public class _DSTImgCtlEvents_FormFieldTouchedEvent
{
    public int nType;
    public int nIndex;
    public int nSubIndex;

    public _DSTImgCtlEvents_FormFieldTouchedEvent(int nType, int nIndex, int nSubIndex)
    {
        this.nType = nType;
        this.nIndex = nIndex;
        this.nSubIndex = nSubIndex;
    }
}

this.%COMPONENT_NAME%.FormFieldTouched += new AxSTIMGCTLLib._DSTImgCtlEvents_FormFieldTouchedEventHandler(this.%CALLBACK_FUNCTION%);

private void %CALLBACK_FUNCTION%(object sender, AxSTIMGCTLLib._DSTImgCtlEvents_MarkEndEvent e);

BEGIN_EVENTSINK_MAP(%CLASS_NAME%, CDialogEx)
    ON_EVENT(%CLASS_NAME%, %COMPONENT_ID%, 5, %CALLBACK_FUNCTION%, VTS_I4 VTS_I4 VTS_I4)
END_EVENTSINK_MAP()

void %CALLBACK_FUNCTION%(long nType, long nIndex, long nSubIndex);