Vorgehensweise: Reagieren auf Formularereignisse

Sie können Code schreiben, um auf unterschiedliche Ereignisse zu reagieren, die auftreten können, wenn ein Benutzer ein Formular ausfüllt. Zum Arbeiten mit Ereignissen in InfoPath fügen Sie Ereignishandler hinzu, während Sie mit einer Formularvorlage im Entwurfsmodus arbeiten.

InfoPath-Ereignishandler sollten immer im Entwurfsmodus erstellt werden, da InfoPath automatisch die richtige Deklaration zum Runtersetzen des Ereignisses der InternalStartup-Methode hinzufügt und die Codevorlage des Ereignishandlers in die Codedatei ("FormCode.cs" oder "FormCode.vb") eines Formulars einfügt. Nachdem Sie einen Ereignishandler erstellt haben, sollten Sie die zugehörige Deklaration in der Codedatei des Formulars nicht mehr ändern.

Weitere Informationen zum Erstellen der InfoPath-Ereignishandler finden Sie unter Vorgehensweise: Hinzufügen eines Ereignishandlers.

Übersicht über die Ereignisklassen

Das InfoPath-Modell, das vom Microsoft.Office.InfoPath-Namespace bereitgestellt wird, implementiert drei Klassen, die wiederum die 12 Ereignisse implementieren, die von Formularvorlagen-Geschäftslogik ausgelöst und behandelt werden können. In der folgenden Tabelle sind alle InfoPath-Ereignisobjekte, die Ereignisse, denen sie zugeordnet sind, sowie eine Beschreibung der durch sie bereitgestellten Funktionalität aufgeführt.

Name	Ereignisse	Beschreibung
ButtonEvent	Clicked	Die ButtonEvent-Klasse implementiert das Clicked-Ereignis, das ausgelöst wird, wenn Sie in einem Formular auf ein Steuerelement vom Typ Schaltfläche klicken.
FormEvents	ContextChanged Loading Merge Save Sign Submit VersionUpgrade ViewSwitched	Die FormEvents-Klasse implementiert die Ereignisse, die für die InfoPath-Formularvorlage selbst spezifisch sind: ContextChanged Tritt nach der Änderung des Kontextknotens ein. Loading Tritt ein, nachdem die Formularvorlage geladen, jedoch bevor eine Ansicht initialisiert wurde. Merge Tritt ein, wenn der Befehl Formulare zusammenführen von der Benutzeroberfläche aufgerufen oder InfoPath über die /aggregate-Befehlszeilenoption gestartet wird. Save Tritt ein, wenn die Befehle Speichern oder Speichern unter von der Benutzeroberfläche aus verwendet werden, oder bei Verwendung der Methoden Save und SaveAs der XmlForm-Klasse. Sign Tritt ein, nachdem eine Gruppe signierter Daten mithilfe des Dialogfelds Digitale Signaturen zum Signieren ausgewählt wurde. Submit Tritt ein, wenn der Befehl Absenden von der Benutzeroberfläche aus verwendet wird, oder bei Verwendung der Submit-Methode der XmlForm-Klasse. VersionUpgrade Tritt ein, wenn die Versionsnummer des Formulars, das geöffnet wird, älter ist als die Versionsnummer der Formularvorlage, auf der das Formular basiert. ViewSwitched Tritt ein, nachdem eine Ansicht eines Formulars erfolgreich gewechselt wurde.
XmlEvent	Changed Changing Validating	Implementiert die durch Änderungen an den Daten des einer Formularinstanz zugrunde liegenden XML-Dokuments ausgelösten Ereignisse. Changed Tritt ein, nachdem Änderungen an dem einem Formular zugrunde liegenden XML-Dokument angenommen wurden und nachdem das Validating-Ereignis eingetreten ist. Changing Tritt ein, nachdem Änderungen an einem Formular zugrunde liegenden XML-Dokument vorgenommen wurden, jedoch bevor diese angenommen wurden. Validating Tritt ein, nachdem Änderungen an dem einem Formular zugrunde liegenden XML-Dokument angenommen wurden, jedoch bevor das Changed-Ereignis eingetreten ist. Die XmlEvent-Klasse implementiert auch die RaiseUndoRedoForChanged-Eigenschaft, die abruft oder festlegt, ob das Changed-Ereignis ausgelöst wird, wenn ein Vorgang zum Rückgängigmachen oder Wiederholen eintritt.

Hinweis

Die Ereignisse Changed und Changing werden nur einmal ausgelöst, wenn eine Änderung in einem nicht leeren Feld des Formulars vorgenommen wird, während die vergleichbaren Ereignisse in InfoPath 2003 und in dem vom Microsoft.Office.Interop.InfoPath.SemiTrust-Namespace bereitgestellten InfoPath 2003-kompatiblen Objektmodell (OnBeforeChange und OnAfterChange) bei Änderungen an einem nicht leeren Feld zweimal ausgelöst werden: wenn der alte Wert gelöscht wird und wenn der neue Wert eingefügt wird.

Übersicht über die EventArgs-Klassen

Jedem der 12 Ereignisse ist ein EventArgs-Objekt zugeordnet, das an den Ereignishandler für das Ereignis übergeben wird, um Statusinformationen und andere Funktionalität bereitzustellen, die im Ereignishandlercode verwendet werden können. Die folgende Tabelle listet die InfoPath-Ereignisse mit den ihnen zugeordneten EventArgs-Objekten und einer kurzen Beschreibung der durch die Eigenschaften und Methoden des Objekts bereitgestellten Funktionalität auf. Details zu den speziellen Eigenschaften und Methoden des Objekts erhalten Sie, indem Sie auf den Namen des EventArgs-Objekts in der Tabelle und dann auf den Hyperlink zu den Membern im Thema klicken.

Ereignis	EventsArgs-Klasse	Beschreibung
Clicked	ClickedEventArgs	Ruft die Steuerelement-ID ab. Ruft ein XPathNavigator-Objekt ab, mit Positionierung im innersten XML-Knoten des dem Formular zugrunde liegenden XML-Dokuments, in dem das Steuerelement Schaltfläche enthalten ist.
ContextChanged	ContextChangedEventArgs	Ruft den Typ der Kontextänderung ab, die beim Eintreten des Ereignisses ausgeführt wurde. Ruft einen Wert ab, der angibt, ob das Kontextänderungsereignis als Reaktion auf einen Vorgang zum Rückgängigmachen oder Wiederholen ausgeführt wurde. Ruft einen Verweis auf XPathNavigator am Kontextknoten ab, der das Ereignis ausgelöst hat.
Loading	LoadingEventArgs	Gibt die Ansicht an, in der das Formular nach dem Laden geöffnet werden soll. Ruft einen Verweis auf das XmlFormCancelEventArgs-Objekt ab. Ruft ein IDictionary-Objekt ab, das Eingabeparameter enthält, die mithilfe der /InputParameters-Befehlszeilenoption oder mithilfe von Abfrageparametern in einem URL angegeben wurden, um das Formular zu öffnen.
Merge	MergeEventArgs	Ruft einen Verweis auf das XmlFormCancelEventArgs-Objekt ab. Ruft die Anzahl der Formulare ab, die bei einem Zusammenführungsvorgang zusammengeführt werden. Ruft den nullbasierten Index des Formulars ab, das zurzeit zusammengeführt wird. Ruft einen mit der Cancel-Eigenschaft verwendeten Wert ab oder legt diesen fest, um zu bestimmen, ob nur das aktuelle Formular oder der gesamte Zusammenführungsvorgang abgebrochen werden soll. Ruft ein XPathNavigator-Objekt auf, welches am Stammknoten des zugrunde liegenden XML-Dokuments des zurzeit zusammengeführten Formulars positioniert ist.
Save	SaveEventArgs	Führt den vom Benutzer angeforderten Speichervorgang aus. Ruft einen Verweis auf das SaveCancelEventArgs-Objekt ab, das zum Abbrechen des Ereignisses verwendet werden kann. Ruft den Dateinamen ab, der im Ereignishandler für das Ereignis verwendet werden soll. Ruft ab, ob der Speichervorgang als Speichern- oder als Speichern-unter-Vorgang ausgeführt wird.
Sign	SignEventArgs	Ruft ab oder legt fest, ob das Dialogfeld Digitale Signaturen angezeigt wird. Ruft die Gruppe signierbarer Daten ab, die das Ereignis ausgelöst hat.
Submit	SubmitEventArgs	Ruft einen Verweis auf das XmlFormCancelEventArgs-Objekt zum Abbrechen des Ereignisses ab.
VersionUpgrade	VersionUpgradeEventArgs	Ruft einen Verweis auf das XmlFormCancelEventArgs-Objekt zum Abbrechen des Ereignisses ab. Ruft die Versionsnummer des Formulardokuments ab, für das ein Update ausgeführt wird. Ruft die Versionsnummer der Formularvorlage ab, die dem Formular zugeordnet ist, für das ein Update ausgeführt wird.
ViewSwitched	ViewSwitchedEventArgs	Die ViewSwitchedEventArgs-Klasse stellt keine anderen als die von System.Object geerbten Eigenschaften und Methoden für das Ereignis bereit.
Changed	XmlEventArgs	Ruft ein XPathExpression-Objekt ab, das einen XPath-Ausdruck enthält, der den Knoten zurückgibt, der zurzeit geändert wird. Ruft den neuen Wert für den Knoten ab, der geändert wird. Ruft ein XPathNavigator-Objekt ab, das auf den Knoten zeigt, der dem gelöschten Knoten übergeordnet ist. Ruft den ursprünglichen Wert des Knotens ab, der geändert wird. Ruft eine XmlOperation-Enumeration ab, die den Typ des Vorgangs angibt, der beim Ändern des Knotens aufgetreten ist. Ruft ein XPathNavigator-Objekt ab, das auf den Knoten zeigt, der geändert wird. Ruft einen Wert ab, der angibt, ob der zu ändernde Knoten Teil eines Vorgangs zum Rückgängigmachen oder Wiederholen ist.
Changing	XmlChangingEventArgs	Ruft ein XmlFormCancelEventArgs-Objekt ab, das dem Ereignis zugeordnet ist. Erbt die gesamte oben aufgeführte Funktionalität für das XmlEventArgs-Objekt.
Validating	XmlValidatingEventArgs	Erstellt ein FormError-Objekt, das benutzerdefinierte Fehlerinformationen mit den angegebenen Werten enthält, und fügt es dem FormErrorCollection-Objekt des Formulars hinzu. Erbt die gesamte oben aufgeführte Funktionalität für das XmlEventArgs-Objekt.

Verwenden der EventArgs-Objekte

Beim Erstellen eines Ereignishandlers wird von InfoPath dessen Deklaration im Formularcode des Projekts erstellt. In der Deklaration des Ereignishandlers wird von InfoPath e als Name des Parameters verwendet, der an den Ereignishandler übergeben wird. Dieser Parameter enthält das EventArgs-Objekt, das dem Ereignishandler zugeordnet ist, um Statusinformationen und andere Funktionalität bereitzustellen, wenn das Ereignis eintritt.

Wenn Sie beispielsweise einen Ereignishandler für das Loading-Ereignis im Entwurfsmodus erstellen (zeigen Sie im Menü Extras auf Programmierung, und klicken Sie dann auf Loading-Ereignis), wird von InfoPath die Deklaration für den Ereignishandler, der das LoadingEventArgs-Objekt erhält, der Formularcodedatei hinzugefügt. Dann wird der Code-Editor geöffnet, damit Sie den Code der folgenden Ereignishändlerdeklaration hinzufügen können.

public void FormEvents_Loading(object sender, LoadingEventArgs e)
{
   // Write your code here.
}

Public Sub FormEvents_Loading(ByVal sender As Object, _
   ByVal e As LoadingEventArgs)
   ' Write your code here.
End Sub

Beim Schreiben von Code für einen Ereignishandler können Sie die Eigenschaften und Methoden verwenden, die vom EventArgs-Objekt implementiert werden, das durch den e-Parameter übergeben wird. Im folgenden Changing-Ereignishandler wird beispielsweise die NewValue-Eigenschaft des XmlChangingEventArgs-Objekts (das von der XmlEventArgs-Klasse geerbt wird) verwendet, um den Wert des Felds zu prüfen, das gerade geändert wurde. Wenn der Benutzer das Feld geändert und leer gelassen hat, wird auf die Message-Eigenschaft der XmlFormCancelEventArgs-Klasse mithilfe der CancelableArgs-Eigenschaft des XmlChangingEventArgs-Objekts zugegriffen, um dem Benutzer einen Fehler anzuzeigen, und die XmlFormCancelEventArgs.Cancel-Eigenschaft wird auf true festgelegt, um das Ereignis abzubrechen und ein Rollback für die Änderungen auszuführen, die der Benutzer vorgenommen hat.

public void field1_Changing(object sender, LoadingEventArgs e)
{
   // Determine whether there is a new value.
   if (e.NewValue == "")
   {
      // The value is blank, so display an error message
      // and roll back the changes.
      e.CancelableArgs.Message = 
         "You must supply a value for this field.";
      e.CancelableArgs.Cancel = true;
      return;
   }
}

Public Sub field1_Changing(ByVal sender As Object, _
   ByVal e As LoadingEventArgs)

   ' 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.CancelableArgs.Message = _
         "You must supply a value for this field."
      e.CancelableArgs.Cancel = True
      Return
   End If
End Sub