Freigeben über


Erstellen eines Benutzersteuerelements (Windows Forms .NET)

In diesem Artikel erfahren Sie, wie Sie Ihrem Projekt ein Benutzersteuerelement hinzufügen und dieses anschließend einem Formular hinzufügen. Sie erstellen ein wiederverwendbares Benutzersteuerelement, das sowohl visuell ansprechend als auch funktional ist. Das neue Steuerelement gruppiert ein TextBox-Steuerelement mit einem Button-Steuerelement. Wenn die Schaltfläche ausgewählt wird, wird der Text im Textfeld gelöscht. Weitere Informationen zu Benutzersteuerelementen finden Sie in der Übersicht über Benutzersteuerelemente.

Hinzufügen eines Benutzersteuerelements zu einem Projekt

Öffnen Sie Ihr Windows Forms-Projekt in Visual Studio, und verwenden Sie dann die Visual Studio-Vorlagen, um ein Benutzersteuerelement zu erstellen:

  1. Suchen Sie in Visual Studio nach dem Fenster Projektmappen-Explorer. Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Hinzufügen>Benutzersteuerelement (Windows Forms) aus.

    Klicken Sie mit der rechten Maustaste auf den Visual Studio-Projektmappen-Explorer, um einem Windows Forms-Projekt ein Benutzersteuerelement hinzuzufügen.

  2. Legen Sie unter Name den Namen des Steuerelements auf ClearableTextBox fest, und wählen Sie Hinzufügen aus.

    Dialogfeld „Hinzufügen“ in Visual Studio für Windows Forms

Nachdem das Benutzersteuerelement erstellt wurde, öffnet Visual Studio den Designer:

Der Benutzersteuerelement-Designer in Visual Studio für Windows Forms

Entwerfen des löschbaren Textfelds

Das Benutzersteuerelement besteht aus konstituierenden Steuerelementen. Das sind die Steuerelemente, die Sie auf der Entwurfsoberfläche erstellen – genau wie beim Entwerfen eines Formulars. Führen Sie die folgenden Schritte aus, um das Benutzersteuerelement und die zugehörigen konstituierenden Steuerelemente hinzuzufügen und zu konfigurieren:

  1. Wenn der Designer geöffnet ist, sollte die Entwurfsoberfläche des Benutzersteuerelements das ausgewählte Objekt sein. Falls nicht, klicken Sie auf die Entwurfsoberfläche, um sie auszuwählen. Legen Sie im Fenster Eigenschaften die folgenden Eigenschaften fest:

    Eigenschaft Wert
    MinimumSize 84, 53
    Größe 191, 53
  2. Fügen Sie ein Label-Steuerelement hinzu. Legen Sie die folgenden Eigenschaften fest:

    Eigenschaften Wert
    Name lblTitle
    Standort 3, 5
  3. Fügen Sie ein TextBox-Steuerelement hinzu. Legen Sie die folgenden Eigenschaften fest:

    Eigenschaften Wert
    Name txtValue
    Anchor Top, Left, Right
    Standort 3, 23
    Größe 148, 23
  4. Fügen Sie ein Button-Steuerelement hinzu. Legen Sie die folgenden Eigenschaften fest:

    Eigenschaften Wert
    Name btnClear
    Anchor Top, Right
    Standort 157, 23
    Größe 31, 23
    Text

    Das Steuerelement sollte wie auf der folgenden Abbildung aussehen:

    Visual Studio mit Windows Forms mit dem soeben entworfenen Benutzersteuerelement.

  5. Drücken Sie F7, um den Code-Editor für die ClearableTextBox-Klasse zu öffnen.

  6. Führen Sie die folgenden Codeänderungen durch:

    1. Importieren Sie am Anfang der Codedatei den System.ComponentModel-Namespace.

    2. Fügen Sie der Klasse das DefaultEvent -Attribut hinzu. Dieses Attribut legt fest, welches Ereignis vom Consumer generiert wird, wenn im Designer auf das Steuerelement doppelgeklickt wird. Der Consumer ist das Objekt, das dieses Steuerelement deklariert und verwendet. Weitere Informationen zu Attributen finden Sie unter Attribute (C#) oder Attributübersicht (Visual Basic).

      using System.ComponentModel;
      
      namespace UserControlProject
      {
          [DefaultEvent(nameof(TextChanged))]
          public partial class ClearableTextBox : UserControl
      
      Imports System.ComponentModel
      
      <DefaultEvent("TextChanged")>
      Public Class ClearableTextBox
      
    3. Fügen Sie einen Ereignishandler hinzu, der das TextBox.TextChanged-Ereignis an den Consumer weiterleitet:

      [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
      

      Beachten Sie, dass für das Ereignis das Browsable-Attribut deklariert wird. Durch Anwenden von Browsable auf ein Ereignis oder auf eine Eigenschaft wird gesteuert, ob das Element im Fenster Eigenschaften sichtbar ist, wenn das Steuerelement im Designer ausgewählt wird. In diesem Fall wird true als Parameter an das Attribut übergeben, um anzugeben, dass das Ereignis sichtbar sein soll.

    4. Fügen Sie eine Zeichenfolgeneigenschaft namens Text hinzu, um die TextBox.Text-Eigenschaft an den Consumer weiterzuleiten:

      [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. Fügen Sie eine Zeichenfolgeneigenschaft namens Title hinzu, um die Label.Text-Eigenschaft an den Consumer weiterzuleiten:

      [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. Kehren Sie zum ClearableTextBox-Designer zurück, und doppelklicken Sie auf das btnClear-Steuerelement, um einen Handler für das Click-Ereignis zu generieren. Fügen Sie den folgenden Code für den Handler hinzu, damit das txtValue-Textfeld gelöscht wird:

    private void btnClear_Click(object sender, EventArgs e) =>
        Text = "";
    
    Private Sub btnClear_Click(sender As Object, e As EventArgs)
        txtValue.Text = ""
    End Sub
    
  8. Erstellen Sie abschließend das Projekt, indem Sie im Fenster Projektmappen-Explorer mit der rechten Maustaste auf das Projekt klicken und Erstellen auswählen. Es sollten keine Fehler auftreten. Nach Abschluss der Erstellung wird das ClearableTextBox-Steuerelement in der Toolbox angezeigt und kann verwendet werden.

Im nächsten Schritt wird das Steuerelement in einem Formular verwendet.

Beispielanwendung

Wenn Sie im letzten Abschnitt ein neues Projekt erstellt haben, verfügen Sie über ein leeres Form-Element mit dem Namen Form1. Falls nicht, erstellen Sie ein neues Formular.

  1. Doppelklicken Sie im Fenster Projektmappen-Explorer auf das Formular, um den Designer zu öffnen. Die Entwurfsoberfläche des Formulars sollte ausgewählt sein.

  2. Legen Sie die Size-Eigenschaft des Formulars auf 432, 315 fest.

  3. Öffnen Sie das Fenster Toolbox, und doppelklicken Sie auf das Steuerelement ClearableTextBox. Dieses Steuerelement sollte unter einem nach Ihrem Projekt benannten Abschnitt aufgeführt sein.

  4. Doppelklicken Sie erneut auf das Steuerelement ClearableTextBox, um ein zweites Steuerelement zu generieren.

  5. Kehren Sie zum Designer zurück, und trennen Sie die Steuerelemente, sodass Sie beide sehen können.

  6. Wählen Sie eines der Steuerelemente aus, und legen Sie die folgenden Eigenschaften fest:

    Eigenschaft Wert
    Name ctlFirstName
    Standort 12, 12
    Größe 191, 53
    Titel First Name
  7. Wählen Sie das andere Steuerelement aus, und legen Sie die folgenden Eigenschaften fest:

    Eigenschaft Wert
    Name ctlLastName
    Standort 12, 71
    Größe 191, 53
    Titel Last Name
  8. Fügen Sie dem Formular im Fenster Toolbox ein Label-Steuerelement hinzu, und legen Sie die folgenden Eigenschaften fest:

    Eigenschaft Wert
    Name lblFullName
    Standort 12, 252
  9. Als Nächstes müssen die Ereignishandler für die beiden Benutzersteuerelemente generiert werden. Doppelklicken Sie im Designer auf das ctlFirstName-Steuerelement. Dadurch wird der Ereignishandler für das TextChanged-Ereignis generiert und der Code-Editor geöffnet.

  10. Kehren Sie zum Designer zurück, und doppelklicken Sie auf das ctlLastName-Steuerelement, um den zweiten Ereignishandler zu generieren.

  11. Kehren Sie zum Designer zurück, und doppelklicken Sie auf die Titelleiste des Formulars. Dadurch wird ein Ereignishandler für das Load-Ereignis generiert.

  12. Fügen Sie im Code-Editor eine Methode mit dem Namen UpdateNameLabel hinzu. Diese Methode kombiniert beide Namen für die Erstellung einer Nachricht und weist die Nachricht dem lblFullName-Steuerelement zu.

    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. Rufen Sie für beide TextChanged-Ereignishandler die UpdateNameLabel-Methode auf:

    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. Rufen Sie abschließend die UpdateNameLabel-Methode über das Load-Ereignis des Formulars auf:

    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
    

Führen Sie das Projekt aus, und geben Sie einen Vornamen und einen Nachnamen ein:

Eine Windows Forms-App mit zwei Textfeldern, die aus Benutzersteuerelementen erstellt wurden, und eine Bezeichnung.

Wählen Sie die Schaltfläche aus, um eines der Textfelder zurückzusetzen.