Creación de un control de usuario (Windows Forms .NET)

En este artículo se explica cómo agregar un control de usuario al proyecto y, después, agregar ese control de usuario a un formulario. Creará un control de usuario reutilizable que sea visualmente atractivo y funcional. El nuevo control agrupa un control TextBox con un control Button. Cuando el usuario selecciona el botón, se borra el texto del cuadro de texto. Para obtener más información sobre los controles de usuario, consulte Información general sobre el control de usuario.

Importante

La documentación de la guía de escritorio para .NET 7 y .NET 6 está en proceso de elaboración.

Adición de un control de usuario al proyecto

Después de abrir el proyecto de Windows Forms en Visual Studio, use las plantillas de Visual Studio para crear un control de usuario:

1. En Visual Studio, busque la ventana Explorador de proyectos. Haga clic con el botón derecho en el proyecto y seleccione Agregar>Control de usuario (Windows Forms).

   

2. Establezca el Nombre del control en ClearableTextBox y haga clic en Agregar.

   

Una vez creado el control de usuario, Visual Studio abre el diseñador:

Diseño del cuadro de texto que se puede borrar

El control de usuario se compone de controles constituyentes, que son los controles que crea en la superficie de diseño, igual que cuando diseña un formulario. Siga estos pasos para agregar y configurar el control de usuario y sus controles constituyentes:

1. Con el diseñador abierto, la superficie de diseño del control de usuario debe ser el objeto seleccionado. Si no es así, haga clic en la superficie de diseño para seleccionarla. Establezca las siguientes propiedades en la ventana Propiedades:

   Propiedad	Valor
   MinimumSize	84, 53
   Size	191, 53

2. Agregue un control Label. Establezca las siguientes propiedades:

   Property	Valor
   Nombre	lblTitle
   Ubicación	3, 5

3. Agregue un control TextBox. Establezca las siguientes propiedades:

   Property	Valor
   Nombre	txtValue
   Delimitador	Top, Left, Right
   Ubicación	3, 23
   Tamaño	148, 23

4. Agregue un control Button. Establezca las siguientes propiedades:

   Property	Valor
   Nombre	btnClear
   Delimitador	Top, Right
   Ubicación	157, 23
   Tamaño	31, 23
   Texto	↻

   El control debe tener un aspecto similar al de la siguiente imagen:

   

5. Presione F7 para abrir el editor de código de la clase ClearableTextBox.

6. Realice los siguientes cambios en el código:

   1. En la parte superior del archivo de código, importe el espacio de nombres System.ComponentModel.

   2. Agregue el atributo DefaultEvent a la clase. Este atributo establece el evento generado por el consumidor cuando se hace doble clic en el control en el diseñador. El consumidor es el objeto que declara y usa este control.

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

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

   3. Agregue un controlador de eventos que reenvíe el evento TextBox.TextChanged al consumidor:

      [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 el evento incluye el atributo Browsable declarado. Cuando el atributo Browsable se aplica a un evento o propiedad, controla si el elemento está visible o no en la ventana Propiedades cuando se selecciona el control en el diseñador. En este caso, true se pasa como un parámetro al atributo para indicar que el evento debe estar visible.

   4. Agregue una propiedad de cadena denominada Text, la cual reenvía la propiedad TextBox.Text al consumidor:

      [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. Agregue una propiedad de cadena denominada Title, la cual reenvía la propiedad Label.Text al consumidor:

      [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. Vuelva al diseñador de ClearableTextBox y haga doble clic en el control btnClear para generar un controlador para el evento Click. Agregue el código siguiente para el controlador, que borra el cuadro 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. Por último, compile el proyecto haciendo clic en él con el botón derecho desde la ventana Explorador de soluciones y seleccionando Compilar. No debería haber errores y, una vez finalizada la compilación, el control ClearableTextBox debería aparecer en el cuadro de herramientas para su uso.

El siguiente paso consiste en usar el control en un formulario.

Aplicación de ejemplo

Si ha creado un nuevo proyecto en la última sección, tiene un formulario (Form) en blanco denominado Form1, de lo contrario, cree un nuevo formulario.

1. En la ventana Explorador de soluciones, haga doble clic en el formulario para abrir el diseñador. Se debe seleccionar la superficie de diseño del formulario.

2. Establezca la propiedad Size del formulario en 432, 315.

3. Abra la ventana Cuadro de herramientas y haga doble clic en el control ClearableTextBox. Este control debería aparecer en una sección denominada igual que el proyecto.

4. De nuevo, haga doble clic en el control ClearableTextBox para generar un segundo control.

5. Vuelva al diseñador y separe los controles para que pueda ver ambos.

6. Seleccione un control y establezca las siguientes propiedades:

   Propiedad	Valor
   Nombre	ctlFirstName
   Ubicación	12, 12
   Tamaño	191, 53
   Título	First Name

7. Seleccione el otro control y establezca las siguientes propiedades:

   Propiedad	Valor
   Nombre	ctlLastName
   Ubicación	12, 71
   Tamaño	191, 53
   Título	Last Name

8. Vuelva a la ventana Cuadro de herramientas, agregue un control de etiqueta al formulario y establezca las siguientes propiedades:

   Propiedad	Valor
   Nombre	lblFullName
   Ubicación	12, 252

9. Después, debe generar los controladores de eventos para los dos controles de usuario. En el diseñador, haga doble clic en el control ctlFirstName. Esta acción genera el controlador de eventos para el evento TextChanged y abre el editor de código.

10. Vuelva al diseñador y haga doble clic en el control ctlLastName para generar el segundo controlador de eventos.

11. Vuelva al diseñador y haga doble clic en la barra de título del formulario. Esta acción genera un controlador de eventos para el evento Load.

12. En el editor de código, agregue un método denominado UpdateNameLabel. Este método combina ambos nombres para crear un mensaje y asigna el mensaje al control 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 controladores de eventos TextChanged, llame al 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 último, llame al método UpdateNameLabel desde el evento Load del formulario:

    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
    

Ejecute el proyecto y escriba un nombre y un apellido:

Presione el botón ↻ para restablecer uno de los cuadros de texto.