Properti waktu desain untuk kontrol kustom

Artikel ini mengajarkan Anda tentang bagaimana properti ditangani untuk kontrol di Windows Forms Visual Designer di Visual Studio.

Setiap kontrol mewarisi banyak properti dari kelas dasar System.Windows.Forms.Control, seperti:

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

Saat membuat kontrol, Anda dapat menentukan properti baru dan mengontrol bagaimana properti tersebut muncul di perancang.

Menentukan properti

Setiap properti publik dengan memiliki aksesor yang ditentukan oleh kontrol secara otomatis dapat dilihat di jendela Properti Visual Studio. Jika properti juga mendefinisikan aksesor pengaturan , properti dapat diubah di jendela Properti. Namun, properti dapat ditampilkan secara eksplisit atau tersembunyi dari jendela Properti dengan menerapkan . Atribut ini mengambil satu parameter boolean untuk menunjukkan apakah itu ditampilkan atau tidak. Untuk informasi selengkapnya tentang atribut, lihat Ringkasan Atribut (C#) atau Atribut (Visual Basic).

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

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

Nota

Properti kompleks yang tidak dapat dikonversi secara implisit ke dan dari string memerlukan pengonversi jenis.

Properti terserialisasi

Properti yang diatur pada kontrol diserialisasi ke dalam berkas kode-belakang perancang. Ini terjadi ketika nilai properti diatur ke sesuatu selain nilai defaultnya.

Ketika perancang mendeteksi perubahan pada properti, perancang mengevaluasi semua properti untuk kontrol dan menserialisasikan properti apa pun yang nilainya tidak cocok dengan nilai default untuk properti . Nilai properti diserialisasikan ke dalam file code-behid perancang. Nilai default membantu perancang untuk menentukan nilai properti mana yang harus diserialisasikan.

Nilai baku

Properti dianggap memiliki nilai default saat menerapkan atribut DefaultValueAttribute, atau kelas properti berisi metode Reset dan ShouldSerialize khusus properti. Untuk informasi selengkapnya tentang atribut, lihat Ringkasan Atribut (C#) atau Atribut (Visual Basic).

Dengan mengatur nilai default, Anda mengaktifkan yang berikut ini:

• Properti menyediakan tanda visual di jendela Properti jika telah dimodifikasi dari nilai defaultnya.
• Pengguna dapat mengklik kanan properti dan memilih Reset untuk memulihkan properti ke nilai defaultnya.
• Perancang menghasilkan kode yang lebih efisien.

Jika properti menggunakan jenis sederhana, seperti jenis primitif, nilai default dapat diatur dengan menerapkan DefaultValueAttribute ke properti . Namun, properti dengan atribut ini tidak secara otomatis dimulai dengan nilai yang ditetapkan tersebut. Anda harus mengatur field pendukung properti ke nilai default yang sama. Anda dapat mengatur properti pada deklarasi atau di konstruktor kelas.

Saat properti adalah jenis kompleks, atau Anda ingin mengontrol perilaku reset dan serialisasi perancang, tentukan metode Reset<PropertyName> dan ShouldSerialize<PropertyName> pada kelas. Misalnya, jika kontrol menentukan properti Age, metode diberi nama ResetAge dan ShouldSerializeAge.

Penting

Terapkan DefaultValueAttribute ke properti, atau berikan metode Reset<PropertyName> dan ShouldSerialize<PropertyName>. Jangan mencampur dua cara untuk menentukan nilai default.

Properti dapat "diatur ulang" ke nilai defaultnya melalui jendela Properti dengan mengklik kanan pada nama properti dan memilih Reset.

Opsi menu konteks Reset akan tersedia saat properti Klik kanandiaktifkan.

• Properti memiliki atribut DefaultValueAttribute yang diterapkan, tetapi nilai properti tersebut tidak sesuai dengan nilai atributnya.
• Kelas properti mendefinisikan metode Reset<PropertyName> tanpa ShouldSerialize<PropertyName>.
• Kelas properti mendefinisikan metode Reset<PropertyName> dan ShouldSerialize<PropertyName> mengembalikan true.

DefaultValueAttribute

Jika nilai properti tidak cocok dengan nilai yang disediakan oleh , properti dianggap berubah dan dapat diatur ulang melalui jendela Properti .

Penting

Atribut ini tidak boleh digunakan pada properti yang memiliki metode Reset<PropertyName> dan ShouldSerialize<PropertyName> yang sesuai.

Kode berikut mendeklarasikan dua properti, enumerasi dengan nilai default North dan bilangan bulat dengan nilai default 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

Reset dan ShouldSerialize

Seperti yang disebutkan sebelumnya, metode Reset<PropertyName> dan ShouldSerialize<PropertyName> memberikan kesempatan untuk memandu tidak hanya perilaku reset dari sebuah properti, tetapi juga dalam menentukan apakah nilai diubah dan harus diserialisasikan ke dalam file code-behind perancang. Kedua metode bekerja sama dan Anda tidak boleh menentukannya tanpa metode lain.

Penting

Metode Reset<PropertyName> dan ShouldSerialize<PropertyName> tidak boleh dibuat untuk properti yang memiliki DefaultValueAttribute.

Saat Reset<PropertyName> ditentukan, jendela Properti menampilkan opsi menu konteks Reset untuk properti tersebut. Saat Reset dipilih, metode Reset<PropertyName> dipanggil. Opsi menu konteks Reset diaktifkan atau dinonaktifkan oleh apa yang dikembalikan oleh metode ShouldSerialize<PropertyName>. Ketika ShouldSerialize<PropertyName> mengembalikan true, itu menunjukkan bahwa properti telah berubah dari nilai defaultnya dan harus diserialisasikan ke dalam file code-behind dan mengaktifkan opsi menu konteks Reset. Saat false dikembalikan, opsi menu konteks Reset dinonaktifkan dan kode di belakang memiliki kode set properti yang dihapus.

Petunjuk / Saran

Kedua metode dapat dan harus didefinisikan dengan cakupan privat sehingga tidak membentuk API publik kontrol.

Cuplikan kode berikut mendeklarasikan properti bernama Direction. Perilaku perancang properti ini dikendalikan oleh metode ResetDirection dan 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

Jenis-jenis pengonversi

Meskipun konverter tipe biasanya mengonversi satu jenis ke jenis lainnya, mereka juga menyediakan konversi dari string ke nilai untuk grid properti dan kontrol lain pada saat desain. Konversi string-ke-nilai memungkinkan properti kompleks diwakili dalam kontrol saat desain ini.

Sebagian besar jenis data bawaan (angka, enumerasi, dan lainnya) memiliki pengonversi jenis default yang menyediakan konversi string-ke-nilai dan melakukan pemeriksaan validasi. Pengonversi jenis default berada di namespace System.ComponentModel dan diberi nama setelah jenis yang dikonversi. Nama jenis pengonversi menggunakan format berikut: {type name}Converter. Misalnya, StringConverter, TimeSpanConverter, dan Int32Converter.

Pengonversi jenis digunakan secara ekstensif pada waktu desain dengan jendela Properti. Konverter tipe bisa diterapkan ke sebuah properti atau tipe, menggunakan TypeConverterAttribute.

Jendela Properti menggunakan pengonversi untuk menampilkan properti sebagai nilai string ketika TypeConverterAttribute dideklarasikan di properti. Ketika dideklarasikan pada jenis, jendela Properti menggunakan pengonversi pada setiap properti jenis tersebut. Pengonversi jenis juga membantu menyerialisasikan nilai properti di file code-behind milik perancang.

Ketik editor

Jendela Properti secara otomatis menggunakan editor jenis untuk properti ketika jenis properti adalah tipe bawaan atau yang diketahui. Misalnya, nilai boolean diedit sebagai kotak kombo dengan nilai True dan False, sedangkan tipe DateTime menggunakan menu dropdown kalender.

Penting

Editor jenis kustom telah berubah sejak .NET Framework. Untuk informasi selengkapnya, lihat Perubahan perancang sejak .NET Framework.