STImgCtl – Formularfelder

Überblick und Hinweise

Ist der Formularfeldmodus aktiviert, kann der Benutzer Formularfelder im Dokument bearbeiten. Das Ausfüllen von Formularfeldern funktioniert nur für PDF-Dokumente.

Unterstützte Elemente sind:

• Textbox

• Checkbox

• Radiobutton

• Listbox

• Combobox

Die im Formularfeldmodus vorgenommenen Änderungen können mit der Methode SaveDocument übernommen werden.

Der Formularfeldmodus kann über den entsprechenden Button in der Werkzeugleiste oder die Funktion EnablePDFFormularMode aktiviert und deaktiviert werden.

Soll eine Änderung des Formularfeldmodus durch den Benutzer verhindert werden, kann die Werkzeugleiste ausgeblendet werden.

Während der Formularmodus aktiv ist, können andere Methoden gegebenenfalls gar nicht oder nur eingeschränkt verwendet werden. Ebenso sind einige Funktionen in der Werkzeugleiste der Komponente deaktiviert (z.B. das Drucken). Bereichshervorhebungen durch SetSelection oder über AllowMouseSelection sind nicht möglich, dafür können Sie SetHighlightFields zur Hervorhebung von Formularfeldern nutzen.

Formularfelder in PDF-Dokumenten können auf die Eingabe bestimmter Datentypen begrenzt werden. So kann z.B. festgelegt werden, dass in einem Formularfeld nur ein Datum mit einer bestimmten Syntax eingetragen werden darf, oder dass in einem Feld nur Zahlenwerte aber keine Buchstaben zulässig sind. Diese Syntaxprüfung der Formularfelddaten erfolgt durch JavaScript.
Folgende JavaScript-Kommandos zur Syntaxprüfung der Formularfelddaten werden von dieser Komponente unterstützt:

• AFDate_FormatEx (Formatierung als Datum)

• AFNumber_Format (Formatierung als Zahl)

Beispiele für Formatierungen im 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);

Methode EnablePDFFormularMode

Mit dieser Methode kann der Formularmodus zum aktiven Ausfüllen von PDF-Dokumenten aktiviert und deaktiviert werden. Standardmäßig ist dieser Modus ausgeschaltet.

Der Rückgabewert dieser Methode entspricht der Eigenschaft PDFFormularMode zum Zeitpunkt des Aufrufs.

int EnablePDFFormularMode(int nOptions);

long EnablePDFFormularMode(long nOptions);

Methode SetHighlightFields

Diese Methode ändert die optische Darstellung von Formularfeldern im Formularfeldmodus. Zur Änderung muss kein PDF-Dokument geladen worden sein.

int SetHighlightFields(short nMode);

long SetHighlightFields(short nMode);

Methode SetRenderInternal

Mit dieser Methode kann eingestellt werden, ob per Tab-Taste zwischen den Formularfeldern navigiert werden kann, solange der Formularfeldmodus aktiv ist.

sbyte SetRenderInternal(int nOptions);

char SetRenderInternal(long nOptions);

Methode IsModified

Diese Methode gibt zurück, ob ein PDF-Dokument im Formularfeldmodus geändert wurde.

int IsModified();

long IsModified();

Methode GetEmptyMandatoryField

Diese Methode sucht nach leeren veränderbaren Pflicht-Formularfeldern in einem PDF-Dokument. So kann geprüft werden, ob noch unausgefüllte Pflichtfelder vorhanden sind. Es kann die Anzahl an unausgefüllten Pflichtfeldern zurückgegeben werden, oder der Index eines solchen Felds in der internen Auflistung der Formularfelder. (Wird stattdessen der PDF-Formularfeldindex benötigt, kann er danach mit MapFieldIndex2PDFIndex abgefragt werden.)

Um ein noch nicht ausgefülltes Feld in der Anzeige direkt anzuspringen, steht die Methode SelectFormfield zur Verfügung.

int GetEmptyMandatoryField(int nOption);

long GetEmptyMandatoryField(long nOption);

Codebeispiel für das Finden aller unausgefüllten Pflichtfelder:

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));
  }
}

Codebeispiel zum Testen, ob noch unausgefüllte Pflichtfelder vorliegen:

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

Methode GetEmptyOptionalField

Diese Methode sucht nach leeren veränderbaren optionalen Formularfeldern in einem PDF-Dokument. So kann geprüft werden, ob noch unausgefüllte optionale Felder vorhanden sind. Es kann die Anzahl an unausgefüllten optionalen Feldern zurückgegeben werden, oder der Index eines solchen Felds in der internen Auflistung der Formularfelder. (Wird stattdessen der PDF-Formularfeldindex benötigt, kann er danach mit MapFieldIndex2PDFIndex abgefragt werden.)

Um ein noch nicht ausgefülltes Feld in der Anzeige direkt anzuspringen, steht die Methode SelectFormfield zur Verfügung.

int GetEmptyOptionaField(int nReserved);

long GetEmptyOptionaField(long nReserved);

Für ein Codebeispiel siehe die Methode GetEmptyMandatoryField, die äquivalent angewendet wird.

Methode SelectFormfield

Diese Methode setzt den Fokus der Anzeige auf das gewünschte Formularfeldelement. Dafür muss der Stellenindex des Feldes in der internen Auflistung der Formularfelder übergeben werden, den man von den Methoden GetEmptyMandatoryField und GetEmptyOptionalField erhält.

int SelectFormfield(int nIndex, int nReserved);

long SelectFormfield(long nIndex, long nReserved);

Methode MapFieldIndex2PDFIndex

Diese Methode dient dazu, den Index eines Feldes des aktuell geöffneten PDF-Dokumentes als PDF-konformen Feldindex zu erhalten. Hierfür wird der interne Feldindex benötigt, welchen die Methoden GetEmptyMandatoryField und GetEmptyOptionalField liefern.

int MapFieldIndex2PDFIndex(int nIndex);

long MapFieldIndex2PDFIndex(long nIndex);

Eigenschaft PDFFormularMode

Über diese Eigenschaft kann der Status des Formularfeldmodus abgefragt werden.

int PDFFormularMode;

long PDFFormularMode;

Eigenschaft PDFTotalFormularFields

Über diese Eigenschaft kann die Anzahl der Formularfelder in dem geladenen Dokument abgefragt werden, die über den Formularfeldmodus bearbeitet werden können.

int PDFTotalFormularFields;

long PDFTotalFormularFields;

Event FormFieldClicked

Dieses Event signalisiert das Anklicken eines Formularfeldbutton mit der Maus bzw. die Änderung des Textes in einem Textfeld. Hierfür muss der Formularfeldmodus aktiv sein. Es werden der Typ des Formularfelds, seine Indexposition und sein Subindex im PDF-konformen Format zurückgegeben. Signaturfelder werden von diesem Event ignoriert.

Im folgenden wird eine Beispiel-Implementierung gezeigt, in der benutzerdefinierte Namen durch Platzhalter (%…%) ersetzt wurden.

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

Dieses Event signalisiert das Anklicken eines Formularfeldes mit der Maus. Hierfür darf weder der Formularfeldmodus noch die Markierung mit der Maus (siehe AllowMouseSelection) aktiv sein. Es werden der Typ des Formularfelds, seine Indexposition und sein Subindex im PDF-konformen Format zurückgegeben. Signaturfelder werden von diesem Event ignoriert.

Im folgenden wird eine Beispiel-Implementierung gezeigt, in der benutzerdefinierte Namen durch Platzhalter (%…%) ersetzt wurden.

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);