Freigeben über

Entwurfszeiteigenschaften für benutzerdefinierte Steuerelemente

In diesem Artikel erfahren Sie, wie Eigenschaften für Steuerelemente im Windows Forms Visual Designer in Visual Studio behandelt werden.

Jedes Steuerelement erbt viele Eigenschaften von der Basisklasse System.Windows.Forms.Control, z. B.:

Beim Erstellen eines Steuerelements können Sie neue Eigenschaften definieren und steuern, wie sie im Designer angezeigt werden.

Definieren einer Eigenschaft

Alle öffentlichen Eigenschaften, deren Get-Accessor von einem Steuerelement definiert wird, sind automatisch im Eigenschaftenfenster von Visual Studio sichtbar. Wenn die Eigenschaft auch einen Set-Accessor definiert, kann die Eigenschaft im Eigenschaftenfenster geändert werden. Eigenschaften können jedoch explizit im Eigenschaftenfenster angezeigt oder ausgeblendet werden, indem BrowsableAttribute angewendet wird. Dieses Attribut verwendet einen einzelnen booleschen Parameter, um anzugeben, ob er angezeigt wird. Weitere Informationen zu Attributen finden Sie unter Attribute (C#) oder Attributübersicht (Visual Basic).

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

<Browsable(False)>
<DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)>
Public Property IsSelected As Boolean

Hinweis

Komplexe Eigenschaften, die nicht implizit in und aus einer Zeichenfolge konvertiert werden können, erfordern einen Typkonverter.

Serialisierte Eigenschaften

Eigenschaften, die für ein Steuerelement festgelegt sind, werden in die CodeBehind-Datei des Designers serialisiert. Dies geschieht, wenn der Wert einer Eigenschaft auf einen anderen Wert als den Standardwert festgelegt wird.

Wenn der Designer eine Änderung an einer Eigenschaft erkennt, wertet er alle Eigenschaften für das Steuerelement aus und serialisiert alle Eigenschaften, deren Wert nicht mit dem Standardwert für die Eigenschaft übereinstimmt. Der Wert einer Eigenschaft wird in die Codebehid-Datei des Designers serialisiert. Standardwerte helfen dem Designer, zu bestimmen, welche Eigenschaftswerte serialisiert werden sollen.

Standardwerte

Eine Eigenschaft wird als Standardwert betrachtet, wenn sie entweder das DefaultValueAttribute-Attribut anwendet oder die Klasse der Eigenschaft eigenschaftsspezifische Reset- und ShouldSerialize-Methoden enthält. Weitere Informationen zu Attributen finden Sie unter Attribute (C#) oder Attributübersicht (Visual Basic).

Durch Festlegen eines Standardwerts aktivieren Sie Folgendes:

  • Die Eigenschaft stellt visuelle Hinweise im Eigenschaftenfenster bereit, wenn sie vom Standardwert geändert wurde.
  • Die benutzende Person kann mit der rechten Maustaste auf die Eigenschaft klicken und Zurücksetzen auswählen, um die Eigenschaft auf ihren Standardwert zurückzusetzen.
  • Der Designer generiert effizienteren Code.

Wenn eine Eigenschaft einen einfachen Typ verwendet, z. B. einen Grundtyp, kann der Standardwert durch Anwenden der DefaultValueAttribute Eigenschaft festgelegt werden. Eigenschaften mit diesem Attribut beginnen jedoch nicht automatisch mit diesem zugewiesenen Wert. Sie müssen das Datenfeld der Eigenschaft auf denselben Standardwert setzen. Sie können eine Eigenschaft bei der Deklaration oder im Konstruktor der Klasse festlegen.

Wenn es sich bei einer Eigenschaft um einen komplexen Typ handelt oder Sie das Zurücksetzungs- und Serialisierungsverhalten des Designers steuern möchten, definieren Sie die Reset<PropertyName> Methoden und ShouldSerialize<PropertyName> Methoden für die Klasse. Wenn das Steuerelement beispielsweise eine Age Eigenschaft definiert, werden die Methoden benannt ResetAge und ShouldSerializeAge.

Von Bedeutung

Wenden Sie entweder die DefaultValueAttribute-Eigenschaft an, oder stellen Sie die Methoden Reset<PropertyName> und ShouldSerialize<PropertyName> bereit. Kombinieren Sie nicht die beiden Methoden zum Definieren des Standardwerts.

Eigenschaften können über das Eigenschaftenfenster auf ihre Standardwerte zurückgesetzt werden, indem Sie mit der rechten Maustaste auf den Eigenschaftennamen klicken und "Zurücksetzen" auswählen.

Das Kontextmenüelement

Die Verfügbarkeit der 'Eigenschaften'>Rechtsklick>'Zurücksetzen'-Option im Kontextmenü ist aktiviert, wenn:

  • Die Eigenschaft hat das DefaultValueAttribute Attribut angewendet, und der Wert der Eigenschaft stimmt nicht mit dem Wert des Attributs überein.
  • Die Eigenschaftsklasse definiert eine Reset<PropertyName> Methode ohne eine ShouldSerialize<PropertyName>.
  • Die Eigenschaftsklasse definiert eine Reset<PropertyName> Methode und gibt ShouldSerialize<PropertyName> "true" zurück.

Standardwert-Attribut

Wenn der Wert einer Eigenschaft nicht mit dem von ihnen bereitgestellten DefaultValueAttributeWert übereinstimmt, wird die Eigenschaft als geändert betrachtet und kann über das Eigenschaftenfenster zurückgesetzt werden.

Von Bedeutung

Dieses Attribut sollte nicht für Eigenschaften verwendet werden, die über entsprechende Reset<PropertyName> und ShouldSerialize<PropertyName> Methoden verfügen.

Der folgende Code deklariert zwei Eigenschaften, eine Aufzählung mit einem Standardwert von North und eine ganze Zahl mit dem Standardwert 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

Zurücksetzen und ShouldSerialize

Wie bereits erwähnt, bieten die Methoden Reset<PropertyName> und ShouldSerialize<PropertyName> die Möglichkeit, nicht nur das Zurücksetzungsverhalten einer Eigenschaft zu leiten, sondern auch zu bestimmen, ob ein Wert geändert wird und in die Code-Behind-Datei des Designers serialisiert werden soll. Beide Methoden arbeiten zusammen, und Sie sollten eins nicht ohne den anderen definieren.

Von Bedeutung

Die Reset<PropertyName>- und ShouldSerialize<PropertyName>-Methoden sollten nicht für eine Eigenschaft erstellt werden, die über eine DefaultValueAttribute verfügt.

Wenn Reset<PropertyName> definiert ist, zeigt das Eigenschaftenfenster eine Kontextmenüoption Zurücksetzen für diese Eigenschaft an. Wenn "Zurücksetzen" ausgewählt ist, wird die Reset<PropertyName> Methode aufgerufen. Die Option Zurücksetzen im Kontextmenü wird durch das, was von der ShouldSerialize<PropertyName> Methode zurückgegeben wird, aktiviert oder deaktiviert. Wenn ShouldSerialize<PropertyName>true zurückkehrt, bedeutet dies, dass sich die Eigenschaft von ihrem Standardwert geändert hat und in die Code-Behind-Datei serialisiert werden soll, was die Kontextmenüoption Zurücksetzen verfügbar macht. Wenn false zurückgegeben wird, ist die Option "Zurücksetzen" im Kontextmenü deaktiviert, und der CodeBehind hat den Eigenschafteneinstellungscode entfernt.

Tipp

Beide Methoden können und sollten mit privatem Bereich definiert werden, sodass sie nicht aus der öffentlichen API des Steuerelements bestehen.

Der folgende Codeausschnitt deklariert eine Eigenschaft mit dem Namen Direction. Das Designerverhalten dieser Eigenschaft wird durch die ResetDirection- und ShouldSerializeDirection-Methoden gesteuert.

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

Typumwandler

Während Typkonverter in der Regel einen Typ in einen anderen konvertieren, stellen sie auch Zeichenfolge-zu-Wert-Konvertierung für das Eigenschaftenraster und andere Entwurfszeitsteuerelemente bereit. Die Konvertierung von Zeichenfolgen zu Werten ermöglicht die Darstellung komplexer Eigenschaften in diesen Entwurfszeitsteuerelementen.

Die meisten integrierten Datentypen (Zahlen, Enumerationen und andere) verfügen über Standardtypkonverter, die Zeichenfolgen-zu-Wert-Konvertierungen bereitstellen und Überprüfungen durchführen. Die Standardtypkonverter befinden sich im System.ComponentModel Namespace und werden nach dem typ benannt, der konvertiert wird. Die Konvertertypnamen verwenden das folgende Format: {type name}Converter. Beispiel: StringConverter, TimeSpanConverter und Int32Converter.

Typkonverter werden während der Entwurfsphase häufig mit dem Eigenschaftenfenster verwendet. Ein Typkonverter kann mithilfe von TypeConverterAttribute auf eine Eigenschaft oder einen Typ angewendet werden.

Das Eigenschaftenfenster verwendet Konverter, um die Eigenschaft als Zeichenfolgenwert anzuzeigen, wenn die TypeConverterAttribute Eigenschaft für die Eigenschaft deklariert wird. Wenn die Eigenschaft TypeConverterAttribute für einen Typ deklariert wird, verwendet das Eigenschaftenfenster den Konverter für jede Eigenschaft dieses Typs. Der Typkonverter hilft auch beim Serialisieren des Eigenschaftswerts in der Code-Behind-Datei des Designers.

Typ-Editoren

Das Eigenschaftenfenster verwendet automatisch einen Typ-Editor für eine Eigenschaft, wenn der Typ der Eigenschaft ein integrierter oder bekannter Typ ist. Beispielsweise wird ein boolescher Wert als Kombinationsfeld mit True - und False-Werten bearbeitet, und der DateTime Typ verwendet ein Kalenderdropdown.

Von Bedeutung

Benutzerdefinierte Typ-Editoren haben sich seit Einführung des .NET Frameworks weiterentwickelt. Weitere Informationen finden Sie unter Der Designer ändert sich seit .NET Framework.