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.

Name	Events	Description
ButtonEvent	Clicked	The ButtonEvent class implements the Clicked event that is raised when a Button control is clicked on a form.
FormEvents	ContextChanged Loading Merge Save Sign Submit VersionUpgrade ViewSwitched	The FormEvents class implements the events that are specific to an InfoPath form template itself: ContextChanged Occurs after the context node changes. Loading Occurs when the form template has been loaded, but before any views have been initialized. Merge Occurs when the Merge Forms command is invoked from the user interface, or InfoPath is started with the /aggregate command-line switch. Save Occurs when the Save or Save As commands are used from the user interface, or when the Save and SaveAs methods of the XmlForm class are used. Sign Occurs after a set of signed data has been selected to sign through the Digital Signatures dialog box. Submit Occurs when the Submit command is used from the user interface, or the Submit method of the XmlForm class is used. VersionUpgrade Occurs when the version number of the form being opened is older than the version number of the form template on which it is based. ViewSwitched Occurs after a view of a form has been successfully switched.
XmlEvent	Changed Changing Validating	Implements the events raised by changes to the data in the underlying XML document of a form instance: Changed Occurs after changes to a form's underlying XML document have been accepted and after the Validating event has occurred. Changing Occurs after changes to a form's underlying XML document have been made but before the changes have been accepted. Validating Occurs after changes to a form's underlying XML document have been accepted but before the Changed event has occurred. The XmlEvent class also implements the RaiseUndoRedoForChanged property, which gets or sets whether the Changed event will be raised when an undo or redo operation occurs.

Note

The Changed and Changing events fire only once when a change is made in a non-blank field in the form, whereas the comparable events in InfoPath 2003 and the InfoPath 2003-compatible object model provided by the Microsoft.Office.Interop.InfoPath.SemiTrust namespace (OnBeforeChange and OnAfterChange) fire twice on changes to a non-blank field: once when the old value is deleted, and again when the new value is inserted.

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.

Event	EventsArgs Class	Description
Clicked	ClickedEventArgs	Gets the control ID. Get an XPathNavigator object positioned at the innermost XML node of the form's underlying XML document that contains the Button control.
ContextChanged	ContextChangedEventArgs	Gets the type of context change that was performed when the event occurred. Gets a value indicating whether the context change event occurred in response to undoing or redoing an operation. Gets a reference to an XPathNavigator positioned at the context node that raised the event.
Loading	LoadingEventArgs	Specifies the view in which to open the form after loading. Gets a reference to the XmlFormCancelEventArgs object. Gets an IDictionary containing any input parameters specified using the /InputParameters command-line option, or specified using query parameters in a URL to open the form.
Merge	MergeEventArgs	Gets a reference to the XmlFormCancelEventArgs object. Gets the count of the number of forms being merged in a merging operation. Gets the zero-based index of the form that is currently being merged. Gets or sets a value that is used with the Cancel property to determine whether to cancel only the current form or the entire merging operation. Gets an XPathNavigator object positioned at the root node of the underlying XML document of the form that is currently being merged.
Save	SaveEventArgs	Performs the save operation requested by the user. Gets a reference to the SaveCancelEventArgs object that can be used to cancel the event. Gets the file name to be used in the event handler for the event. Gets whether the save operation will be performed as a "save" operation or as a "save as" operation.
Sign	SignEventArgs	Gets or sets whether to display the Digital Signatures dialog box. Gets the set of signable data that raised the event.
Submit	SubmitEventArgs	Gets a reference to the XmlFormCancelEventArgs object for cancelling the event.
VersionUpgrade	VersionUpgradeEventArgs	Gets a reference to the XmlFormCancelEventArgs object for cancelling the event. Gets the version number of the form document being upgraded. Gets the version number of the form template associated with the form being upgraded.
ViewSwitched	ViewSwitchedEventArgs	The ViewSwitchedEventArgs class does not provide any properties and methods for the event other than those inherited from System.Object.
Changed	XmlEventArgs	Gets an XPathExpression object which contains an XPath expression that returns the node that is currently being changed. Gets the new value for the node being changed. Gets an XPathNavigator object pointing to the node which is the parent of the node being deleted. Gets the original value of the node that is being changed. Gets an XmlOperation enumeration that indicates the type of operation that occurred when the node was changed. Gets an XPathNavigator object pointing at the node that is being changed. Gets a value that indicates whether the node being changed is part of an undo or redo operation.
Changing	XmlChangingEventArgs	Gets an XmlFormCancelEventArgs object associated with the event. Inherits all of the functionality listed above for the XmlEventArgs object.
Validating	XmlValidatingEventArgs	Creates a FormError object that contains custom error information with the specified values and adds it to the FormErrorCollection object of the form. Inherits all of the functionality listed above for the XmlEventArgs object.

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