Export (0) Print
Expand All

Form.ShowDialog Method ()

.NET Framework 1.1

Shows the form as a modal dialog box with no owner window.

[Visual Basic]
Overloads Public Function ShowDialog() As DialogResult
[C#]
public DialogResult ShowDialog();
[C++]
public: DialogResult ShowDialog();
[JScript]
public function ShowDialog() : DialogResult;

Return Value

One of the DialogResult values.

Exceptions

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

-or-

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.

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 form button (the button with an "X" at the top right 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 not 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.

Example

[Visual Basic, C#, C++] 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 assumes that a Form named testDialog is created and that it contains a TextBox control named TextBox1. Furthermore, the example assumes 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.

[Visual Basic] 
Public Sub ShowMyDialogBox()
    Dim testDialog As New Form2()
    
    ' Show testDialog as a modal dialog and determine if DialogResult = OK.
    If testDialog.ShowDialog(Me) = System.Windows.Forms.DialogResult.OK Then
        ' Read the contents of testDialog's TextBox.
        txtResult.Text = testDialog.TextBox1.Text
    Else
        txtResult.Text = "Cancelled"
    End If
    testDialog.Dispose()
End Sub 'ShowMyDialogBox

[C#] 
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();
}

[C++] 
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 = S"Cancelled";
      }
      testDialog->Dispose();
   }

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework

See Also

Form Class | Form Members | System.Windows.Forms Namespace | Form.ShowDialog Overload List | DialogResult

Show:
© 2015 Microsoft