Export (0) Print
Expand All

Form.ShowDialog Method (IWin32Window)

Shows the form as a modal dialog box with the specified owner.

Namespace:  System.Windows.Forms
Assembly:  System.Windows.Forms (in System.Windows.Forms.dll)

public DialogResult ShowDialog(
	IWin32Window owner
)

Parameters

owner
Type: System.Windows.Forms.IWin32Window

Any object that implements IWin32Window that represents the top-level window that will own the modal dialog box.

Return Value

Type: System.Windows.Forms.DialogResult
One of the DialogResult values.

ExceptionCondition
ArgumentException

The form specified in the owner parameter is the same as the form being shown.

InvalidOperationException

The form being shown is already visible.

-or-

The form being shown is disabled.

-or-

The form being shown is not a top-level window.

-or-

The form being shown as a dialog box is already a modal form.

-or-

The current process is not running in user interactive mode (for more information, see UserInteractive).

You can use this method to display a modal dialog box in your application. When this method is called, the code following it is not executed until after the dialog box is closed. The dialog box can be assigned one of the values of DialogResult by assigning it to the DialogResult property of a Button on the form or by setting the DialogResult property of the form in code. This value is then returned by this method. You can use this return value to determine how to process the actions that occurred in the dialog box. For example, if the dialog box was closed and returned the DialogResult.Cancel value through this method, you could prevent code following the call to ShowDialog from executing.

When a form is displayed as a modal dialog box, clicking the Close button (the button with an X at the upper-right corner of the form) causes the form to be hidden and the DialogResult property to be set to DialogResult.Cancel. Unlike modeless forms, the Close method is not called by the .NET Framework when the user clicks the close form button of a dialog box or sets the value of the DialogResult property. Instead the form is hidden and can be shown again without creating a new instance of the dialog box. Because a form displayed as a dialog box is hidden instead of closed, you must call the Dispose method of the form when the form is no longer needed by your application.

This version of the ShowDialog method allows you to specify a specific form that will own the dialog box that is shown.

The following code example displays a form as a modal dialog box and evaluates the return value of the dialog box before determining whether to read the value of a TextBox control on the dialog box form. This example requires that a Form named Form2 is created and that it contains a TextBox control named TextBox1. The example uses the version of ShowDialog that specifies an owner for the dialog box.

public void ShowMyDialogBox()
{
   Form2 testDialog = new Form2();

   // Show testDialog as a modal dialog and determine if DialogResult = OK. 
   if (testDialog.ShowDialog(this) == DialogResult.OK)
   {
      // Read the contents of testDialog's TextBox. 
      this.txtResult.Text = testDialog.TextBox1.Text;
   }
   else
   {
      this.txtResult.Text = "Cancelled";
   }
   testDialog.Dispose();
}

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft