InfoPath Team Blog

Using the Events Manager of the InfoPath Hosted Control

The InfoPath hosted control gives developers of third party hosted applications the ability to respond to events in the form.  The InfoPath event manager provides this functionality.  Through the event manager a host application can respond to 5 form events, 3 xml events and 1 control event:

How can third party host applications use the event manager?

Step 1: Implement an InternalStartup method

First, add code to handle the InternalStartup event. InternalStartup method will execute when a form loads.

public Form1()
{
            InitializeComponent();

            //sync to the startup event where you can register for individual events
            formControl1.InternalStartup += new Microsoft.Office.InfoPath.FormControl.EventHandler<EventArgs>(InternalStartup);
}

Next, implement your InternalStartup method. The function signature should look similar to:

void formControl1_InternalStartup(object sender, EventArgs e)

Step 2: Register to receive events

In your InternalStartup method add code to register for events. For form events this code looks like this.

void InternalStartup(object sender, EventArgs e)
{           
       ((FormControl)sender).EventManager.FormEvents.ViewSwitched += new ViewSwitchedEventHandler(OnSwitchView);
       ((FormControl)sender).EventManager.FormEvents.Submit       += new SubmitEventHandler(OnSubmit);
       ((FormControl)sender).EventManager.FormEvents.Sign         += new SignEventHandler(OnSign);
       ((FormControl)sender).EventManager.FormEvents.Save         += new SaveEventHandler(OnSave);
       ((FormControl)sender).EventManager.FormEvents.Merge        += new MergeEventHandler(OnMerge);
 }

For xml events you must provide the XPath of the node whose events you wish to respond to. Below is a sample of how to register to receive xml events.

void InternalStartup(object sender, EventArgs e)
{
      ((FormControl)sender).EventManager.XmlEvents["/my:myFields/my:field1"].Changed    += new XmlChangedEventHandler(FieldChanged);
      ((FormControl)sender).EventManager.XmlEvents["/my:myFields/my:field1"].Changing   += new XmlChangingEventHandler(FieldChanging);
      ((FormControl)sender).EventManager.XmlEvents["/my:myFields/my:field1"].Validating += new XmlValidatingEventHandler(FieldValidating);
}

To receive the click event for a button you must specify the control id of the button. Below is a sample of how to register to receive control events.

void InternalStartup(object sender, EventArgs e)
{
      ((ButtonEvent)((FormControl)sender).EventManager.ControlEvents["CTRL2_5"]).Clicked += new ClickedEventHandler(ButtonClicked);
}

Step 3: Implement methods to handle each event registered

The final step is to implement handlers for the events you have registered for.
The handlers for the events have the following method signatures.

Form Events

public delegate void ViewSwitchedEventHandler(object sender, Microsoft.Office.InfoPath.ViewSwitchedEventArgs e)
public delegate void SubmitEventHandler(object sender, Microsoft.Office.InfoPath.SubmitEventArgs e)
public delegate void SignEventHandler(object sender, Microsoft.Office.InfoPath.SignEventArgs e)
public delegate void SaveEventHandler(object sender, Microsoft.Office.InfoPath.SaveEventArgs e)
public delegate void MergeEventHandler(object sender, Microsoft.Office.InfoPath.MergeEventArgs e)

Xml Events

public delegate void XmlChangedEventHandler(object sender, Microsoft.Office.InfoPath.XmlEventArgs e)
public delegate void XmlChangingEventHandler(object sender, Microsoft.Office.InfoPath.XmlChangingEventArgs e)
public delegate void XmlValidatingEventHandler(object sender, Microsoft.Office.InfoPath.XmlValidatingEventArgs e)

Control Events

public delegate void ClickedEventHandler(object sender, Microsoft.Office.InfoPath.ClickedEventArgs e)

Example: changed event, view switched event, button clicked event.

void FieldChanged(object sender, XmlEventArgs e) {}
void OnSwitchView(object sender, ViewSwitchedEventArgs e) {}
void button1_Click(object sender, EventArgs e) {}

Things to know about handling events

1. Events are handled first by the form’s business logic, then by others who register to handle events. Since events are handled asynchronously it is possible that the code in the business logic may cancel the event, and deny the host the opportunity to handle the event.
2. In order to handle the submit, save and merging events, the designer of the form template must specify that the event is to be handled through the use of code. Without enabling this in the form template the event will not be handled in code.
3. Buttons must specify that clicks be handled through code or the event will not be handled through code.
4. The sign event will only take place when the form is fully trusted.
5. The Loading and VersionUpgrade events are not available from third party hosted applications as these events occur before the form is loaded in the hosted application.

DeVere Dyett
Software Design Engineer in Test