Partilhar 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 controle TextBox com um controle Button. Quando o utilizador 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 consumidores de controle de usuário

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

  • Formulários que contêm seu controle de usuário.
  • Outros controles que hospedam seu controle de usuário.
  • Aplicativos que fazem referência à sua 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 seu controle de usuário — eles apenas interagem com as propriedades e 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 de código mínimo viável para um controle de usuário. Em sua essência, um controle de usuário precisa:

  • Encaminhamento de eventos - Passe eventos de controles internos para o consumidor.
  • Exposição à propriedade - Permitir que o consumidor aceda a propriedades de controlo interno.
  • Comportamento lógico - Manipule 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 com os 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 Gerenciador de Soluções . Clique com o botão direito do rato 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 controlo como ClearableTextBox e pressione Adicionar.

    caixa de diálogo de adição de 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

Desenhe a caixa de texto que pode ser limpa

O controlo de utilizador é composto por controlos constituintes, que são os controlos que você cria na superfície de design, assim como você projeta 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 de controle do usuário deve ser o objeto selecionado. Se não estiver, clique na área 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 controle Label. Defina as seguintes propriedades:

    Propriedade Valor
    Nome lblTitle
    Localização 3, 5

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

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

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

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

    O controlo deve assemelhar-se à imagem seguinte:

    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 para a classe ClearableTextBox.

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

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

    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 Attributes (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 TextBox.TextChanged evento para os consumidores do seu 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 Browsable declarado nele. Quando o é aplicado a um evento ou propriedade, ele controla se o item está 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 ser visível.

    4. Adicione uma propriedade string chamada Text, que expõe a TextBox.Text propriedade aos consumidores do 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 string chamada Title, que expõe a Label.Text propriedade aos consumidores do 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 designer de ClearableTextBox e clique duas vezes no controle btnClear para gerar um manipulador para o evento Click. Adicione o seguinte código para o manipulador, que limpa a caixa de texto txtValue:

    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, construa o projeto clicando com o botão direito do mouse sobre o 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 controle ClearableTextBox aparecerá na caixa de ferramentas para uso.

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

Exemplo de aplicação

Se criou um novo projeto na última seção, terá um Form vazio chamado Form1; caso contrário, crie um novo formulário.

  1. Na janela Explorador 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 Toolbox e clique duas vezes no controlo ClearableTextBox. Esse controle deve ser listado em uma seção com o nome do seu projeto.

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

  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. De volta à 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 controle ctlFirstName. Essa ação gera o manipulador de eventos para o evento TextChanged e abre o editor de código.

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

  11. Retorne 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 evento Load.

  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 controle lblFullName.

    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 manipuladores de eventos TextChanged, 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. Finalmente, 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