Come creare un controllo utente

Questo articolo illustra come aggiungere un controllo utente al progetto e quindi aggiungere tale controllo utente a un modulo. Si creerà un controllo utente riutilizzabile che sia visivamente accattivante che funzionale. Il nuovo gruppo di controllo raggruppa un controllo TextBox con un controllo Button. Quando l'utente seleziona il pulsante, il testo nella casella di testo viene cancellato. Per altre informazioni sui controlli utente, vedere Panoramica del controllo utente.

Comprensione dei consumatori di controllo dell'utente

In questo articolo, il termine consumer fa riferimento a qualsiasi codice che usa il controllo utente. Sono inclusi:

• Moduli che contengono il tuo controllo utente.
• Altri controlli che ospitano il controllo utente.
• Applicazioni che fanno riferimento alla libreria di controlli utente.

Quando si crea un controllo utente, si sta creando un componente riutilizzabile. Chi utilizza il componente lo fa collocandolo in un modulo, impostandone le proprietà o reagendo ai suoi eventi. Il consumer non deve conoscere i controlli interni (ad esempio TextBox e Button) che costituiscono il controllo utente, ma interagiscono solo con le proprietà e gli eventi che si sceglie di esporre.

Modello di codice essenziale per i controlli utente

Prima di aggiungere l'implementazione dettagliata, è utile comprendere il modello di codice minimo praticabile per un controllo utente. Fondamentalmente, un controllo dell'utente deve:

• Inoltro di eventi: passa eventi dai controlli interni al consumer.
• Esposizione delle proprietà : consente all'utente di accedere alle proprietà del controllo interno.
• Comportamento logico : gestire le interazioni tra i controlli interni.

Il codice seguente illustra questi modelli. Non è necessario tutto questo codice per un controllo utente di base, ma questi modelli consentono di creare un componente professionale riutilizzabile che si integra bene con la finestra di progettazione e le applicazioni consumer.

Aggiungere un nuovo controllo utente

Dopo aver aperto il progetto Windows Form in Visual Studio, usare i modelli di Visual Studio per creare un controllo utente:

1. In Visual Studio trovare la finestra Esplora soluzioni . Fare clic con il pulsante destro del mouse sul progetto e scegliere Aggiungi>controllo utente (Windows Form).

   

2. Impostare Il nome del controllo su ClearableTextBox e premere Aggiungi.

   

Dopo aver creato il controllo utente, Visual Studio apre la finestra di progettazione:

Progettare la casella di testo cancellabile

Il controllo utente è costituito da controlli costitutivi, che sono i controlli creati nell'area di progettazione, proprio come si progetta un modulo. Seguire questa procedura per aggiungere e configurare il controllo utente e i relativi controlli costitutivi:

1. Con la finestra di progettazione aperta, l'area di progettazione del controllo utente deve essere l'oggetto selezionato. In caso contrario, clicca sull'area di progettazione per selezionarla. Impostare le proprietà seguenti nella finestra Proprietà :

   Proprietà	Valore
   Misura Minima	84, 53
   Misura	191, 53

2. Aggiungere un Label controllo. Impostare le proprietà seguenti:

   Proprietà	Valore
   Nome	lblTitle
   Posizione	3, 5

3. Aggiungere un TextBox controllo. Impostare le proprietà seguenti:

   Proprietà	Valore
   Nome	txtValue
   Ancoraggio	Top, Left, Right
   Posizione	3, 23
   Misura	148, 23

4. Aggiungere un Button controllo. Impostare le proprietà seguenti:

   Proprietà	Valore
   Nome	btnClear
   Ancoraggio	Top, Right
   Posizione	157, 23
   Misura	31, 23
   Testo	↻

   Il controllo dovrebbe essere simile all'immagine seguente:

   

5. Premere F7 per aprire l'editor di codice per la ClearableTextBox classe .

6. Apportare le modifiche di codice seguenti:

   1. All'inizio del file di codice, importa lo spazio dei nomi System.ComponentModel.

   2. Aggiungere l'attributo DefaultEvent alla classe. Questo attributo imposta l'evento generato quando il consumer (modulo o applicazione che utilizza questo controllo) fa doppio clic sul controllo nella finestra di progettazione. Per altre informazioni sugli attributi, vedere Cenni preliminari sugli attributi (C#) o attributi (Visual Basic).

      using System.ComponentModel;
      
      namespace UserControlProject
      {
          [DefaultEvent(nameof(TextChanged))]
          public partial class ClearableTextBox : UserControl
      

      Imports System.ComponentModel
      
      <DefaultEvent("TextChanged")>
      Public Class ClearableTextBox
      

   3. Aggiungere un gestore eventi che inoltra l'evento TextBox.TextChanged ai consumatori del controllo utente.

      [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
      

      Si noti che l'evento ha l'attributo Browsable dichiarato. Quando l'oggetto Browsable viene applicato a un evento o a una proprietà, controlla se l'elemento è visibile nella finestra Proprietà quando il controllo viene selezionato nella finestra di progettazione. In questo caso, true viene passato come parametro all'attributo che indica che l'evento deve essere visibile.

   4. Aggiungere una proprietà stringa denominata Text, che espone la proprietà TextBox.Text agli utenti del controllo utente.

      [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. Aggiungere una proprietà stringa denominata Title, che espone la proprietà Label.Text agli utenti del controllo utente.

      [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. Tornare alla ClearableTextBox finestra di progettazione e fare doppio clic sul btnClear controllo per generare un gestore per l'evento Click . Aggiungere il codice seguente per il gestore, che cancella la txtValue casella di testo:

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

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

8. Compilare infine il progetto facendo clic con il pulsante destro del mouse sul progetto nella finestra Esplora soluzioni e scegliendo Compila. Non dovrebbero essere presenti errori e, al termine della compilazione, il ClearableTextBox controllo viene visualizzato nella casella degli strumenti per l'uso.

Il passaggio successivo consiste nell'usare il controllo in un modulo.

Applicazione di esempio

Se hai creato un nuovo progetto nell'ultima sezione, avrai un Form vuoto denominato Form1, altrimenti, crea un nuovo modulo.

1. Nella finestra Esplora soluzioni fare doppio clic sul modulo per aprire la finestra di progettazione. È necessario selezionare l'area di progettazione del modulo.

2. Impostare la proprietà Size del modulo su 432, 315.

3. Aprire la finestra casella degli strumenti e fare doppio clic sul controllo ClearableTextBox . Questo controllo deve essere elencato in una sezione che porta il nome del tuo progetto.

4. Anche in questo caso, fare doppio clic sul controllo ClearableTextBox per generare un secondo controllo.

5. Torna al progettista e separa i controlli in modo da poterli vedere entrambi.

6. Selezionare un controllo e impostare le proprietà seguenti:

   Proprietà	Valore
   Nome	ctlFirstName
   Posizione	12, 12
   Misura	191, 53
   Titolo	First Name

7. Selezionare l'altro controllo e impostare le proprietà seguenti:

   Proprietà	Valore
   Nome	ctlLastName
   Posizione	12, 71
   Misura	191, 53
   Titolo	Last Name

8. Nella finestra Toolbox, aggiungere un controllo etichetta al modulo e impostare le proprietà seguenti:

   Proprietà	Valore
   Nome	lblFullName
   Posizione	12, 252

9. Successivamente, è necessario generare i gestori eventi per i due controlli utente. Nella finestra di progettazione, fare doppio clic sul controllo ctlFirstName. Questa azione genera il gestore eventi per l'evento TextChanged e apre l'editor di codice.

10. Tornare alla finestra di progettazione e fare doppio clic sul ctlLastName controllo per generare il secondo gestore eventi.

11. Passare di nuovo alla finestra di progettazione e fare doppio clic sulla barra del titolo del modulo. Questa azione genera un gestore eventi per l'evento Load .

12. Nell'editor di codice aggiungere un metodo denominato UpdateNameLabel. Questo metodo combina entrambi i nomi per creare un messaggio e assegna il messaggio al lblFullName controllo .

    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. Per entrambi i gestori di eventi TextChanged, chiamare il metodo 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. Chiamare infine il metodo UpdateNameLabel dall'evento Load del modulo:

    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
    

Eseguire il progetto e immettere un nome e un cognome:

Provare a premere il pulsante ↻ per reimpostare una delle caselle di testo.