Propiedades en tiempo de diseño para controles personalizados

En este artículo se explica cómo se controlan las propiedades de los controles en el Diseñador visual de Windows Forms en Visual Studio.

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

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

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

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 ventana Propiedades 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, consulte Atributos (C#) o Información general sobre los atributos (Visual Basic).

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

<Browsable(False)>
<DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)>
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 a 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 configurar 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 Age propiedad, los métodos se denominan ResetAge y ShouldSerializeAge.

Importante

Aplique la propiedad a DefaultValueAttribute, o proporcione tanto los métodos Reset<PropertyName> como ShouldSerialize<PropertyName>. No combine las dos formas de definir el valor predeterminado.

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 DefaultValueAttribute atributo y el valor de la propiedad no coincide con el valor del atributo.
• La clase de la propiedad define un método Reset<PropertyName> sin un ShouldSerialize<PropertyName>.
• La clase de la propiedad define un Reset<PropertyName> método y devuelve ShouldSerialize<PropertyName> 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 ventana Propiedades .

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 Reset<PropertyName> métodos y ShouldSerialize<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 un 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 Reset<PropertyName> método . La opción de menú contextual Restablecer está habilitada o deshabilitada según lo que devuelve el método ShouldSerialize<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 es devuelto, la opción de menú contextual Restablecer está deshabilitada y se elimina el código de configuración de propiedades del código subyacente.

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 ResetDirection métodos 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 de datos suelen convertir un tipo a otro, también proporcionan conversiones de cadenas a valores para la cuadrícula de propiedades y otros controles durante el 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 System.ComponentModel espacio de nombres 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 ventana Propiedades 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 tipográficos

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 DateTime tipo usa una lista desplegable de calendarios.

Importante

Los editores de tipos personalizados han cambiado desde .NET Framework. Para obtener más información, vea Cambios en el diseñador desde .NET Framework.