How to: Respond to Form Events

You can write code to respond to various events that can occur as a user fills out a form. To work with events in InfoPath, you add event handlers while working with a form template in design mode.

InfoPath event handlers should always be created in design mode because InfoPath automatically adds the correct declaration for sinking the event to the InternalStartup method and inserts the event handler's code skeleton into a form's code file (FormCode.cs or FormCode.vb). After you have created an event handler, you should not alter its declaration in the form's code file.

For information about creating the InfoPath event handlers, see How to: Add an Event Handler.

Overview of the Event Classes

The InfoPath model provided by the Microsoft.Office.InfoPath namespace implements three classes that implement the 12 events that can be raised and handled by form template business logic. The following table lists each of the InfoPath event objects, the events they are associated with, and a description of the functionality they provide.

Overview of the EventArgs Classes

Each of the 12 events have an EventArgs object associated with the event that are passed to the event handler for the event to provide state information and other functionality that can be used in the event handler code. The following table lists the InfoPath events with their associated EventArgs objects and a brief description of the functionality provided by the properties and methods of the object. For details on the specific properties and methods of the object, click the name of the EventArgs object in the table, and then click on the Members link in the topic.

Using the EventArgs Objects

When you create an event handler, InfoPath creates the event handler's declaration in the project's form code. In the declaration of the event handler, InfoPath uses e as the name of the parameter that is passed to the event handler. This parameter contains the EventArgs object that is associated with the event handler for providing state information and other functionality when the event occurs.

For example, when you create an event handler for the Loading event in design mode (by clicking the Tools menu, point to Programming, and then clicking Loading Event), InfoPath adds the declaration for the event handler that receives the LoadingEventArgs object to the form code file, and then opens the code editor so that you can add your code to the following event handler declaration.

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

When writing code for an event handler, you can use the properties and methods implemented by the EventArgs object that is passed through the e parameter. For example, in the following Changing event handler, the NewValue property of the XmlChangingEventArgs object (which is inherited from the XmlEventArgs class) is used to check the value of the field that was just changed. If the user changed the field and left it blank, the Message property of the XmlFormCancelEventArgs class is accessed using the CancelableArgs property of the XmlChangingEventArgs object to display an error to the user, and the XmlFormCancelEventArgs.Cancel property is set to true, to cancel the event and roll back the changes the user made.

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