How to: Display Alerts and Dialog Boxes Using the InfoPath 2003 Object Model

  • Article

When writing code to extend the functionality of a form template that uses the InfoPath 2003 object model, it is often useful to provide the user with information in a dialog box. Programmatically displaying a dialog box and related user interface elements is accomplished in InfoPath by using the methods of the UIObject interface.

Overview of the UIObject Interface

The UIObject interface provides the following methods, which form developers can use to have different types of dialog boxes displayed to InfoPath users as they are filling out a form.

Name Description

Alert

Displays a simple message box that contains a specified message string. This method should be used when no input is required from the user and only a message needs to be displayed. The dialog box displayed is closed by clicking the OK button.

Confirm

Displays a message box with buttons for input from a user. The value that is returned is one of the XdConfirmChoice enumerated constants.

SetSaveAsDialogFileName

Sets the default file name for a form in the Save As dialog box.

SetSaveAsDialogLocation

Sets the initial location at which the Save As dialog box starts to browse when it is opened.

ShowMailItem

Creates a new e-mail message in the default e-mail application, with the currently open form attached to the message.

ShowModalDialog

Displays a modal dialog box, based on the specified .html file and positional arguments. This method should be used if you want to display more than a simple message to the user and you need to get back some data from the user (beyond the simple confirmation that is provided by the Yes | No | Cancel buttons displayed by the Confirm method).

ShowSignatureDialog

Displays the built-in Digital Signatures dialog box.

Using the UIObject Interface

The UIObject interface is accessed through the UI property of the XDocument interface, which itself is accessed through the thisXDocument variable that is initialized in the _Startup method of the form code class. The following example demonstrates using the ShowMailItem and Alert methods of the UIObject interface.

thisXDocument.UI.ShowMailItem("someone@example.com","", "", 
   "Updated Form", "Here is the updated form that you requested.");

thisXDocument.UI.Alert("The e-mail message has been created.");

thisXDocument.UI.ShowMailItem("someone@example.com", "", "", _
   "Updated Form", "Here is the updated form that you requested.")

thisXDocument.UI.Alert("The e-mail message has been created.")

Using the ShowModalDialog Method

This example demonstrates how to use the ShowModalDialog method of the UIObject interface to display a custom dialog box defined in the HTML file show.html.

public void CTRL1_5_OnClick(DocActionEvent e)
{
   // Write your code here.
   thisXDocument.UI.ShowModalDialog(
      "show.html",(object)thisXDocument,200,450,50,50);
}

Public Sub CTRL1_5_OnClick(ByVal e As DocActionEvent)
   ' Write your code here.
   thisXDocument.UI.ShowModalDialog( _
      "show.html", _
      DirectCast(thisXDocument, Object), 200, 450, 50, 50)
End Sub

Both the Visual C# and Visual Basic samples depend on an HTML file named "show.html" that defines the dialog box that is invoked by the ShowModalDialog method. This HTML file displays some data from the form and shows a text box for the user to fill in a value. The value in the textbox is returned to the form when the dialog box is closed.

<HTML>
   <HEAD>
      <script language="JScript">
function BtnClick()
{
   xdocument = window.dialogArguments;
   myXml = xdocument.DOM.xml
   aForm = oForm.elements;
   aForm.textBox.value = myXml;
}
      </script>
   </HEAD>
   <BODY>
      <H1><FONT face="Arial">This is a modal dialog box</FONT> &nbsp;
      </H1>
      <BUTTON onclick="BtnClick()" id="BUTTON1" type="button">
         Get XML DOM
      </BUTTON>
      <FORM ID="oForm">
         <INPUT Type="text" name="textBox">
      </FORM>
   </BODY>
</HTML>

Important

The ShowModal method requires Full Trust to run or preview. For more information, see How to: Preview and Debug Managed Code Form Templates that Require Full Trust.

Using a Windows Form for a Dialog Box

Instead of using an HTML file to show the contents in a dialog box, as shown in the previous example, you can also display a Windows Form as a dialog box from your InfoPath form. This example demonstrates how to display a Windows Form as a custom dialog box from a button named ShowDialog on an InfoPath form. This does not require using the UIObject interface or any other members of the InfoPath object model.

Note

You cannot create and add a Windows Form to an InfoPath form template project created using Microsoft Visual Studio Tools for Applications (VSTA). To create and add a Windows form to a form template project, you must be using Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System and Visual Studio 2005 or Visual Studio 2008 with Visual Studio Tools for Office.

public void ShowDialog_OnClick(DocActionEvent e)
{
   // Instantiate and show Form1.
   Form1 myform = new Form1();
   myform.Show();
}

Public Sub ShowDialog_OnClick(ByVal e As DocActionEvent)
   ' Instantiate and show Form1.
   Dim MyForm As New Form1()
   MyForm.Show()
End Sub

Both the Visual C# and Visual Basic samples depend on a Windows Form named "Form1" that defines the dialog box that is invoked by the event handler for the ShowDialog button on the InfoPath form. To add Form1 to your InfoPath project, use the following procedure.

Add a Windows Form to an InfoPath project

  1. In the Solution Explorer, right-click the form code project (projectnameFormCode), point to Add, and then click Add Windows Form.

  2. In the Add New Item dialog box, name the form, and then click Open.

  3. From the Toolbox, drag a Button control onto the form.

  4. Double-click the button, and then add the following code to the button's event handler.

   // Close the form.
   this.Close();

   ' Close the form.
   Me.Close()