Propiedades en tiempo de diseño para controles personalizados (Windows Forms .NET)

En este artículo se explica cómo se controlan las propiedades de los controles en Windows Forms Designer en Visual Studio.

Cada control hereda muchas propiedades de la clase base System.Windows.Forms.Control, como:

• Enabled
• Font
• ForeColor
• Focused
• Visible
• Width

Al crear un control, puede definir nuevas propiedades y controlar cómo aparecen en el diseñador.

Importante

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

Definición de una propiedad

Cualquier propiedad pública con un descriptor de acceso get definido por un control se puede ver automáticamente en la ventana Propiedades de Visual Studio. Si la propiedad también define un descriptor de acceso set, la propiedad se puede cambiar en la ventana Propiedades. Sin embargo, las propiedades se pueden mostrar o ocultar explícitamente en la ventanaPropiedades aplicando BrowsableAttribute. Este atributo toma un único parámetro booleano para indicar si se muestra o no. Para obtener más información sobre los atributos, vea Atributos (C#) o Información general sobre los atributos (Visual Basic).

[Browsable(false)]
public bool IsSelected { get; set; }

<Browsable(False)>
Public Property IsSelected As Boolean

[NOTA] Las propiedades complejas que no se pueden convertir implícitamente a y desde una cadena requieren un convertidor de tipos.

Propiedades serializadas

Las propiedades establecidas en un control se serializan en el archivo de código subyacente del diseñador. Esto sucede cuando el valor de una propiedad se establece en algo distinto de su valor predeterminado.

Cuando el diseñador detecta un cambio en una propiedad, evalúa todas las propiedades del control y serializa cualquier propiedad cuyo valor no coincida con el valor predeterminado de la propiedad. El valor de una propiedad se serializa en el archivo code-behid del diseñador. Los valores predeterminados ayudan al diseñador a determinar qué valores de propiedad se deben serializar.

Valores predeterminados

Se considera que una propiedad tiene un valor predeterminado cuando aplica el atributo DefaultValueAttribute o la clase de la propiedad contiene métodos específicos Reset y ShouldSerialize de la propiedad. Para obtener más información sobre los atributos, consulte Atributos (C#) o Información general sobre los atributos (Visual Basic).

Al establecer un valor predeterminado, habilite lo siguiente:

• La propiedad proporciona una indicación visual en la ventana Propiedades si se ha modificado a partir de su valor predeterminado.
• El usuario puede hacer clic con el botón derecho en la propiedad y elegir Restablecer para restaurar la propiedad a su valor predeterminado.
• El diseñador genera código más eficaz.

Si una propiedad usa un tipo simple, como un tipo primitivo, el valor predeterminado se puede establecer aplicando DefaultValueAttribute la propiedad. Sin embargo, las propiedades con este atributo no comienzan automáticamente con ese valor asignado. Debe establecer el campo de respaldo de la propiedad en el mismo valor predeterminado. Puede establecer la propiedad en la declaración o en el constructor de la clase.

Cuando una propiedad es un tipo complejo o desea controlar el comportamiento de restablecimiento y serialización del diseñador, defina los métodos Reset<PropertyName> y ShouldSerialize<PropertyName> en la clase. Por ejemplo, si el control define una propiedad Age, los métodos se denominan ResetAge y ShouldSerializeAge.

Importante

Aplique a DefaultValueAttribute la propiedad o proporcione ambos métodos Reset<PropertyName> y ShouldSerialize<PropertyName>. No use ambos.

Las propiedades se pueden "restablecer" a sus valores predeterminados a través de la ventana Propiedades haciendo clic con el botón derecho en el nombre de la propiedad y seleccionando Restablecer.

La disponibilidad de la opción de menú contextual Propiedades>haga clic con el botón derecho en>Restablecer se habilita cuando:

• La propiedad tiene aplicado el atributoDefaultValueAttribute y el valor de la propiedad no coincide con el valor del atributo.
• La clase de la propiedad define un métodoReset<PropertyName> sin un ShouldSerialize<PropertyName>.
• La clase de la propiedad define un método Reset<PropertyName> y ShouldSerialize<PropertyName> devuelve true.

DefaultValueAttribute

Si el valor de una propiedad no coincide con el valor proporcionado por DefaultValueAttribute, la propiedad se considera modificada y se puede restablecer a través de la ventanaPropiedades.

Importante

Este atributo no se debe usar en propiedades que tengan métodos correspondientes Reset<PropertyName> y ShouldSerialize<PropertyName>.

El código siguiente declara dos propiedades, una enumeración con un valor predeterminado de North y un entero con un valor predeterminado de 10.

[DefaultValue(typeof(Directions), "North")]
public Directions PointerDirection { get; set; } = Directions.North;

[DefaultValue(10)]
public int DistanceInFeet { get; set; } = 10;

<DefaultValue(GetType(Directions), "North")>
Public Property PointerDirection As Directions = Directions.North

<DefaultValue(10)>
Public Property DistanceInFeet As Integer = 10

Restablecer y ShouldSerialize

Como se mencionó anteriormente, los métodos Reset<PropertyName> yShouldSerialize<PropertyName> proporcionan la oportunidad de guiar no solo el comportamiento de restablecimiento de una propiedad, sino también para determinar si se cambia un valor y se deben serializar en el archivo de código subyacente del diseñador. Ambos métodos funcionan juntos y no debe definir uno sin el otro.

Importante

Los métodos Reset<PropertyName> y ShouldSerialize<PropertyName> no se deben crear para una propiedad que tenga DefaultValueAttribute.

Cuando Reset<PropertyName> se define, la ventana Propiedades muestra una opción de menú contextual Restablecer para esa propiedad. Cuando se selecciona Restablecer, se invoca el método Reset<PropertyName>. La opción de menú contextual Restablecer está habilitada o deshabilitada por lo que devuelve el métodoShouldSerialize<PropertyName>. Cuando ShouldSerialize<PropertyName> devuelve true, indica que la propiedad ha cambiado de su valor predeterminado y se debe serializar en el archivo de código subyacente y habilita la opción de menú contextual Restablecer. Cuando false se devuelve, la opción de menú contextual Restablecer está deshabilitada y el código subyacente tiene quitado el código del conjunto de propiedades.

Sugerencia

Ambos métodos pueden y deben definirse con ámbito privado para que no componen la API pública del control.

El fragmento de código siguiente declara una propiedad denominada Direction. El comportamiento del diseñador de esta propiedad se controla mediante los métodos ResetDirection y ShouldSerializeDirection.

public Directions Direction { get; set; } = Directions.None;

private void ResetDirection() =>
    Direction = Directions.None;

private bool ShouldSerializeDirection() =>
    Direction != Directions.None;

Public Property Direction As Directions = Directions.None

Private Sub ResetDirection()
    Direction = Directions.None
End Sub

Private Function ShouldSerializeDirection() As Boolean
    Return Direction <> Directions.None
End Function

Convertidores de tipos

Aunque los convertidores de tipos suelen convertir un tipo a otro, también proporcionan conversión de cadena a valor para la cuadrícula de propiedades y otros controles en tiempo de diseño. La conversión de cadena a valor permite representar propiedades complejas en estos controles en tiempo de diseño.

La mayoría de los tipos de datos integrados (números, enumeraciones y otros) tienen convertidores de tipos predeterminados que proporcionan conversiones de cadena a valor y realizan comprobaciones de validación. Los convertidores de tipos predeterminados están en el espacio de nombresSystem.ComponentModel y se denominan después del tipo que se va a convertir. Los nombres de tipo de convertidor usan el siguiente formato: {type name}Converter. Por ejemplo, StringConverter, TimeSpanConverter y Int32Converter.

Los convertidores de tipos se usan ampliamente en tiempo de diseño con la ventana Propiedades. Un convertidor de tipos se puede aplicar a una propiedad o a un tipo mediante TypeConverterAttribute.

La ventanaPropiedades usa convertidores para mostrar la propiedad como un valor de cadena cuando TypeConverterAttribute se declara en la propiedad. Cuando TypeConverterAttribute se declara en un tipo, la ventana Propiedades usa el convertidor en cada propiedad de ese tipo. El convertidor de tipos también ayuda a serializar el valor de propiedad en el archivo de código subyacente del diseñador.

Editores de tipos

La ventana Propiedades usa automáticamente un editor de tipos para una propiedad cuando el tipo de la propiedad es un tipo integrado o conocido. Por ejemplo, un valor booleano se edita como un cuadro combinado con valores True y False y el tipo DateTime usa una lista desplegable de calendarios.

Importante

Los editores de tipos personalizados han cambiado desde .NET Framework. Para obtener más información, consulte El diseñador cambia desde .NET Framework (Windows Forms .NET).