Como manipular um evento de controle (Windows Forms .NET)

Artigo
10/18/2023

Eventos para controles (e para formulários) geralmente são definidos por meio do Visual Studio Visual Designer para Windows Forms. A definição de um evento por meio do Visual Designer é conhecida como manipulação de um evento em tempo de design. Você também pode manipular eventos dinamicamente no código, conhecido como manipulação de eventos em tempo de execução. Um evento criado em tempo de execução permite que você conecte manipuladores de eventos dinamicamente com base no que seu aplicativo está fazendo no momento.

Importante

A documentação do Guia da Área de Trabalho para .NET 7 e .NET 6 está em construção.

Manipular um evento - designer

No Visual Studio, use o Visual Designer para gerenciar manipuladores para eventos de controle. O Visual Designer irá gerar o código do manipulador e adicioná-lo ao evento para você.

Definir o manipulador

Use o painel Propriedades para adicionar ou definir o manipulador de um evento:

Abra o Visual Designer do formulário que contém o controle a ser alterado.
Selecione o controle .
Altere o modo do painel Propriedades para Eventos pressionando o botão de eventos ().
Localize o evento ao qual você deseja adicionar um manipulador, por exemplo, o evento Click :
Realize um dos seguintes procedimentos:
- Clique duas vezes no evento para gerar um novo manipulador, ele ficará em branco se nenhum manipulador for atribuído. Se não estiver em branco, essa ação abrirá o código do formulário e navegará até o manipulador existente.
- Use a caixa de seleção ( ) para escolher um manipulador existente.
  
  A caixa de seleção listará todos os métodos que têm uma assinatura de método compatível para o manipulador de eventos.

Limpar o manipulador

Para remover um manipulador de eventos, você não pode simplesmente excluir o código do manipulador que está no arquivo code-behind do formulário, ele ainda é referenciado pelo evento. Use o painel Propriedades para remover o manipulador de um evento:

Abra o Visual Designer do formulário que contém o controle a ser alterado.
Selecione o controle .
Altere o modo do painel Propriedades para Eventos pressionando o botão de eventos ().
Localize o evento que contém o manipulador que você deseja remover, por exemplo, o evento Click :
Clique com o botão direito do mouse no evento e escolha Redefinir.

Manipular um evento - código

Normalmente, você adiciona manipuladores de eventos a controles em tempo de design por meio do Visual Designer. No entanto, você pode criar controles em tempo de execução, o que requer que você adicione manipuladores de eventos no código. Adicionar manipuladores no código também lhe dá a chance de adicionar vários manipuladores ao mesmo evento.

Adicionar um manipulador

O exemplo a seguir mostra como criar um controle e adicionar um manipulador de eventos. Esse controle é criado no Button.Click manipulador de eventos um botão diferente. Quando Button1 é pressionado. O código move e dimensiona um novo botão. O evento do Click novo botão é manipulado MyNewButton_Click pelo método. Para que o novo botão apareça, ele é adicionado à coleção do Controls formulário. Também há código para remover o manipulador do evento, isso é discutido na seção Remover o Button1.Click manipulador.

private void button1_Click(object sender, EventArgs e)
{
    // Create and add the button
    Button myNewButton = new()
    {
        Location = new Point(10, 10),
        Size = new Size(120, 25),
        Text = "Do work"
    };

    // Handle the Click event for the new button
    myNewButton.Click += MyNewButton_Click;
    this.Controls.Add(myNewButton);

    // Remove this button handler so the user cannot do this twice
    button1.Click -= button1_Click;
}

private void MyNewButton_Click(object sender, EventArgs e)
{
    
}

Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
    'Create and add the button
    Dim myNewButton As New Button() With {.Location = New Point(10, 10),
                                          .Size = New Size(120, 25),
                                          .Text = "Do work"}

    'Handle the Click event for the new button
    AddHandler myNewButton.Click, AddressOf MyNewButton_Click
    Me.Controls.Add(myNewButton)

    'Remove this button handler so the user cannot do this twice
    RemoveHandler Button1.Click, AddressOf Button1_Click
End Sub

Private Sub MyNewButton_Click(sender As Object, e As EventArgs)

End Sub

Para executar esse código, faça o seguinte em um formulário com o Visual Studio Visual Designer:

Adicione um novo botão ao formulário e nomeie-o como Button1.
Altere o modo do painel Propriedades para Eventos pressionando o botão de evento ().
Clique duas vezes no evento Click para gerar um manipulador. Essa ação abre a janela de código e gera um método em branco Button1_Click .
Substitua o código do método pelo código anterior acima.

Para obter mais informações sobre eventos C#, consulte Eventos (C#) Para obter mais informações sobre eventos do Visual Basic, consulte Eventos (Visual Basic)

Remover o manipulador

A seção Adicionar um manipulador usou algum código para demonstrar a adição de um manipulador . Esse código também continha uma chamada para remover um manipulador:

button1.Click -= button1_Click;

RemoveHandler Button1.Click, AddressOf Button1_Click

Essa sintaxe pode ser usada para remover qualquer manipulador de eventos de qualquer evento.

Para obter mais informações sobre eventos C#, consulte Eventos (C#) Para obter mais informações sobre eventos do Visual Basic, consulte Eventos (Visual Basic)

Como usar vários eventos com o mesmo manipulador

Com o painel Propriedades do Visual Studio Visual Designer, você pode selecionar o mesmo manipulador já em uso por um evento diferente. Siga as instruções na seção Definir o manipulador para selecionar um manipulador existente em vez de criar um novo.

No C#, o manipulador é anexado ao evento de um controle no código de designer do formulário, que foi alterado por meio do Visual Designer. Para obter mais informações sobre eventos C#, consulte Eventos (C#)

Visual Basic

No Visual Basic, o manipulador é anexado a um evento de controle no arquivo code-behind do formulário, onde o código do manipulador de eventos é declarado. Várias Handles palavras-chave podem ser adicionadas ao código do manipulador de eventos para usá-lo com vários eventos. O Visual Designer irá gerar a Handles palavra-chave para você e adicioná-la ao manipulador de eventos. No entanto, você pode facilmente fazer isso sozinho para qualquer manipulador de eventos e eventos do controle, desde que a assinatura do método manipulador corresponda ao evento. Para obter mais informações sobre eventos do Visual Basic, consulte Eventos (Visual Basic)

Este código demonstra como o mesmo método pode ser usado como um manipulador para dois eventos diferentes Button.Click :

Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click, Button2.Click
    'Do some work to handle the events
End Sub