Compartilhar via

Como criar um controle de usuário

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 é limpo. Para obter mais informações sobre controles de usuário, consulte Visão geral do controle de usuário.

Noções básicas sobre os consumidores de controle de usuário

Ao longo deste artigo, o termo consumidor refere-se a qualquer código que use seu controle de usuário. Isso inclui:

  • Formulários que contêm o controle de usuário.
  • Outros controles que hospedam o controle do usuário.
  • Aplicativos que fazem referência à biblioteca de controle de usuário.

Ao criar um controle de usuário, você está criando um componente reutilizável. O consumidor é quem usa esse componente colocando-o em um formulário, definindo suas propriedades ou respondendo a seus eventos. O consumidor não precisa saber sobre os controles internos (como o TextBox e Button) que compõem o controle do usuário; eles só interagem com as propriedades e os eventos que você escolhe expor.

Padrão de código essencial para controles de usuário

Antes de adicionar a implementação detalhada, é útil entender o padrão mínimo de código viável para um controle de usuário. Em sua essência, um controle de usuário precisa:

  • Encaminhamento de eventos – Transmita eventos de controles internos para o consumidor.
  • Exposição de propriedades – Permita que o usuário acesse as propriedades de controle interno.
  • Comportamento lógico – manipular interações entre controles internos.

O código a seguir demonstra esses padrões. Você não precisa de todo esse código para um controle de usuário básico, mas esses padrões ajudam a criar um componente profissional e reutilizável que se integra bem aos aplicativos de designer e consumidor.

Adicionar um novo controle de usuário

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

  1. No Visual Studio, localize a janela do Gerenciador de Soluções . 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 Forms

  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 por controles constituintes, que são os controles que você cria na superfície de projeto, assim como ao projetar 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 do 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
    Tamanho Mínimo 84, 53
    Tamanho 191, 53

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

    Propriedade Valor
    Nome lblTitle
    Localização 3, 5

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

    Propriedade Valor
    Nome txtValue
    Âncora Top, Left, Right
    Localização 3, 23
    Tamanho 148, 23

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

    Propriedade Valor
    Nome btnClear
    Âncora Top, Right
    Localização 157, 23
    Tamanho 31, 23
    Texto ↻

    O controle deve ser semelhante à 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 quando o consumidor (o formulário ou aplicativo que usa esse controle) clica duas vezes no controle no designer. Para obter mais informações sobre atributos, consulte Atributos (C#) ou Visão geral de atributos (Visual Basic).

      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 encaminha o evento TextBox.TextChanged aos consumidores do controle de usuário:

      [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 atributo declarado Browsable nele. Quando o Browsable é aplicado a um evento ou propriedade, ele controla se o item fica visível ou não na janela Propriedades quando o controle é selecionado no designer. Nesse caso, true é passado como um parâmetro para o atributo que indica que o evento deve estar visível.

    4. Adicione uma propriedade de cadeia de caracteres chamada Text, que expõe a TextBox.Text propriedade aos consumidores de seu controle de usuário:

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

      <Browsable(True)>
<DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)>
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 de cadeia de caracteres chamada Title, que expõe a Label.Text propriedade aos consumidores de seu controle de usuário:

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

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

  7. Volte 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. Por fim, 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, após a conclusão do build, o ClearableTextBox controle aparece 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, terá um Form em branco 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 Size do 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 ambos.

  6. Selecione um controle e defina as seguintes propriedades:

    Propriedade Valor
    Nome ctlFirstName
    Localização 12, 12
    Tamanho 191, 53
    Título First Name

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

    Propriedade Valor
    Nome ctlLastName
    Localização 12, 71
    Tamanho 191, 53
    Título Last Name

  8. Volte à janela caixa de ferramentas, adicione um controle de rótulo ao formulário e defina as seguintes propriedades:

    Propriedade Valor
    Nome lblFullName
    Localização 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. Alterne de volta para o designer e clique duas vezes no ctlLastName controle para gerar o segundo manipulador de eventos.

  11. Volte 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 os dois 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 método UpdateNameLabel:

    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. Por fim, chame o método UpdateNameLabel do evento Load do 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 Forms com 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.

  • Last updated on