Form.ShowDialog Método

Definición

Muestra el formulario como un cuadro de diálogo modal.Shows the form as a modal dialog box.

Sobrecargas

ShowDialog()

Muestra el formulario como un cuadro de diálogo modal.Shows the form as a modal dialog box.

ShowDialog(IWin32Window)

Muestra el formulario como un cuadro de diálogo modal con el propietario especificado.Shows the form as a modal dialog box with the specified owner.

ShowDialog()

Muestra el formulario como un cuadro de diálogo modal.Shows the form as a modal dialog box.

public:
 System::Windows::Forms::DialogResult ShowDialog();
public System.Windows.Forms.DialogResult ShowDialog ();
member this.ShowDialog : unit -> System.Windows.Forms.DialogResult
Public Function ShowDialog () As DialogResult

Devoluciones

DialogResult

Uno de los valores de DialogResult.One of the DialogResult values.

Excepciones

El formulario que se va a mostrar ya está visible.The form being shown is already visible.

o bien-or- El formulario que se va a mostrar está deshabilitado.The form being shown is disabled.

o bien-or- El formulario que se va a mostrar no es una ventana de nivel superior.The form being shown is not a top-level window.

o bien-or- El formulario que se va a mostrar como un cuadro de diálogo ya es un formulario modal.The form being shown as a dialog box is already a modal form.

o bien-or- El proceso actual no se está ejecutando en modo de interacción con el usuario (para obtener más información, vea UserInteractive).The current process is not running in user interactive mode (for more information, see UserInteractive).

Ejemplos

En el ejemplo siguiente se muestra un formulario como un cuadro de diálogo modal y se evalúa el valor devuelto del cuadro de diálogo antes de determinar si se va a leer el valor de un control de TextBox en el formulario del cuadro de diálogo.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. En este ejemplo se requiere que se cree un Form denominado testDialog y que contenga un control TextBox denominado TextBox1.This example requires that a Form named testDialog is created and that it contains a TextBox control named TextBox1. Además, el ejemplo requiere que el código de este ejemplo esté contenido y se llame desde un Form diferente para mostrar testDialog como un cuadro de diálogo modal.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. En el ejemplo se utiliza la versión de ShowDialog que especifica un propietario para el cuadro de diálogo.The example uses the version of ShowDialog that specifies an owner for the dialog box.

void ShowMyDialogBox()
{
   Form2^ testDialog = gcnew 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";
   }

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

Comentarios

Puede usar este método para mostrar un cuadro de diálogo modal en la aplicación.You can use this method to display a modal dialog box in your application. Cuando se llama a este método, el código siguiente no se ejecuta hasta que se cierre el cuadro de diálogo.When this method is called, the code following it is not executed until after the dialog box is closed. Se puede asignar uno de los valores de la enumeración DialogResult al cuadro de diálogo asignándole a la propiedad DialogResult de una Button en el formulario o estableciendo la propiedad DialogResult del formulario en código.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. Este método devuelve este valor.This value is then returned by this method. Puede usar este valor devuelto para determinar cómo se procesan las acciones que se produjeron en el cuadro de diálogo.You can use this return value to determine how to process the actions that occurred in the dialog box. Por ejemplo, si se ha cerrado el cuadro de diálogo y se ha devuelto el valor DialogResult.Cancel a través de este método, puede impedir que se ejecute el código que sigue a la llamada a ShowDialog.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.

Cuando un formulario se muestra como un cuadro de diálogo modal, al hacer clic en el botón cerrar (el botón con una X en la esquina superior derecha del formulario), se oculta el formulario y se establece la propiedad DialogResult en DialogResult.Cancel.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. A diferencia de las formas no modales, el .NET Framework no llama al método Close cuando el usuario hace clic en el botón Cerrar formulario de un cuadro de diálogo o establece el valor de la propiedad DialogResult.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. En su lugar, el formulario está oculto y se puede mostrar de nuevo sin crear una nueva instancia del cuadro de diálogo.Instead the form is hidden and can be shown again without creating a new instance of the dialog box. Dado que un formulario mostrado como cuadro de diálogo está oculto en lugar de cerrado, debe llamar al método Dispose del formulario cuando la aplicación ya no necesite el formulario.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.

Esta versión del método ShowDialog no especifica un formulario o un control como propietario.This version of the ShowDialog method does not specify a form or control as its owner. Cuando se llama a esta versión, la ventana activa actualmente se convierte en el propietario del cuadro de diálogo.When this version is called, the currently active window is made the owner of the dialog box. Si desea especificar un propietario específico, use la otra versión de este método.If you want to specify a specific owner, use the other version of this method.

Consulte también:

ShowDialog(IWin32Window)

Muestra el formulario como un cuadro de diálogo modal con el propietario especificado.Shows the form as a modal dialog box with the specified owner.

public:
 System::Windows::Forms::DialogResult ShowDialog(System::Windows::Forms::IWin32Window ^ owner);
public System.Windows.Forms.DialogResult ShowDialog (System.Windows.Forms.IWin32Window owner);
member this.ShowDialog : System.Windows.Forms.IWin32Window -> System.Windows.Forms.DialogResult
Public Function ShowDialog (owner As IWin32Window) As DialogResult

Parámetros

owner
IWin32Window

Cualquier objeto que implemente IWin32Window que representa la ventana de nivel superior que será propietaria del cuadro de diálogo modal.Any object that implements IWin32Window that represents the top-level window that will own the modal dialog box.

Devoluciones

DialogResult

Uno de los valores de DialogResult.One of the DialogResult values.

Excepciones

El formulario especificado en el parámetro owner es el mismo que el formulario que se va a mostrar.The form specified in the owner parameter is the same as the form being shown.

El formulario que se va a mostrar ya está visible.The form being shown is already visible.

o bien-or- El formulario que se va a mostrar está deshabilitado.The form being shown is disabled.

o bien-or- El formulario que se va a mostrar no es una ventana de nivel superior.The form being shown is not a top-level window.

o bien-or- El formulario que se va a mostrar como un cuadro de diálogo ya es un formulario modal.The form being shown as a dialog box is already a modal form.

o bien-or- El proceso actual no se está ejecutando en modo de interacción con el usuario (para obtener más información, vea UserInteractive).The current process is not running in user interactive mode (for more information, see UserInteractive).

Ejemplos

En el ejemplo siguiente se muestra un formulario como un cuadro de diálogo modal y se evalúa el valor devuelto del cuadro de diálogo antes de determinar si se va a leer el valor de un control de TextBox en el formulario del cuadro de diálogo.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. En este ejemplo se requiere que se cree un Form denominado Form2 y que contenga un control TextBox denominado TextBox1.This example requires that a Form named Form2 is created and that it contains a TextBox control named TextBox1. En el ejemplo se utiliza la versión de ShowDialog que especifica un propietario para el cuadro de diálogo.The example uses the version of ShowDialog that specifies an owner for the dialog box.

void ShowMyDialogBox()
{
   Form2^ testDialog = gcnew 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";
   }

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

Comentarios

Puede usar este método para mostrar un cuadro de diálogo modal en la aplicación.You can use this method to display a modal dialog box in your application. Cuando se llama a este método, el código siguiente no se ejecuta hasta que se cierre el cuadro de diálogo.When this method is called, the code following it is not executed until after the dialog box is closed. Se puede asignar uno de los valores de DialogResult al cuadro de diálogo asignándole a la propiedad DialogResult de un Button en el formulario o estableciendo la propiedad DialogResult del formulario en código.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. Este método devuelve este valor.This value is then returned by this method. Puede usar este valor devuelto para determinar cómo se procesan las acciones que se produjeron en el cuadro de diálogo.You can use this return value to determine how to process the actions that occurred in the dialog box. Por ejemplo, si se ha cerrado el cuadro de diálogo y se ha devuelto el valor DialogResult.Cancel a través de este método, puede impedir que se ejecute el código que sigue a la llamada a ShowDialog.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.

Cuando un formulario se muestra como un cuadro de diálogo modal, al hacer clic en el botón cerrar (el botón con una X en la esquina superior derecha del formulario), se oculta el formulario y se establece la propiedad DialogResult en DialogResult.Cancel.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. A diferencia de los formularios no modales, el .NET Framework no llama al método Close cuando el usuario hace clic en el botón Cerrar formulario de un cuadro de diálogo o establece el valor de la propiedad DialogResult.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. En su lugar, el formulario está oculto y se puede mostrar de nuevo sin crear una nueva instancia del cuadro de diálogo.Instead the form is hidden and can be shown again without creating a new instance of the dialog box. Dado que un formulario mostrado como cuadro de diálogo está oculto en lugar de cerrado, debe llamar al método Dispose del formulario cuando la aplicación ya no necesite el formulario.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.

Esta versión del método ShowDialog permite especificar un formulario específico que será el propietario del cuadro de diálogo que se muestra.This version of the ShowDialog method allows you to specify a specific form that will own the dialog box that is shown.

Consulte también:

Se aplica a