Display Alerts and Dialog Boxes Using the InfoPath 2003 Object Model
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 email message in the default email 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 email message has been created.");
thisXDocument.UI.ShowMailItem("someone@example.com", "", "", _
"Updated Form", "Here is the updated form that you requested.")
thisXDocument.UI.Alert("The email 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>
</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 ShowModalDialog method requires Full Trust to run or preview. For more information, see Preview and Debug Form Templates that Require Full Trust.