Tentang Gambar Kustom

Bagian ini berisi informasi umum tentang fungsionalitas gambaran kustom dan memberikan gambaran umum konseptual tentang bagaimana aplikasi dapat mendukung gambar kustom. Saat ini, kontrol berikut mendukung fungsionalitas gambar kustom:

• Kontrol header
• Kontrol tampilan daftar
• Kontrol bilah ulang
• Kontrol bilah alat
• Kontrol tipsalat
• Kontrol trackbar
• Kontrol tampilan pohon

• Tentang Pesan Pemberitahuan Gambar Kustom
• Siklus Cat, Tahap Menggambar, dan Pesan Pemberitahuan
• Memanfaatkan Layanan Undian Kustom
  • Menanggapi pemberitahuan prabayar
  • Meminta pemberitahuan khusus item
  • Menggambar item sendiri
  • Mengubah font dan warna
• Gambar Kustom Dengan Tampilan Daftar dan Kontrol Tampilan Pohon
  • Gambar Kustom Dengan Kontrol Tampilan Daftar
• Topik terkait

Tentang Pesan Pemberitahuan Gambar Kustom

Semua kontrol umum yang mendukung gambar kustom mengirim kode pemberitahuan NM_CUSTOMDRAW pada titik tertentu selama operasi menggambar. Kode pemberitahuan ini menjelaskan operasi menggambar yang berlaku untuk seluruh kontrol serta operasi menggambar khusus untuk item dalam kontrol. Seperti banyak kode pemberitahuan, NM_CUSTOMDRAW pemberitahuan dikirim sebagai pesan WM_NOTIFY.

Parameter lParam dari pemberitahuan gambar kustom akan menjadi alamat struktur NMCUSTOMDRAW atau struktur khusus kontrol yang berisi struktur NMCUSTOMDRAW sebagai anggota pertamanya. Tabel berikut mengilustrasikan hubungan antara kontrol dan struktur yang mereka gunakan.

Struktur	Digunakan oleh
NMCUSTOMDRAW	Kontrol rebar, trackbar, dan header
NMLVCUSTOMDRAW	Kontrol tampilan daftar
NMTBCUSTOMDRAW	Kontrol bilah alat
NMTTCUSTOMDRAW	Kontrol tipsalat
NMTVCUSTOMDRAW	Kontrol tampilan pohon

 

Siklus Cat, Tahap Menggambar, dan Pesan Pemberitahuan

Seperti semua aplikasi Windows, kontrol umum secara berkala melukis dan menghapus diri mereka sendiri berdasarkan pesan yang diterima dari sistem atau aplikasi lainnya. Proses lukisan kontrol atau penghapusan itu sendiri disebut siklus cat. Kontrol yang mendukung gambar kustom mengirim kode pemberitahuan NM_CUSTOMDRAW secara berkala melalui setiap siklus cat. Kode pemberitahuan ini disertai dengan struktur NMCUSTOMDRAW atau struktur lain yang berisi struktur NMCUSTOMDRAW sebagai anggota pertamanya.

Salah satu informasi yang dikandung struktur NMCUSTOMDRAW adalah tahap siklus cat saat ini. Ini disebut sebagai tahap gambar dan diwakili oleh nilai dalam anggota dwDrawStage struktur. Kontrol menginformasikan kepada induknya tentang empat tahap gambar dasar. Tahapan gambar dasar, atau global ini diwakili dalam struktur oleh nilai bendera berikut (ditentukan dalam Commctrl.h).

Nilai tahap gambar global	Deskripsi
CDDS_PREPAINT	Sebelum siklus cat dimulai.
CDDS_POSTPAINT	Setelah siklus cat selesai.
CDDS_PREERASE	Sebelum siklus penghapusan dimulai.
CDDS_POSTERASE	Setelah siklus penghapusan selesai.

 

Masing-masing nilai sebelumnya dapat dikombinasikan dengan bendera CDDS_ITEM untuk menentukan tahap gambar khusus untuk item. Untuk kenyamanan, Commctrl.h berisi nilai khusus item berikut.

Nilai tahap gambar khusus item	Deskripsi
CDDS_ITEMPREPAINT	Sebelum item digambar.
CDDS_ITEMPOSTPAINT	Setelah item digambar.
CDDS_ITEMPREERASE	Sebelum item dihapus.
CDDS_ITEMPOSTERASE	Setelah item dihapus.
CDDS_SUBITEM	Kontrol Umum Versi 4.71. Bendera dikombinasikan dengan CDDS_ITEMPREPAINT atau CDDS_ITEMPOSTPAINT jika subitem sedang digambar. Ini hanya akan diatur jika CDRF_NOTIFYITEMDRAW dikembalikan dari CDDS_PREPAINT.

 

Aplikasi Anda harus memproses kode pemberitahuan NM_CUSTOMDRAW lalu mengembalikan nilai tertentu yang menginformasikan kontrol apa yang harus dilakukannya. Lihat bagian berikut untuk informasi selengkapnya tentang nilai pengembalian ini.

Memanfaatkan Layanan Undian Kustom

Kunci untuk memanfaatkan fungsionalitas gambar kustom adalah merespons kode pemberitahuan NM_CUSTOMDRAW yang dikirim kontrol. Nilai pengembalian yang dikirim aplikasi Anda sebagai respons terhadap pemberitahuan ini menentukan perilaku kontrol untuk siklus cat tersebut.

Bagian ini berisi informasi tentang bagaimana aplikasi Anda dapat menggunakan nilai pengembalian pemberitahuan NM_CUSTOMDRAW untuk menentukan perilaku kontrol.

Detailnya dipecah ke dalam topik berikut:

• Menanggapi pemberitahuan prabayar
• Meminta pemberitahuan khusus item
• Menggambar item sendiri
• Mengubah font dan warna

Menanggapi pemberitahuan prabayar

Pada awal setiap siklus cat, kontrol mengirimkan kode pemberitahuan NM_CUSTOMDRAW , menentukan nilai CDDS_PREPAINT di anggota dwDrawStage dari struktur NM_CUSTOMDRAW yang menyertainya. Nilai yang dikembalikan aplikasi Anda ke pemberitahuan pertama ini menentukan bagaimana dan kapan kontrol mengirim pemberitahuan gambar kustom berikutnya untuk sisa siklus cat tersebut. Aplikasi Anda dapat mengembalikan kombinasi bendera berikut sebagai respons terhadap pemberitahuan pertama.

Nilai hasil	Efek
CDRF_DODEFAULT	Kontrol akan menggambar dirinya sendiri. Ini tidak akan mengirim pemberitahuan NM_CUSTOMDRAW tambahan untuk siklus cat ini. Bendera ini tidak dapat digunakan dengan bendera lain.
CDRF_DOERASE	Kontrol hanya akan menggambar latar belakang.
CDRF_NEWFONT	Aplikasi Anda menentukan font baru untuk item; kontrol akan menggunakan font baru. Untuk informasi selengkapnya tentang mengubah font, lihat Mengubah font dan warna. Ini terjadi ketika dwDrawStage sama dengan CDDS_ITEMPREPAINT.
CDRF_NOTIFYITEMDRAW	Kontrol akan memberi tahu induk operasi gambar khusus item apa pun. Ini akan mengirim kode pemberitahuan NM_CUSTOMDRAW sebelum dan sesudah menggambar item. Ini terjadi ketika dwDrawStage sama dengan CDDS_PREPAINT.
CDRF_NOTIFYPOSTERASE	Kontrol akan memberi tahu induk setelah menghapus item. Ini terjadi ketika dwDrawStage sama dengan CDDS_PREPAINT.
CDRF_NOTIFYPOSTPAINT	Kontrol akan mengirim pemberitahuan NM_CUSTOMDRAW ketika siklus pengecatan untuk seluruh kontrol selesai. Ini terjadi ketika dwDrawStage sama dengan CDDS_PREPAINT.
CDRF_NOTIFYSUBITEMDRAW	Versi 4.71. Aplikasi Anda akan menerima pemberitahuan NM_CUSTOMDRAW dengan dwDrawStage diatur ke CDDS_ITEMPREPAINT | CDDS_SUBITEM sebelum setiap subitem tampilan daftar digambar. Anda kemudian dapat menentukan font dan warna untuk setiap subitem secara terpisah atau mengembalikan CDRF_DODEFAULT untuk pemrosesan default. Ini terjadi ketika dwDrawStage sama dengan CDDS_ITEMPREPAINT.
CDRF_SKIPDEFAULT	Aplikasi Anda menggambar item secara manual. Kontrol tidak akan menggambar item. Ini terjadi ketika dwDrawStage sama dengan CDDS_ITEMPREPAINT.
CDRF_SKIPPOSTPAINT	Kontrol tidak akan menggambar persegi panjang fokus di sekitar item.

 

Meminta pemberitahuan khusus item

Jika aplikasi Anda mengembalikan CDRF_NOTIFYITEMDRAW ke pemberitahuan gambar kustom prabayar awal, kontrol akan mengirim pemberitahuan untuk setiap item yang digambarnya selama siklus cat tersebut. Pemberitahuan khusus item ini akan memiliki nilai CDDS_ITEMPREPAINT di anggota dwDrawStage dari struktur NMCUSTOMDRAW yang menyertainya. Anda dapat meminta agar kontrol mengirim pemberitahuan lain setelah selesai menggambar item dengan mengembalikan CDRF_NOTIFYPOSTPAINT ke pemberitahuan khusus item ini. Jika tidak, kembalikan CDRF_DODEFAULT dan kontrol tidak akan memberi tahu jendela induk hingga mulai menggambar item berikutnya.

Menggambar item sendiri

Jika aplikasi Anda menarik seluruh item, kembalikan CDRF_SKIPDEFAULT. Ini memungkinkan kontrol untuk melewati item yang tidak perlu digambar, sehingga mengurangi overhead sistem. Perlu diingat bahwa mengembalikan nilai ini berarti kontrol tidak akan menggambar bagian item apa pun.

Mengubah font dan warna

Aplikasi Anda dapat menggunakan gambar kustom untuk mengubah font item. Cukup pilih HFONT yang Anda inginkan ke dalam konteks perangkat yang ditentukan oleh anggota hdc struktur NMCUSTOMDRAW yang terkait dengan pemberitahuan gambar kustom. Karena font yang Anda pilih mungkin memiliki metrik yang berbeda dari font default, pastikan Anda menyertakan bit CDRF_NEWFONT dalam nilai pengembalian untuk pesan pemberitahuan. Untuk informasi selengkapnya tentang menggunakan fungsionalitas ini, lihat kode sampel di Menggunakan Gambar Kustom. Font yang ditentukan aplikasi Anda digunakan untuk menampilkan item tersebut ketika tidak dipilih. Gambar kustom tidak memungkinkan Anda mengubah atribut font untuk item terpilih.

Untuk mengubah warna teks untuk semua kontrol yang mendukung gambar kustom kecuali untuk tampilan daftar dan tampilan pohon, cukup atur warna teks dan latar belakang yang diinginkan dalam konteks perangkat yang disediakan dalam struktur pemberitahuan gambar kustom dengan fungsi SetTextColor dan SetBkColor. Untuk mengubah warna teks dalam tampilan daftar atau tampilan pohon, Anda perlu menempatkan nilai warna yang diinginkan dalam anggota clrText dan clrTextBk dari struktur NMLVCUSTOMDRAW atau NMTVCUSTOMDRAW.

Catatan

Sebelum versi 6.0 dari kontrol umum, toolbar mengabaikan bendera CDRF_NEWFONT. Versi 6.0 mendukung bendera CDRF_NEWFONT , dan Anda dapat menggunakannya untuk memilih font yang berbeda untuk toolbar. Namun, Anda tidak dapat mengubah warna toolbar saat gaya visual aktif. Untuk mengubah warna toolbar di Versi 6.0, Anda harus terlebih dahulu menonaktifkan gaya visual dengan memanggil SetWindowTheme dan menentukan tanpa gaya visual:

 

SetWindowTheme (hwnd, "", "");

Gambar Kustom Dengan Tampilan Daftar dan Kontrol Tampilan Pohon

Sebagian besar kontrol umum dapat ditangani pada dasarnya dengan cara yang sama. Namun, kontrol tampilan daftar dan tampilan pohon memiliki beberapa fitur yang memerlukan pendekatan yang agak berbeda untuk gambar kustom.

Untuk Versi 5.0, kedua kontrol ini dapat menampilkan teks yang diklip jika Anda mengubah font dengan mengembalikan CDRF_NEWFONT. Perilaku ini diperlukan untuk kompatibilitas mundur dengan versi kontrol umum yang lebih lama. Jika Anda ingin mengubah font kontrol tampilan daftar atau tampilan pohon, Anda akan mendapatkan hasil yang lebih baik jika Anda mengirim pesan CCM_SETVERSION dengan nilai wParam yang diatur ke 5 sebelum menambahkan item apa pun ke kontrol. Untuk contoh kontrol tampilan pohon yang menggunakan gambar kustom lihat artikel Pangkalan Pengetahuan SAMPEL: CustDTv Mengilustrasikan Gambar Kustom di TreeView (Q248496).

Gambar Kustom Dengan Kontrol Tampilan Daftar

Karena kontrol tampilan daftar memiliki subitem dan beberapa mode tampilan, Anda harus menangani pemberitahuan NM_CUSTOMDRAW agak berbeda dari untuk kontrol umum lainnya.

Untuk mode laporan, gunakan prosedur berikut.

1. Pemberitahuan NM_CUSTOMDRAW pertama akan memiliki anggota dwDrawStage dari struktur NMCUSTOMDRAW terkait yang diatur ke CDDS_PREPAINT. Mengembalikan CDRF_NOTIFYITEMDRAW.
2. Anda kemudian akan menerima pemberitahuan NM_CUSTOMDRAW dengan dwDrawStage diatur ke CDDS_ITEMPREPAINT. Jika Anda menentukan font atau warna baru dan mengembalikan CDRF_NEWFONT, semua subitem item akan diubah. Jika Anda ingin menangani setiap subitem secara terpisah, kembalikan CDRF_NOTIFYSUBITEMDRAW.
3. Jika Anda mengembalikan CDRF_NOTIFYSUBITEMDRAW di langkah sebelumnya, Anda kemudian akan menerima pemberitahuan NM_CUSTOMDRAW untuk setiap subitem dengan dwDrawStage diatur ke CDDS_SUBITEM | CDDS_ITEMPREPAINT. Untuk mengubah font atau warna untuk subitem tersebut, tentukan font atau warna baru dan kembalikan CDRF_NEWFONT.

Untuk ikon besar, ikon kecil, dan mode daftar, gunakan prosedur berikut.

1. Pemberitahuan NM_CUSTOMDRAW pertama akan memiliki anggota dwDrawStage dari struktur NMCUSTOMDRAW terkait yang diatur ke CDDS_PREPAINT. Mengembalikan CDRF_NOTIFYITEMDRAW.
2. Anda kemudian akan menerima pemberitahuan NM_CUSTOMDRAW dengan dwDrawStage diatur ke CDDS_ITEMPREPAINT. Anda dapat mengubah font atau warna item dengan menentukan font dan warna baru dan mengembalikan CDRF_NEWFONT. Karena mode ini tidak memiliki subitem, Anda tidak akan menerima pemberitahuan NM_CUSTOMDRAW tambahan.

Untuk contoh penangan pemberitahuan NM_CUSTOMDRAW tampilan daftar, lihat Menggunakan Gambar Kustom.

Topik terkait

Konseptual

Menggunakan Gambar Kustom

Referensi Gambar Kustom

Sumber Daya Lainnya

SAMPEL: CustDTv Mengilustrasikan Gambar Kustom dalam TreeView (Q248496)