FormEvents.Merge Event

Reference

Definition

Namespace:: Microsoft.Office.InfoPath

Assembly:: Microsoft.Office.InfoPath.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Occurs when the Merge Forms command is invoked from the user interface, or InfoPath is started with the /aggregate command-line switch.

public:
 abstract event Microsoft::Office::InfoPath::MergeEventHandler ^ Merge;

public abstract event Microsoft.Office.InfoPath.MergeEventHandler Merge;

member this.Merge : Microsoft.Office.InfoPath.MergeEventHandler

Public MustOverride Custom Event Merge As MergeEventHandler

Event Type

MergeEventHandler

Exceptions

InvalidOperationException

The developer attempted to bind the event in some location other than the InternalStartup method.

Examples

In the following example, the event handler for the Merge event sets variables to indicate the status of the merge operation, calls the MergeForm(XPathNavigator) method of the XmlForm class to perform the merge operation, and displays a message when merging is finished.

private bool _merging = false;
public void FormEvents_Merge(object sender, MergeEventArgs e)
{
   // Set global property to indicate that forms are being merged.
   if (e.Index == 0)
   {
      _merging = true;
   }
   // Merge the current form.
   MergeForm(e.Xml);
   e.CancelableArgs.Cancel = false;

   // Check to see if merging is finished.
   if ((e.Index + 1) == e.Count)
   {
      _merging = false;
      MessageBox.Show("Your request to merge " + e.Count + 
         " files is now complete.");
      // Perform any "after merge" operations here.
   }
}

Private _merging As Boolean = False
Public Sub FormEvents_Merge(ByVal sender As Object, _
   ByVal e As MergeEventArgs)
   ' Set global property to indicate that forms are being merged.
   If (e.Index = 0) Then
      _merging = True
   End If

   ' Merge the current form.
   MergeForm(e.Xml)
   e.CancelableArgs.Cancel = False

   ' Check to see if merging is finished.
   If ((e.Index + 1) = e.Count) Then
      _merging = False
      MessageBox.Show("Your request to merge " + e.Count + 
         " files is now complete.")
      ' Perform any "after merge" operations here.
   End If
End Sub

Remarks

Important: The Merge event is not meant to be instantiated by the developer in form code. You should only add event handlers for form-level events from the Microsoft InfoPath design mode user interface. When you add an event handler to your form template from the design mode user interface, InfoPath generates code in the InternalStartup method of your form code file using the EventManager class and the member of the FormEvents class to bind the event to its event handler. For information on how to add event handlers in InfoPath design mode, see How to: Add an Event Handler.

The Merge event is bound using the MergeEventHandler delegate.

The Merge event can be cancelled by using the CancelableArgs property of the MergeEventArgs class to set the Cancel property to true.

If you cancel the event, how InfoPath works depends on whether or how you set the Message and MessageDetails properties as described in the following table.

Set only the Message property to a message string	Your message and "Do you want to continue?" with Yes, Yes to All, and Cancel buttons.
Set only the MessageDetails property to a message string	"Microsoft Office InfoPath has encountered a problem merging the following form: formname.xml." and your detailed message with Yes, Yes to All, and Cancel buttons.
Set both the Message and MessageDetails properties to a message string	Your message and detailed message with Yes, Yes to All, and Cancel buttons.
Don't set the Message and MessageDetails properties, or set them both to a null reference (Nothing in Visual Basic) or an empty string	No dialog box is displayed.

The behaviors when a user clicks the Yes, Yes to All, and Cancel buttons are as follows:

Yes button	The merge operation takes place and the user has to click Yes for each individual form being merged.
Yes to All button	The merge operation takes place and all selected forms are merged.
Cancel button	The merging of all forms is cancelled. If the user clicked Yes for any forms before clicking Cancel, the merging of those forms is also cancelled.

The MergeEventArgs object is passed as a parameter to the event handler for the Merge event of a form. The MergeEventArgs object provides properties that can be used during the Merge event to programmatically interact with a form's underlying XML document and to determine merge properties such as the number of files being merged. The properties that the MergeEventArgs object provides are available only during this event.

During a single merge forms operation, the Merge event will occur (and the code in its event handler will run) once for each file being merged.

Important: In the InfoPath 2003 object model, there is an OnAfterImport event that occurs after the merge operation is completed. The Microsoft InfoPath object model does not provide an equivalent event. However, the same functionality can be achieved in an event handler for the Merge event by comparing the values of the Index and Count properties of the MergeEventArgs class to confirm that the merge operation is complete, before performing any "after merge" operations.

This type or member can be accessed only from code running in forms opened in Microsoft InfoPath Filler.

Applies to

Share via