Vorgehensweise: Reagieren auf Formularereignisse mit dem InfoPath 2003-Objektmodell
Sie können Code schreiben, um auf unterschiedliche Ereignisse zu reagieren, die auftreten können, wenn ein Benutzer ein Formular ausfüllt. Für die Bearbeitung von Ereignissen in InfoPath erstellen Sie Ereignishandler in einem Formular im Entwurfsmodus.
InfoPath-Ereignishandler sollten im Entwurfsmodus erstellt werden, da InfoPath beim Verwenden des InfoPath 2003-kompatiblen Objektmodells automatisch die richtige Deklaration hinzufügt und ein Attribut (InfoPathEventHandlerAttribute) in einer Codedatei des Formulars ("FormCode.cs" oder "FormCode.vb") zum Identifizieren und Runtersetzen des Ereignishandlers anwendet. Nachdem Sie einen Ereignishandler erstellt haben, sollten Sie die zugehörige Deklaration und das Attribut in der Codedatei des Formulars nicht mehr ändern.
Weitere Informationen zum Erstellen der InfoPath-Ereignishandler finden Sie unter Vorgehensweise: Hinzufügen eines Ereignishandlers mit dem InfoPath 2003-Objektmodell.
Übersicht über die Ereignisobjekte
Das InfoPath 2003-kompatible Objektmodell implementiert neun Ereignisobjekte, die im Microsoft.Office.Interop.InfoPath.SemiTrust-Namespace offen gelegt sind. In der folgenden Tabelle sind alle InfoPath-Ereignisobjekte, die zugeordneten Ereignishandler sowie eine Beschreibung der durch sie bereitgestellten Funktionen aufgelistet.
| Name | Ereignishandler | Beschreibung |
|---|---|---|
Gibt einen Verweis auf das einem Formular zugrunde liegende XML-Dokument, den Rückgabestatus sowie andere Eigenschaften, die Informationen zum XML-Knoten enthalten, zurück, während ein XML-DOM (Document Object Model) geändert wird. Schließt auch eine Methode zum Auslösen eines Fehlers ein. |
||
Gibt einen Verweis auf das einem Formular zugrunde liegende XML-Dokument, den Rückgabestatus und den XML-Quellknoten zurück, während im Formularbereich auf eine Schaltfläche geklickt wird. |
||
Gibt Informationen zum XML-DOM-Knoten (Document Object Model) zurück, bei dem es sich um den aktuellen Kontext des dem Formular zugrunde liegenden XML-Dokuments handelt. |
||
Gibt einen Verweis auf das einem Formular zugrunde liegende XML-Dokument zurück, während die Ansicht gewechselt oder Formulare zusammengeführt werden. |
||
Gibt einen Verweis auf das einem Formular zugrunde liegende XML-Dokument und den Rückgabestatus zurück, während ein Formular geladen oder gesendet wird. |
||
Gibt Eigenschaften und Methoden zurück, die während eines OnMergeRequest-Ereignisses für die programmseitige Interaktion mit dem zugrunde liegenden XML-Dokument eines Formulars sowie für die Ermittlung von Zusammenführungseigenschaften, wie z. B. die Anzahl der zusammenzuführenden Dateien, verwendet werden können. |
||
Gibt eine Reihe von Eigenschaften und Methoden zurück, die während eines Speichervorgangs vom OnSaveRequest-Ereignishandler für die programmseitige Interaktion mit dem zugrunde liegenden XML-Dokument eines Formulars, die Festlegung der Speichereigenschaften und die Ausführung des Speichervorgangs verwendet werden können. |
||
Wird verwendet, um zusätzliche Daten zur digitalen Signatur hinzuzufügen. |
||
Gibt einen Verweis auf das einem Formular zugrunde liegende XML-Dokument, den Rückgabestatus sowie die Dokument- und Lösungsversionsnummern zurück, während eine Versionsaktualisierung durchgeführt wird. |
Verwenden der Ereignisobjekte
Beim Erstellen eines Ereignishandlers wird von InfoPath dessen Deklaration in der Formularcodedatei des Projekts ("FormCode.cs" oder "FormCode.vb") erstellt. In der Deklaration des Ereignishandlers wird von InfoPath e als Name der Parameter verwendet, der an den Ereignishandler übergeben wird. Dieser Parameter enthält das Ereignisobjekt, das dem Ereignishandler zugeordnet ist.
Wenn Sie beispielsweise einen Ereignishandler für das OnLoad-Ereignis im Entwurfsmodus erstellen (zeigen Sie im Menü Extras auf Programmierung, und klicken Sie dann auf OnLoad-Ereignis), wird von InfoPath die Deklaration für den Ereignishandler, der das DocReturnEvent-Objekt erhält, der Formularcodedatei hinzugefügt. Dann wird der Code-Editor geöffnet, damit Sie den Code der folgenden Ereignishandlerdeklaration hinzufügen können.
// The following function handler is created by Microsoft Office
// InfoPath. Do not modify the type or number of arguments.
[InfoPathEventHandler(EventType=InfoPathEventType.OnLoad)]
public void FormEvents_OnLoad(DocReturnEvent e)
{
// Write your code here.
}
' The following function handler is created by Microsoft Office
' InfoPath. Do not modify the type or number of arguments.
<InfoPathEventHandler(EventType:=InfoPathEventType.OnLoad)> _
Public Sub FormEvents_OnLoad(ByVal e As DocReturnEvent)
' Write your code here.
End Sub
Beim Schreiben von Code für einen Ereignishandler können Sie die Eigenschaften und Methoden verwenden, die vom Ereignisobjekt implementiert werden, das durch den e-Parameter übergeben wird. So wird beispielsweise im folgenden OnBeforeChange-Ereignishandler die NewValue-Eigenschaft des DataDOMEvent-Ereignisobjekts verwendet, um den Wert des soeben geänderten Felds zu überprüfen. Wenn das Feld leer ist, wird die ReturnMessage-Eigenschaft des DataDOMEvent-Ereignisobjekts verwendet, um dem Benutzer einen Fehler in einem Dialogfeld anzuzeigen. Anschließend wird die ReturnStatus-Eigenschaft auf false festgelegt, wodurch darauf hingewiesen wird, dass die vom Benutzer vorgenommenen Änderungen nicht übernommen werden sollen.
[InfoPathEventHandler(MatchPath="/my:myFields/my:field1",
EventType=InfoPathEventType.OnBeforeChange)]
public void field1_OnBeforeChange(DataDOMEvent e)
{
// Determine whether there is a new value.
if ((string)e.NewValue == "")
{
// The value is blank, so display an error message and roll
// back the changes.
e.ReturnMessage = "You must supply a value for this field.";
e.ReturnStatus = false;
return;
}
}
<InfoPathEventHandler(MatchPath:="/my:myFields/my:field1", _ EventType:=InfoPathEventType.OnBeforeChange)> _
Public Sub field1_OnBeforeChange(ByVal e As DataDOMEvent)
' Determine whether there is a new value.
If (e.NewValue = "") Then
' The value is blank, so display an error message and roll back
' the changes.
e.ReturnMessage = "You must supply a value for this field."
e.ReturnStatus = False
Return
End If
End Sub
Hinweis
Von jedem der InfoPath-Ereignisobjekte im InfoPath 2003-kompatiblen Objektmodell werden unterschiedliche Eigenschaften und Methoden implementiert. Klicken Sie in der zuvor angezeigten Tabelle zu den Ereignisobjekten auf das entsprechende Objekt, um weitere Informationen zu einem bestimmten Ereignisobjekt zu erhalten.