Form.ShowDialog Método

Definição

Namespace:

System.Windows.Forms

Assembly:

System.Windows.Forms.dll

Mostra o formulário como uma caixa de diálogo modal.

Sobrecargas

ShowDialog()	Mostra o formulário como uma caixa de diálogo modal.
ShowDialog(IWin32Window)	Mostra o formulário como uma caixa de diálogo modal com o proprietário especificado.

ShowDialog()

Mostra o formulário como uma caixa de diálogo modal.

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

Retornos

DialogResult

Um dos valores de DialogResult.

Exceções

InvalidOperationException

O formulário que está sendo mostrado já está visível.

- ou - O formulário que está sendo mostrado está desabilitado.

- ou - O formulário que está sendo mostrado não é uma janela de nível superior.

- ou - O formulário que está sendo mostrado como uma caixa de diálogo já é um formulário modal.

- ou - O processo atual não está em execução no modo interativo do usuário (para obter mais informações, consulte UserInteractive).

Exemplos

O exemplo a seguir exibe um formulário como uma caixa de diálogo modal e avalia o valor retornado da caixa de diálogo antes de determinar se deseja ler o valor de um TextBox controle no formulário da caixa de diálogo. Este exemplo requer que um Form nome testDialog seja criado e que ele contenha um TextBox controle chamado TextBox1. Além disso, o exemplo requer que o código neste exemplo esteja contido e chamado de um diferente Form para ser exibido testDialog como uma caixa de diálogo modal. O exemplo usa a versão que ShowDialog especifica um proprietário para a caixa de diálogo.

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

Comentários

Você pode usar esse método para exibir uma caixa de diálogo modal em seu aplicativo. Quando esse método é chamado, o código a seguir não é executado até que a caixa de diálogo seja fechada. A caixa de diálogo pode ser atribuída a um dos valores da DialogResult enumeração atribuindo-a DialogResult à propriedade de um Button no formulário ou definindo a DialogResult propriedade do formulário no código. Esse valor é retornado por esse método. Você pode usar esse valor retornado para determinar como processar as ações que ocorreram na caixa de diálogo. Por exemplo, se a caixa de diálogo foi fechada e retornou o DialogResult.Cancel valor por meio desse método, você poderá impedir que o código após a chamada seja ShowDialog executado.

Quando um formulário é exibido como uma caixa de diálogo modal, clicar no botão Fechar (o botão com um X no canto superior direito do formulário) faz com que o formulário fique oculto e a DialogResult propriedade seja definida como DialogResult.Cancel. Ao contrário dos formulários não modais, o Close método não é chamado pelo .NET Framework quando o usuário clica no botão fechar formulário de uma caixa de diálogo ou define o valor da DialogResult propriedade. Em vez disso, o formulário está oculto e pode ser mostrado novamente sem criar uma nova instância da caixa de diálogo. Como um formulário exibido como uma caixa de diálogo está oculto em vez de fechado, você deve chamar o Dispose método do formulário quando o formulário não for mais necessário para seu aplicativo.

Esta versão do ShowDialog método não especifica um formulário ou controle como seu proprietário. Quando essa versão é chamada, a janela ativa atualmente é feita como o proprietário da caixa de diálogo. Se você quiser especificar um proprietário específico, use a outra versão desse método.

Confira também

• DialogResult

ShowDialog(IWin32Window)

Mostra o formulário como uma caixa de diálogo modal com o proprietário especificado.

public:
 System::Windows::Forms::DialogResult ShowDialog(System::Windows::Forms::IWin32Window ^ 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

Qualquer objeto que implementa IWin32Window e que representa a janela de nível superior que possuirá a caixa de diálogo modal.

Retornos

DialogResult

Um dos valores de DialogResult.

Exceções

ArgumentException

O formulário especificado no parâmetro owner é igual ao formulário que está sendo mostrado.

InvalidOperationException

O formulário que está sendo mostrado já está visível.

- ou - O formulário que está sendo mostrado está desabilitado.

- ou - O formulário que está sendo mostrado não é uma janela de nível superior.

- ou - O formulário que está sendo mostrado como uma caixa de diálogo já é um formulário modal.

- ou - O processo atual não está em execução no modo interativo do usuário (para obter mais informações, consulte UserInteractive).

Exemplos

O exemplo a seguir exibe um formulário como uma caixa de diálogo modal e avalia o valor retornado da caixa de diálogo antes de determinar se deseja ler o valor de um TextBox controle no formulário da caixa de diálogo. Este exemplo requer que um Form nome Form2 seja criado e que ele contenha um TextBox controle chamado TextBox1. O exemplo usa a versão que ShowDialog especifica um proprietário para a caixa de diálogo.

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

Comentários

Você pode usar esse método para exibir uma caixa de diálogo modal em seu aplicativo. Quando esse método é chamado, o código a seguir não é executado até que a caixa de diálogo seja fechada. A caixa de diálogo pode ser atribuída a um dos valores atribuindo-o DialogResult DialogResult à propriedade de um Button no formulário ou definindo a DialogResult propriedade do formulário no código. Esse valor é retornado por esse método. Você pode usar esse valor retornado para determinar como processar as ações que ocorreram na caixa de diálogo. Por exemplo, se a caixa de diálogo foi fechada e retornou o DialogResult.Cancel valor por meio desse método, você poderá impedir que o código após a chamada seja ShowDialog executado.

Quando um formulário é exibido como uma caixa de diálogo modal, clicar no botão Fechar (o botão com um X no canto superior direito do formulário) faz com que o formulário fique oculto e a DialogResult propriedade seja definida como DialogResult.Cancel. Ao contrário dos formulários de modeless, o Close método não é chamado pelo .NET Framework quando o usuário clica no botão fechar formulário de uma caixa de diálogo ou define o valor da DialogResult propriedade. Em vez disso, o formulário está oculto e pode ser mostrado novamente sem criar uma nova instância da caixa de diálogo. Como um formulário exibido como uma caixa de diálogo está oculto em vez de fechado, você deve chamar o Dispose método do formulário quando o formulário não for mais necessário para seu aplicativo.

Essa versão do ShowDialog método permite que você especifique um formulário específico que será o proprietário da caixa de diálogo mostrada.

Confira também

• DialogResult