Como criar um controle de usuário (Windows Forms .NET)

  • Artigo

Este artigo ensina como adicionar um controle de usuário ao seu projeto e, em seguida, adicionar esse controle de usuário a um formulário. Você criará um controle de usuário reutilizável que é visualmente atraente e funcional. O novo controle agrupa um TextBox controle com um Button controle. Quando o usuário seleciona o botão, o texto na caixa de texto é desmarcado. Para obter mais informações sobre controles de usuário, consulte Visão geral do controle de usuário.

Importante

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

Adicionar um controle de usuário a um projeto

Depois de abrir seu projeto do Windows Formno Visual Studio, use os modelos do Visual Studio para criar um controle de usuário:

  1. No Visual Studio, localize a janela Project Explorer . Clique com o botão direito do mouse no projeto e escolha Adicionar>controle de usuário (Windows Forms).

    Clique com o botão direito do mouse no gerenciador de soluções do Visual Studio para adicionar um controle de usuário a um projeto do Windows Form

  2. Defina o Nome do controle como ClearableTextBox e pressione Adicionar.

    Caixa de diálogo Adicionar item no Visual Studio para Windows Forms

Depois que o controle de usuário é criado, o Visual Studio abre o designer:

O designer de controle de usuário no Visual Studio para Windows Forms

Criar a caixa de texto desmarcada

O controle de usuário é composto de controles constituintes, que são os controles que você cria na superfície de design, assim como você cria um formulário. Siga estas etapas para adicionar e configurar o controle de usuário e seus controles constituintes:

  1. Com o designer aberto, a superfície de design do controle de usuário deve ser o objeto selecionado. Se não estiver, clique na superfície de design para selecioná-la. Defina as seguintes propriedades na janela Propriedades :

    Propriedade Valor
    MinimumSize 84, 53
    Tamanho 191, 53

  2. Adicione um Label controle. Defina as seguintes propriedades:

    Propriedade Valor
    Nome lblTitle
    Localidade 3, 5

  3. Adicione um TextBox controle. Defina as seguintes propriedades:

    Propriedade Valor
    Nome txtValue
    Âncora Top, Left, Right
    Localidade 3, 23
    Tamanho 148, 23

  4. Adicione um Button controle. Defina as seguintes propriedades:

    Propriedade Valor
    Nome btnClear
    Âncora Top, Right
    Localidade 157, 23
    Tamanho 31, 23
    Texto ↻

    O controle deve se parecer com a seguinte imagem:

    Visual Studio com Windows Forms, mostrando o controle de usuário que acabou de ser projetado.

  5. Pressione F7 para abrir o editor de código da ClearableTextBox classe.

  6. Faça as seguintes alterações no código:

    1. Na parte superior do arquivo de código, importe o System.ComponentModel namespace.

    2. Adicione o atributo DefaultEvent à classe. Esse atributo define qual evento é gerado pelo consumidor quando o controle é clicado duas vezes no designer. Sendo o consumidor o objeto declarando e utilizando esse controle.

      using System.ComponentModel;

namespace UserControlProject
{
    [DefaultEvent(nameof(TextChanged))]
    public partial class ClearableTextBox : UserControl

      Imports System.ComponentModel

<DefaultEvent("TextChanged")>
Public Class ClearableTextBox

    3. Adicione um manipulador de eventos que encaminhe o TextBox.TextChanged evento para o consumidor:

      [Browsable(true)]
public new event EventHandler? TextChanged
{
    add => txtValue.TextChanged += value;
    remove => txtValue.TextChanged -= value;
}

      <Browsable(True)>
Public Shadows Custom Event TextChanged As EventHandler
    AddHandler(value As EventHandler)
        AddHandler txtValue.TextChanged, value
    End AddHandler
    RemoveHandler(value As EventHandler)
        RemoveHandler txtValue.TextChanged, value
    End RemoveHandler
    RaiseEvent(sender As Object, e As EventArgs)

    End RaiseEvent
End Event

      Observe que o evento tem o Browsable atributo declarado nele. Quando o Browsable é aplicado a um evento ou propriedade, ele controla se o item está ou não visível na janela Propriedades quando o controle é selecionado no designer. Nesse caso, true é passado como um parâmetro para o atributo indicando que o evento deve ser visível.

    4. Adicione uma propriedade string chamada Text, que encaminha a TextBox.Text propriedade para o consumidor:

      [Browsable(true)]
public new string Text
{
    get => txtValue.Text;
    set => txtValue.Text = value;
}

      <Browsable(True)>
Public Shadows Property Text() As String
    Get
        Return txtValue.Text
    End Get
    Set(value As String)
        txtValue.Text = value
    End Set
End Property

    5. Adicione uma propriedade string chamada Title, que encaminha a Label.Text propriedade para o consumidor:

      [Browsable(true)]
public string Title
{
    get => lblTitle.Text;
    set => lblTitle.Text = value;
}

      <Browsable(True)>
Public Property Title() As String
    Get
        Return lblTitle.Text
    End Get
    Set(value As String)
        lblTitle.Text = value
    End Set
End Property

  7. Alterne de volta para o ClearableTextBox designer e clique duas vezes no btnClear controle para gerar um manipulador para o Click evento. Adicione o seguinte código para o manipulador, que limpa a txtValue caixa de texto:

    private void btnClear_Click(object sender, EventArgs e) =>
    Text = "";

    Private Sub btnClear_Click(sender As Object, e As EventArgs)
    txtValue.Text = ""
End Sub

  8. Finalmente, compile o projeto clicando com o botão direito do mouse no projeto na janela Gerenciador de Soluções e selecionando Compilar. Não deve haver erros e, depois que a compilação for concluída, o ClearableTextBox controle aparecerá na caixa de ferramentas para uso.

A próxima etapa é usar o controle em um formulário.

Aplicativo de exemplo

Se você criou um novo projeto na última seção, você tem um espaço em branco Form chamado Form1, caso contrário, crie um novo formulário.

  1. Na janela Gerenciador de Soluções, clique duas vezes no formulário para abrir o designer. A superfície de design do formulário deve ser selecionada.

  2. Defina a propriedade do Size formulário como 432, 315.

  3. Abra a janela Caixa de Ferramentas e clique duas vezes no controle ClearableTextBox . Esse controle deve ser listado em uma seção com o nome do seu projeto.

  4. Novamente, clique duas vezes no controle ClearableTextBox para gerar um segundo controle.

  5. Volte para o designer e separe os controles para que você possa ver os dois.

  6. Selecione um controle e defina as seguintes propriedades:

    Propriedade Valor
    Nome ctlFirstName
    Localidade 12, 12
    Tamanho 191, 53
    Título First Name

  7. Selecione o outro controle e defina as seguintes propriedades:

    Propriedade Valor
    Nome ctlLastName
    Localidade 12, 71
    Tamanho 191, 53
    Título Last Name

  8. De volta à janela Caixa de Ferramentas , adicione um controle de rótulo ao formulário e defina as seguintes propriedades:

    Propriedade Valor
    Nome lblFullName
    Localidade 12, 252

  9. Em seguida, você precisa gerar os manipuladores de eventos para os dois controles de usuário. No designer, clique duas vezes no ctlFirstName controle. Essa ação gera o manipulador de eventos para o TextChanged evento e abre o editor de código.

  10. Troque de volta para o designer e clique duas vezes no ctlLastName controle para gerar o segundo manipulador de eventos.

  11. Troque novamente para o designer e clique duas vezes na barra de título do formulário. Essa ação gera um manipulador de eventos para o Load evento.

  12. No editor de códigos, adicione um método chamado UpdateNameLabel. Esse método combina ambos os nomes para criar uma mensagem e atribui a mensagem ao lblFullName controle.

    private void UpdateNameLabel()
{
    if (string.IsNullOrWhiteSpace(ctlFirstName.Text) || string.IsNullOrWhiteSpace(ctlLastName.Text))
        lblFullName.Text = "Please fill out both the first name and the last name.";
    else
        lblFullName.Text = $"Hello {ctlFirstName.Text} {ctlLastName.Text}, I hope you're having a good day.";
}

    Private Sub UpdateNameLabel()
    If String.IsNullOrWhiteSpace(ctlFirstName.Text) Or String.IsNullOrWhiteSpace(ctlLastName.Text) Then
        lblFullName.Text = "Please fill out both the first name and the last name."
    Else
        lblFullName.Text = $"Hello {ctlFirstName.Text} {ctlLastName.Text}, I hope you're having a good day."
    End If
End Sub

  13. Para ambos os TextChanged manipuladores de eventos, chame o UpdateNameLabel método:

    private void ctlFirstName_TextChanged(object sender, EventArgs e) =>
    UpdateNameLabel();

private void ctlLastName_TextChanged(object sender, EventArgs e) =>
    UpdateNameLabel();

    Private Sub ctlFirstName_TextChanged(sender As Object, e As EventArgs) Handles ctlFirstName.TextChanged
    UpdateNameLabel()
End Sub

Private Sub ctlLastName_TextChanged(sender As Object, e As EventArgs) Handles ctlLastName.TextChanged
    UpdateNameLabel()
End Sub

  14. Finalmente, chame o UpdateNameLabel método do evento do Load formulário:

    private void Form1_Load(object sender, EventArgs e) =>
    UpdateNameLabel();

    Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
    UpdateNameLabel()
End Sub

Execute o projeto e insira um nome e sobrenome:

Um aplicativo do Windows Formcom duas caixas de texto criadas a partir de controles de usuário e um rótulo.

Tente pressionar o ↻ botão para redefinir uma das caixas de texto.