2/19/2021 Form.ShowDialog Method (System.Windows.

Forms) | Microsoft Docs

Form.ShowDialog Method

Namespace: System.Windows.Forms
Assembly: System.Windows.Forms.dll

Shows the form as a modal dialog box.

In this article
Definition
Overloads
ShowDialog()
ShowDialog(IWin32Window)

Overloads

ShowDialog() Shows the form as a modal dialog box.

ShowDialog(IWin32Window) Shows the form as a modal dialog box with the specified owner.

ShowDialog()

Shows the form as a modal dialog box.

C# ＝ Copy

public System.Windows.Forms.DialogResult ShowDialog ();

Returns
DialogResult

One of the DialogResult values.

https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.form.showdialog?view=net-5.0#System_Windows_Forms_Form_ShowDialog 1/6
2/19/2021 Form.ShowDialog Method (System.Windows.Forms) | Microsoft Docs

Exceptions
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).

Examples
The following 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 testDialog is
created and that it contains a TextBox control named TextBox1 . Furthermore, the
example requires that code in this example is contained and called from a different
Form in order to display testDialog as a modal dialog box. The example uses the
version of ShowDialog that specifies an owner for the dialog box.

C# ＝ Copy

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
https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.form.showdialog?view=net-5.0#System_Windows_Forms_Form_ShowDialog 2/6
2/19/2021 Form.ShowDialog Method (System.Windows.Forms) | Microsoft Docs

{
this.txtResult.Text = "Cancelled";
}
testDialog.Dispose();
}

Remarks
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 the DialogResult
enumeration 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 non-modal 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 does not specify a form or control as its owner.
When this version is called, the currently active window is made the owner of the dialog
box. If you want to specify a specific owner, use the other version of this method.

See also
DialogResult

Applies to
.NET 5.0 and other versions

https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.form.showdialog?view=net-5.0#System_Windows_Forms_Form_ShowDialog 3/6
2/19/2021 Form.ShowDialog Method (System.Windows.Forms) | Microsoft Docs

ShowDialog(IWin32Window)

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

C# ＝ Copy

public System.Windows.Forms.DialogResult ShowDialog

(System.Windows.Forms.IWin32Window owner);

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

Returns
DialogResult

One of the DialogResult values.

Exceptions
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-

https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.form.showdialog?view=net-5.0#System_Windows_Forms_Form_ShowDialog 4/6
2/19/2021 Form.ShowDialog Method (System.Windows.Forms) | Microsoft Docs

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).

Examples
The following 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.

C# ＝ Copy

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();
}

Remarks
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

https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.form.showdialog?view=net-5.0#System_Windows_Forms_Form_ShowDialog 5/6
2/19/2021 Form.ShowDialog Method (System.Windows.Forms) | Microsoft Docs

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.

See also
DialogResult

Applies to
.NET 5.0 and other versions

Is this page helpful?

 Yes  No

https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.form.showdialog?view=net-5.0#System_Windows_Forms_Form_ShowDialog 6/6