Crie um controle personalizado simples

2025-05-07

Este artigo ensina como criar controle personalizado do Windows Forms. O controlo simples desenvolvido neste artigo posiciona o conteúdo do controlo à Text esquerda, ao centro ou à direita do controlo. O alinhamento do texto pode ser alterado. Esse controle não gera nem manipula eventos.

Neste artigo, vai aprender a:

Adicione uma propriedade e um campo para manipular a configuração de alinhamento horizontal do texto.
Use OnTextChanged para invalidar o controle.
Forneça código no OnPaint método para desenhar texto na superfície do controle.

Adicionar um controle personalizado

A primeira etapa é adicionar um controle personalizado ao seu projeto.

No Visual Studio, localize a janela Gerenciador de Soluções . Clique com o botão direito do mouse no projeto e escolha Adicionar>novo item.
Procure Controlo Personalizado e selecione-o.
Defina o nome do arquivo como FirstControl e selecione Adicionar.
Se o modo Design do controle estiver visível, alterne para a visualização de código. Pressione F7 ou selecione o link de opção para visualização de código .

Sugestão

Você também pode clicar com o botão direito do mouse no arquivo na janela Gerenciador de Soluções e selecionar Exibir Código.

Agora você deve estar olhando para o código-fonte do controle personalizado, que se parece com o seguinte trecho:

public partial class FirstControl : Control
{
    public FirstControl()
    {
        InitializeComponent();
    }

    protected override void OnPaint(PaintEventArgs pe)
    {
        base.OnPaint(pe);
    }
}

Public Class FirstControl

    Protected Overrides Sub OnPaint(ByVal e As System.Windows.Forms.PaintEventArgs)
        MyBase.OnPaint(e)

        'Add your custom paint code here
    End Sub

End Class

Adicionar uma propriedade

Crie uma nova propriedade no controle chamado TextAlignment. Esta propriedade ajustará onde o texto é pintado no controle. Com a FirstControl classe, execute as seguintes etapas:

Adicione um campo com o nome _textAlignment do tipo HorizontalAlignment.

private HorizontalAlignment _textAlignment = HorizontalAlignment.Left;

Private _textAlignment As HorizontalAlignment = HorizontalAlignment.Left

Envolva o campo numa propriedade chamada TextAlignment. Ao definir a propriedade, chame o Invalidate método para forçar o controle a repintar a si mesmo.

public HorizontalAlignment TextAlignment
{
    get => _textAlignment;
    set
    {
        _textAlignment = value;
        Invalidate();
    }
}

Public Property TextAlignment As HorizontalAlignment
    Get
        Return _textAlignment
    End Get

    Set(value As HorizontalAlignment)
        _textAlignment = value
        Invalidate()
    End Set
End Property

Adicione os seguintes atributos à propriedade para integrá-la com a janela Propriedades no Visual Studio.

Category—A categoria aplicada ao imóvel.
Description—A descrição do imóvel.
DefaultValue—Um valor padrão para a propriedade.

O valor padrão permite que a propriedade seja redefinida pelo designer. Ele também ajuda a determinar quando a propriedade deve ser serializada para o code-behind, já que os valores padrão não são serializados.

[System.ComponentModel.Category("Alignment"),
System.ComponentModel.Description("Specifies the alignment of text."),
System.ComponentModel.DefaultValue(HorizontalAlignment.Left)]
public HorizontalAlignment TextAlignment

<System.ComponentModel.Category("Alignment"),
System.ComponentModel.Description("Specifies the alignment of text."),
System.ComponentModel.DefaultValue(HorizontalAlignment.Left)>
Public Property TextAlignment As HorizontalAlignment

Manipular texto modificado

A TextAlignment propriedade chama Invalidate para que o controle se repinte. Isso garante que o alinhamento correto seja utilizado instantaneamente durante a renderização Text do controlo. No entanto, se a Text propriedade mudar, nada será atualizado porque Text não chama Invalidate. No entanto, a propriedade chama o método OnTextChanged, que pode-se substituir para chamar Invalidate e forçar o controlo a redesenhar-se.

Com a FirstControl classe, execute as seguintes etapas:

Substitua o método OnTextChanged.
Ligue base.OnTextChanged para que o TextChanged evento seja gerado, conforme esperado pelos consumidores do controlo.
Chame o método Invalidate para forçar a repintura.

O seu código deve estar como o seguinte fragmento:

protected override void OnTextChanged(EventArgs e)
{
    base.OnTextChanged(e);
    Invalidate();
}

Protected Overrides Sub OnTextChanged(e As EventArgs)
    MyBase.OnTextChanged(e)
    Invalidate()
End Sub

Pintar o controle

A última parte do controle personalizado é a pintura. Com a FirstControl classe, execute as seguintes etapas:

Localize o OnPaint método gerado pelo modelo. Se estiver ausente, substitua-o pela classe base.
Crie uma nova StringFormat variável chamada style.
```
StringFormat style = new();
```
```
Dim style As New StringFormat
```
O System.Drawing.StringFormat tipo encapsula informações de layout de texto e fornece acesso ao alinhamento.

Com base em TextAlignment, defina a style.Alignment propriedade com o valor apropriado.

style.Alignment = TextAlignment switch
{
    // Map the HorizontalAlignment enum to the StringAlignment enum
    HorizontalAlignment.Left => StringAlignment.Near,
    HorizontalAlignment.Right => StringAlignment.Far,
    HorizontalAlignment.Center => StringAlignment.Center,
    
    // Default to Near alignment
    _ => StringAlignment.Near
};

'Map the HorizontalAlignment enum to the StringAlignment enum
Select Case TextAlignment
    Case HorizontalAlignment.Left
        style.Alignment = StringAlignment.Near
    Case HorizontalAlignment.Right
        style.Alignment = StringAlignment.Far
    Case HorizontalAlignment.Center
        style.Alignment = StringAlignment.Center
End Select

Desenhe a Text propriedade com Graphics.DrawString.

// Create the brush and automatically dispose it.
using SolidBrush foreBrush = new(ForeColor);

// Call the DrawString method to write text.
// Text, Font, and ClientRectangle are inherited properties.
pe.Graphics.DrawString(Text, Font, foreBrush, ClientRectangle, style);

'Create the brush and automatically dispose it.
Using foreBrush As New SolidBrush(ForeColor)
    'Call the DrawString method to write text.
    'Text, Font, and ClientRectangle are inherited properties.
    e.Graphics.DrawString(Text, Font, foreBrush, ClientRectangle, style)
End Using

Importante

O Graphics.DrawString método usa a Brush para a cor do texto. Brushes deve ser eliminado após a utilização.

O Graphics.DrawString método usa texto, uma fonte, cor e opções de formatação para desenhar uma cadeia de caracteres.

Ligue base.OnPaint para garantir que o evento Paint seja ativado.
```
base.OnPaint(pe);
```
```
MyBase.OnPaint(e)
```
Salve o arquivo de código e compile o projeto. Depois que o projeto é compilado, o Visual Studio adiciona o controle personalizado à janela Caixa de Ferramentas quando você abre o Visual Designer.

O seu código deve estar como o seguinte fragmento:

public partial class FirstControl : Control
{
    private HorizontalAlignment _textAlignment = HorizontalAlignment.Left;

    [System.ComponentModel.Category("Alignment"),
    System.ComponentModel.Description("Specifies the alignment of text."),
    System.ComponentModel.DefaultValue(HorizontalAlignment.Left)]
    public HorizontalAlignment TextAlignment
    {
        get => _textAlignment;
        set
        {
            _textAlignment = value;
            Invalidate();
        }
    }

    public FirstControl()
    {
        InitializeComponent();
    }

    protected override void OnTextChanged(EventArgs e)
    {
        base.OnTextChanged(e);
        Invalidate();
    }

    protected override void OnPaint(PaintEventArgs pe)
    {
        StringFormat style = new();

        style.Alignment = TextAlignment switch
        {
            // Map the HorizontalAlignment enum to the StringAlignment enum
            HorizontalAlignment.Left => StringAlignment.Near,
            HorizontalAlignment.Right => StringAlignment.Far,
            HorizontalAlignment.Center => StringAlignment.Center,
            
            // Default to Near alignment
            _ => StringAlignment.Near
        };

        // Create the brush and automatically dispose it.
        using SolidBrush foreBrush = new(ForeColor);

        // Call the DrawString method to write text.
        // Text, Font, and ClientRectangle are inherited properties.
        pe.Graphics.DrawString(Text, Font, foreBrush, ClientRectangle, style);

        base.OnPaint(pe);
    }
}

Public Class FirstControl

    Private _textAlignment As HorizontalAlignment = HorizontalAlignment.Left

    <System.ComponentModel.Category("Alignment"),
    System.ComponentModel.Description("Specifies the alignment of text."),
    System.ComponentModel.DefaultValue(HorizontalAlignment.Left)>
    Public Property TextAlignment As HorizontalAlignment
        Get
            Return _textAlignment
        End Get

        Set(value As HorizontalAlignment)
            _textAlignment = value
            Invalidate()
        End Set
    End Property

    Protected Overrides Sub OnTextChanged(e As EventArgs)
        MyBase.OnTextChanged(e)
        Invalidate()
    End Sub

    Protected Overrides Sub OnPaint(ByVal e As System.Windows.Forms.PaintEventArgs)
        Dim style As New StringFormat

        'Map the HorizontalAlignment enum to the StringAlignment enum
        Select Case TextAlignment
            Case HorizontalAlignment.Left
                style.Alignment = StringAlignment.Near
            Case HorizontalAlignment.Right
                style.Alignment = StringAlignment.Far
            Case HorizontalAlignment.Center
                style.Alignment = StringAlignment.Center
        End Select

        'Create the brush and automatically dispose it.
        Using foreBrush As New SolidBrush(ForeColor)
            'Call the DrawString method to write text.
            'Text, Font, and ClientRectangle are inherited properties.
            e.Graphics.DrawString(Text, Font, foreBrush, ClientRectangle, style)
        End Using
        MyBase.OnPaint(e)
    End Sub

End Class

Partilhar via

Crie um controle personalizado simples

Adicionar um controle personalizado

Adicionar uma propriedade

Manipular texto modificado

Pintar o controle

Conteúdo relacionado

Recursos adicionais