Tentang Kontrol Tampilan Daftar

Lihat Sampel kontrol tampilan daftar virtual.

Kontrol tampilan daftar adalah jendela yang menampilkan kumpulan item. Kontrol tampilan daftar menyediakan beberapa cara untuk mengatur dan menampilkan item dan jauh lebih fleksibel daripada Kotak Daftar sederhana. Misalnya, informasi tambahan tentang setiap item dapat ditampilkan dalam kolom di sebelah kanan ikon dan label.

• Gaya dan Tampilan Tampilan Daftar
  • Gaya Tampilan Daftar yang Diperluas
• Gaya Tampilan Daftar Virtual
  • Membuat Kontrol Tampilan Daftar Virtual
  • Masalah Kompatibilitas
  • Menangani Kode Pemberitahuan Kontrol Tampilan Daftar Virtual
  • Manajemen Cache
• Area Kerja Tampilan Daftar
• Daftar Gambar Tampilan Daftar
• Item dan Subitem Tampilan Daftar
  • Status Item Tampilan Daftar
  • Item Panggilan Balik dan Masker Panggilan Balik
  • Posisi Item Tampilan Daftar
  • Mengatur, Mengurutkan, dan Menemukan Item
• Kolom Tampilan Daftar
• Posisi Gulir Tampilan Daftar
• Pengeditan Label Tampilan Daftar
• Warna Tampilan Daftar
• Mengatur Item Daftar menurut Grup
• Tanda Penyisipan

Gaya dan Tampilan Tampilan Daftar

Kontrol tampilan daftar dapat menampilkan item dalam lima tampilan berbeda. Gaya jendela kontrol menentukan tampilan default. Gaya jendela tambahan menentukan perataan item dan fitur khusus kontrol. Tabel berikut ini menjelaskan tampilan.

Nama Tampilan	Deskripsi
Tampilan ikon	Ditentukan oleh gaya jendela LVS_ICON atau dengan meneruskan LV_VIEW_ICON dengan pesan LVM_SETVIEW. Setiap item muncul sebagai ikon berukuran penuh dengan label di bawahnya. Pengguna dapat menyeret item ke lokasi mana pun di jendela tampilan daftar.
Tampilan ikon kecil	Ditentukan oleh gaya jendela LVS_SMALLICON atau dengan meneruskan LV_VIEW_SMALLICON dengan LVM_SETVIEW. Setiap item muncul sebagai ikon kecil dengan label di sebelah kanannya. Pengguna dapat menyeret item ke lokasi mana pun.
Tampilan daftar	Ditentukan oleh gaya jendela LVS_LIST atau dengan meneruskan LV_VIEW_LIST dengan LVM_SETVIEW. Setiap item muncul sebagai ikon kecil dengan label di sebelah kanannya. Item disusun dalam kolom dan pengguna tidak dapat menyeretnya ke lokasi arbitrer.
Tampilan laporan (detail)	Ditentukan oleh gaya jendela LVS_REPORT atau dengan melewati LV_VIEW_DETAILS dengan LVM_SETVIEW. Setiap item muncul di barisnya sendiri, dengan informasi yang disusun dalam kolom. Kolom paling kiri selalu dibiarkan dibenarkan dan berisi ikon dan label kecil. Kolom berikutnya berisi subitem seperti yang ditentukan oleh aplikasi. Setiap kolom memiliki header, kecuali Anda juga menentukan gaya jendela LVS_NOCOLUMNHEADER .
Tampilan Petak Peta	Versi 6 dan yang lebih baru. Ditentukan dengan meneruskan LV_VIEW_TILE dengan LVM_SETVIEW. Setiap item muncul sebagai ikon berukuran penuh dengan label satu atau beberapa baris di sampingnya.

 

Cuplikan layar berikut menggunakan tampilan untuk menunjukkan jumlah informasi yang berbeda tentang masing-masing dari tujuh hewan peliharaan. Tampilan menunjukkan bagaimana informasi mungkin muncul di Windows Vista. Gaya visual untuk kontrol telah diatur ke tema "Explorer" dengan menggunakan SetWindowTheme.

Cuplikan layar berikut menunjukkan tampilan detail.

Cuplikan layar berikut menunjukkan tampilan ikon.

Cuplikan layar berikut menunjukkan tampilan daftar.

Cuplikan layar berikut menunjukkan tampilan petak peta.

Anda dapat mengubah jenis tampilan setelah membuat kontrol tampilan daftar. Untuk mengambil dan mengubah gaya jendela, gunakan fungsi GetWindowLong dan SetWindowLong. Untuk menentukan gaya jendela tampilan saat ini, gunakan nilai LVS_TYPEMASK.

Anda dapat mengontrol cara item diatur dalam tampilan ikon atau ikon kecil dengan menentukan gaya jendela LVS_ALIGNTOP (default) atau LVS_ALIGNLEFT.

Anda dapat mengubah perataan setelah membuat kontrol tampilan daftar. Untuk menentukan perataan saat ini, gunakan nilai LVS_ALIGNMASK.

Gaya jendela tambahan menyediakan opsi lain, seperti apakah pengguna dapat mengedit label atau memilih lebih dari satu item sekaligus. Untuk daftar lengkapnya, lihat Gaya Jendela Tampilan Daftar.

Gaya Tampilan Daftar yang Diperluas

Gaya kontrol tampilan daftar yang diperluas menyediakan opsi seperti kotak centang, bilah gulir datar, garis kisi, dan pelacakan panas. Untuk daftar lengkapnya, lihat Gaya Tampilan Daftar yang Diperluas. Anda tidak mengakses gaya tampilan daftar yang diperluas dengan cara yang sama seperti gaya jendela standar. Anda tidak menggunakan fungsi GetWindowLong dan SetWindowLong untuk membuat perubahan gaya yang diperluas.

Ada dua pesan yang mengatur dan mengambil informasi gaya yang diperluas, LVM_SETEXTENDEDLISTVIEWSTYLE dan LVM_GETEXTENDEDLISTVIEWSTYLE. Alih-alih mengirim pesan secara eksplisit, Anda dapat menggunakan makro terkait berikut: ListView_SetExtendedListViewStyle, ListView_SetExtendedListViewStyleEx, dan ListView_GetExtendedListViewStyle.

Gaya Tampilan Daftar Virtual

Tampilan daftar virtual adalah kontrol tampilan daftar yang memiliki gaya LVS_OWNERDATA. Gaya ini memungkinkan kontrol untuk menangani jutaan item karena pemilik menerima beban pengelolaan data item. Ini memungkinkan Anda untuk menggunakan kontrol tampilan daftar virtual dengan database informasi besar, di mana metode akses data tertentu sudah ada.

Kontrol tampilan daftar virtual mempertahankan informasi item yang sangat sedikit itu sendiri. Kecuali untuk pilihan item dan informasi fokus, pemilik kontrol harus mengelola semua informasi item. Proses lain meminta informasi item dari pemilik dengan menggunakan kode pemberitahuan LVN_GETDISPINFO .

Karena jenis kontrol daftar ini ditujukan untuk himpunan data besar, disarankan agar Anda menyimpan data item yang diminta cache untuk meningkatkan performa pengambilan. Tampilan daftar menyediakan mekanisme petunjuk cache untuk membantu mengoptimalkan cache. Petunjuk diimplementasikan dalam bentuk kode pemberitahuan LVN_ODCACHEHINT .

Membuat Kontrol Tampilan Daftar Virtual

Anda membuat kontrol tampilan daftar virtual menggunakan fungsi CreateWindow atau CreateWindowEx, menentukan gaya jendela LVS_OWNERDATA sebagai bagian dari parameter fungsi dwStyle. Beralih secara dinamis ke dan dari gaya LVS_OWNERDATA tidak didukung.

Anda dapat menggunakan gaya LVS_OWNERDATA dalam kombinasi dengan sebagian besar gaya jendela lainnya, kecuali gaya LVS_SORTASCENDING atau LVS_SORTDESCENDING. Semua kontrol tampilan daftar virtual default ke gaya LVS_AUTOARRANGE.

Untuk mengaktifkan item yang akan ditampilkan dalam daftar, Anda harus terlebih dahulu mengirim pesan LVM_SETITEMCOUNT, baik secara eksplisit atau dengan menggunakan makro ListView_SetItemCountEx.

Pesan berikut ini tidak didukung di bawah gaya LVS_OWNERDATA: LVM_ENABLEGROUPVIEW, LVM_GETITEMTEXT, LVM_SETTILEINFO, dan LVM_MAPIDTOINDEX.

Masalah Kompatibilitas

Keempat gaya tampilan daftar—ikon, ikon kecil, daftar, dan tampilan laporan—mendukung gaya LVS_OWNERDATA. Kontrol tampilan daftar yang memiliki gaya LVS_OWNERDATA tidak menyimpan informasi khusus item. Oleh karena itu, satu-satunya bendera status item yang valid yang dapat Anda terapkan ke item LVIS_SELECTED dan LVIS_FOCUSED. Tidak ada informasi status lain yang disimpan. Secara khusus, kontrol tampilan daftar tidak mempertahankan gambar status atau overlay untuk setiap item. Namun, Anda bisa memiliki kueri kontrol tampilan daftar aplikasi Anda untuk gambar-gambar ini dengan mengirimkannya pesan LVM_SETCALLBACKMASK .

Sebagian besar pesan kontrol tampilan daftar dan makro terkait didukung sepenuhnya. Namun, beberapa pesan memiliki batasan atau tidak didukung saat Anda menggunakan gaya LVS_OWNERDATA. Tabel berikut ini meringkas pesan yang terpengaruh.

Pesan	Pembatasan
LVM_ARRANGE	Tidak mendukung gaya LVA_SNAPTOGRID .
LVM_DELETEALLITEMS	Mengatur jumlah item ke nol dan menghapus semua variabel pilihan internal, tetapi tidak benar-benar menghapus item apa pun. Ini membuat panggilan balik pemberitahuan.
LVM_DELETEITEM	Didukung hanya untuk integritas pilihan dan tidak benar-benar menghapus item.
LVM_GETITEMSTATE	Mengembalikan hanya fokus dan status pilihan (yaitu, status yang disimpan oleh kontrol tampilan daftar).
LVM_GETNEXTITEM	Tidak mendukung kriteria pencarian tampilan daftar LVNI_CUT, LVNI_HIDDEN, atau LVNI_DROPHILITED. Semua kriteria lainnya didukung.
LVM_GETWORKAREAS	Tidak didukung.
LVM_INSERTITEM	Hanya didukung untuk integritas pilihan.
LVM_SETITEM	Tidak didukung. Untuk mengatur status item, gunakan pesan ListView_SetItemState.
LVM_SETITEMCOUNT	Mengatur jumlah item yang saat ini ada dalam daftar. Jika kontrol tampilan daftar mengirimkan pemberitahuan yang meminta data untuk item apa pun hingga set maksimum, pemilik harus siap untuk menyediakan data tersebut. Parameter pesan mendukung kontrol tampilan daftar virtual.
LVM_SETITEMPOSITION	Tidak didukung.
LVM_SETITEMSTATE	Hanya memperbolehkan pemilihan dan status fokus yang akan diubah untuk item.
LVM_SETITEMTEXT	Tidak didukung. Ini adalah tanggung jawab aplikasi untuk mempertahankan teks item.
LVM_SETWORKAREAS	Tidak didukung.
LVM_SORTITEMS	Tidak didukung. Aplikasi bertanggung jawab untuk menyajikan item dalam urutan yang diinginkan.

 

Menangani Kode Pemberitahuan Kontrol Tampilan Daftar Virtual

Kontrol tampilan daftar dengan gaya LVS_OWNERDATA mengirim kode pemberitahuan yang sama dengan kontrol tampilan daftar lainnya dan dua kontrol tambahan: LVN_ODCACHEHINT dan LVN_ODFINDITEM. Berikut ini adalah pemberitahuan paling umum yang dikirim oleh kontrol tampilan daftar dengan gaya LVS_OWNERDATA .

Pemberitahuan	Deskripsi
LVN_GETDISPINFO	Kontrol tampilan daftar virtual mempertahankan informasi item yang sangat sedikit sendiri. Akibatnya, sering mengirim kode pemberitahuan LVN_GETDISPINFO untuk meminta informasi item. Pesan ini ditangani dengan cara yang sama seperti item panggilan balik dalam kontrol daftar standar. Karena jumlah item yang didukung oleh kontrol bisa sangat besar, data item penembolokan meningkatkan performa. Saat menangani LVN_GETDISPINFO, pemilik kontrol pertama kali mencoba menyediakan informasi item yang diminta dari cache (untuk informasi selengkapnya, lihat Manajemen Cache). Jika item yang diminta tidak di-cache, pemilik harus siap untuk memberikan informasi dengan cara lain.
LVN_ODCACHEHINT	Tampilan daftar virtual mengirimkan kode pemberitahuan LVN_ODCACHEHINT untuk membantu mengoptimalkan cache. Kode pemberitahuan menyediakan nilai indeks inklusif untuk rentang item yang direkomendasikan untuk di-cache. Setelah menerima kode pemberitahuan, pemilik harus siap memuat cache dengan informasi item untuk rentang yang diminta sehingga informasi akan tersedia saat pesan LVN_GETDISPINFO dikirim.
LVN_ODFINDITEM	Kode pemberitahuan LVN_ODFINDITEM dikirim oleh kontrol tampilan daftar virtual saat kontrol memerlukan pemilik untuk menemukan item panggilan balik tertentu. Kode pemberitahuan dikirim saat kontrol tampilan daftar menerima akses kunci cepat atau saat menerima pesan LVM_FINDITEM. Informasi pencarian dikirim dalam bentuk struktur LVFINDINFO, yang merupakan anggota struktur NMLVFINDITEM. Pemilik harus siap untuk mencari item yang cocok dengan informasi yang diberikan oleh kontrol tampilan daftar. Pemilik mengembalikan indeks item jika berhasil, atau -1 jika tidak ada item yang cocok yang ditemukan.

 

Manajemen Tembolokan

Kontrol tampilan daftar dengan gaya LVS_OWNERDATA menghasilkan sejumlah besar kode pemberitahuan LVN_GETDISPINFO dan, untuk membantu mengoptimalkan cache, pesan LVN_ODCACHEHINT. LVN_ODCACHEHINT pesan menyediakan informasi tentang item yang direkomendasikan untuk disertakan dalam cache. Pesan ini dikirim sebagai pesan WM_NOTIFY, dengan nilai lParam bertindak sebagai alamat struktur NMLVCACHEHINT.

Struktur NMLVCACHEHINT mencakup dua anggota bilangan bulat, iFrom dan iTo, yang mewakili titik akhir inklusif dari berbagai item yang kemungkinan besar akan diperlukan. Pemilik harus siap memuat cache dengan informasi item untuk setiap item dalam rentang yang direkomendasikan.

Kontrol daftar sering memerlukan informasi item untuk item pertama (offset 0). Kode pemberitahuan LVN_ODCACHEHINT mungkin tidak selalu menyertakan item 0, tetapi harus selalu disertakan dalam cache.

Item terakhir dalam daftar sering diakses. Oleh karena itu, pemilik mungkin ingin menyimpan cache kedua yang menyertakan item di akhir daftar. Rentang yang diminta dari LVN_ODCACHEHINT dapat diperiksa terhadap cache akhir untuk membuatnya tersedia secara otomatis alih-alih memuat ulang rentang akhir yang sama setiap kali.

Area Kerja Tampilan Daftar

Kontrol tampilan daftar mendukung area kerja, yang merupakan area virtual persegi panjang yang digunakan kontrol tampilan daftar untuk mengatur itemnya. Area kerja bukan jendela dan tidak dapat memiliki batas yang terlihat. Secara default, kontrol tampilan daftar tidak memiliki area kerja. Dengan membuat area kerja, Anda dapat membuat batas kosong di sebelah kiri, atas, atau kanan item atau menyebabkan bilah gulir horizontal ditampilkan ketika biasanya tidak akan ada.

Ketika area kerja dibuat, item yang terletak di dalam area kerja menjadi anggota area kerja. Demikian pula, jika item dipindahkan ke area kerja, item menjadi anggota area kerja tersebut. Jika item tidak terletak di dalam area kerja apa pun, item tersebut secara otomatis menjadi anggota area kerja (indeks 0) pertama. Untuk menempatkan item baru dalam area kerja tertentu, Anda harus terlebih dahulu membuat item lalu menggunakan pesan LVM_SETITEMPOSITION atau LVM_SETITEMPOSITION32 untuk memindahkannya ke area kerja yang diinginkan.

Ilustrasi berikut adalah contoh kontrol tampilan daftar yang berisi empat area kerja, masing-masing dalam kuadrian area klien yang berbeda.

Beberapa area kerja dapat digunakan untuk membuat area yang berbeda dalam satu tampilan. Anda dapat membuat area dalam satu tampilan yang memiliki arti berbeda. Misalnya, tampilan sistem file mungkin memiliki area untuk file baca/tulis dan area lain untuk file baca-saja. Pengguna dapat mengategorikan item dengan menempatkannya di area kerja yang berbeda. Jika file dipindahkan ke area baca-saja, file akan secara otomatis menjadi baca-saja.

Beberapa area kerja dapat berpotongan, tetapi item apa pun yang terletak di dalam persimpangan menjadi anggota area dengan indeks yang lebih rendah; oleh karena itu, yang terbaik adalah menghindari situasi ini. Saat mengurutkan beberapa area kerja, item diurutkan dibandingkan dengan item lain di area kerja yang sama.

Jumlah area kerja dapat diambil dengan pesan LVM_GETNUMBEROFWORKAREAS. Area kerja diubah dengan pesan LVM_SETWORKAREAS dan dapat diambil dengan pesan LVM_GETWORKAREAS. Kedua pesan ini mengambil alamat array struktur RECT sebagai lParam dan jumlah struktur RECT sebagai wParam. Anggota kiri dan atas struktur ini menentukan koordinat sudut kiri atas (asal) area kerja, dan anggota kanan dan bawah menentukan sudut kanan bawah area kerja. Semua koordinat berada dalam koordinat klien dari tampilan daftar. Jumlah maksimum area kerja yang diizinkan ditentukan oleh nilai LV_MAX_WORKAREAS .

Mengubah area kerja tidak berpengaruh pada kontrol tampilan daftar yang memiliki tampilan LVS_LIST atau LVS_REPORT, tetapi area kerja akan dipertahankan saat jenis tampilan diubah. Dengan tampilan LVS_ICON dan LVS_SMALLICON, area kerja dapat dimodifikasi untuk mengubah cara item ditampilkan. Membuat lebar area kerja (kanan - kiri) lebih besar dari lebar klien kontrol menyebabkan item dibungkus pada lebar tersebut dan bilah gulir horizontal ditampilkan. Membuat lebar area kerja lebih sempit dari lebar area klien kontrol menyebabkan item dibungkus dalam area kerja dan bukan area klien. Mengatur anggota kiri atau atas ke nilai positif menyebabkan item ditampilkan mulai dari area kerja, membuat ruang kosong antara tepi kontrol dan item. Ruang kosong juga dapat dibuat antara tepi kanan kontrol dan item dengan membuat lebar area kerja kurang dari lebar klien kontrol.

Daftar Gambar Tampilan Daftar

Secara default, kontrol tampilan daftar tidak menampilkan gambar item. Untuk menampilkan gambar item, Anda harus membuat daftar gambar dan mengaitkannya dengan kontrol. Kontrol tampilan daftar dapat memiliki tiga daftar gambar:

• Daftar gambar yang berisi ikon berukuran penuh yang ditampilkan saat kontrol berada dalam tampilan ikon.
• Daftar gambar yang berisi ikon kecil yang ditampilkan saat kontrol berada dalam tampilan ikon kecil, tampilan daftar, atau tampilan laporan.
• Daftar gambar yang berisi gambar status, yang ditampilkan di sebelah kiri ikon berukuran penuh atau kecil. Anda dapat menggunakan gambar status, seperti kotak centang yang dicentang dan dikosongkan, untuk menunjukkan status item yang ditentukan aplikasi. Gambar status ditampilkan dalam tampilan ikon, tampilan ikon kecil, tampilan daftar, dan tampilan laporan.

Daftar gambar ikon berukuran penuh dan kecil juga dapat berisi gambar overlay, yang dirancang untuk digambar secara transparan di atas ikon item.

Untuk menggunakan gambar overlay dalam kontrol tampilan daftar:

1. Panggil fungsi ImageList_SetOverlayImage untuk menetapkan indeks gambar overlay ke gambar dalam daftar gambar ikon berukuran penuh dan kecil. Gambar overlay diidentifikasi oleh indeks berbasis satu.
2. Anda dapat mengaitkan indeks gambar overlay dengan item saat memanggil makro ListView_InsertItem atau ListView_SetItem. Gunakan makro INDEXTOOVERLAYMASK untuk menentukan indeks gambar overlay di anggota status struktur LVITEM item. Anda juga harus mengatur bit LVIS_OVERLAYMASK di anggota stateMask.

Jika daftar gambar status ditentukan, kontrol tampilan daftar mencadangkan ruang di sebelah kiri ikon setiap item untuk gambar status.

Untuk mengaitkan gambar status dengan item, gunakan makro INDEXTOSTATEIMAGEMASK untuk menentukan indeks gambar status dalam anggota status struktur LVITEM. Indeks mengidentifikasi gambar dalam daftar gambar status kontrol. Meskipun indeks daftar gambar berbasis nol, kontrol menggunakan indeks berbasis satu untuk mengidentifikasi gambar status. Indeks gambar status nol menunjukkan bahwa item tidak memiliki gambar status.

Secara default, ketika kontrol tampilan daftar dihancurkan, kontrol tersebut akan menghancurkan daftar gambar yang ditetapkan untuknya. Namun, jika kontrol tampilan daftar memiliki gaya jendela LVS_SHAREIMAGELISTS , aplikasi bertanggung jawab untuk menghancurkan daftar gambar ketika tidak lagi digunakan. Anda harus menentukan gaya ini jika Anda menetapkan daftar gambar yang sama ke beberapa kontrol tampilan daftar; jika tidak, lebih dari satu kontrol mungkin mencoba menghancurkan daftar gambar yang sama.

Item dan Subitem Tampilan Daftar

Setiap item dalam kontrol tampilan daftar memiliki ikon, label, status saat ini, dan nilai yang ditentukan aplikasi. Dengan menggunakan pesan tampilan daftar, Anda dapat menambahkan, memodifikasi, dan menghapus item serta mengambil informasi tentang item.

Setiap item dapat memiliki satu atau beberapa subitem. Subitem adalah string yang, dalam tampilan laporan, ditampilkan dalam kolom yang terpisah dari ikon dan label item. Untuk menentukan teks subitem, gunakan pesan LVM_SETITEMTEXT atau LVM_SETITEM. Semua item dalam kontrol tampilan daftar memiliki jumlah subitem yang sama. Jumlah subitem ditentukan oleh jumlah kolom dalam kontrol tampilan daftar. Saat Anda menambahkan kolom ke kontrol tampilan daftar, Anda menentukan indeks subitem terkait.

Struktur LVITEM mendefinisikan item tampilan daftar atau subitem. Anggota iItem adalah indeks item berbasis nol. Anggota iSubItem adalah indeks berbasis satu subitem atau nol jika struktur berisi informasi tentang item. Anggota tambahan menentukan teks, ikon, status, dan data item item. Data item adalah nilai yang ditentukan aplikasi yang terkait dengan item tampilan daftar.

Untuk menambahkan item ke kontrol tampilan daftar, gunakan pesan LVM_INSERTITEM, menentukan alamat struktur LVITEM. Sebelum menambahkan beberapa item, Anda dapat mengirim kontrol pesan LVM_SETITEMCOUNT , menentukan jumlah item yang pada akhirnya akan dimuat kontrol. Pesan ini memungkinkan kontrol tampilan daftar untuk merealokasi struktur data internalnya hanya sekali daripada setiap kali Anda menambahkan item. Anda dapat menentukan jumlah item dalam kontrol tampilan daftar dengan menggunakan pesan LVM_GETITEMCOUNT. Jika Anda menambahkan sejumlah besar item ke kontrol tampilan daftar, Anda dapat mempercepat proses dengan menonaktifkan penggalian ulang sebelum menambahkan item, lalu mengaktifkan penggalian ulang setelah item ditambahkan. Gunakan pesan WM_SETREDRAW untuk mengaktifkan dan menonaktifkan penguraian ulang.

Untuk mengubah atribut item tampilan daftar, gunakan pesan LVM_SETITEM, menentukan alamat struktur LVITEM. Anggota mask struktur ini menentukan atribut item yang ingin Anda ubah. Misalnya, untuk mengubah teks item atau subitem saja, gunakan pesan LVM_SETITEMTEXT.

Untuk mengambil informasi tentang item tampilan daftar, gunakan pesan LVM_GETITEM, menentukan alamat struktur LVITEM untuk diisi. Anggota mask dari struktur ini menentukan atribut item yang akan diambil. Untuk hanya mengambil teks item atau subitem, gunakan pesan LVM_GETITEMTEXT.

Untuk menghapus item tampilan daftar, gunakan pesan LVM_DELETEITEM. Anda dapat menghapus semua item dalam kontrol tampilan daftar dengan menggunakan pesan LVM_DELETEALLITEMS.

Status Item Tampilan Daftar

Status item adalah nilai yang menentukan ketersediaan item, menunjukkan tindakan pengguna, atau mencerminkan status item. Kontrol tampilan daftar mengubah beberapa bit status, seperti saat pengguna memilih item. Aplikasi mungkin mengubah bit status lain untuk menonaktifkan atau menyembunyikan item atau untuk menentukan gambar overlay atau gambar status. Untuk informasi selengkapnya tentang gambar overlay dan gambar status, lihat Daftar Gambar Tampilan Daftar.

Status item ditentukan oleh anggota status struktur LVITEM . Saat Anda menentukan atau mengubah status item, anggota stateMask menentukan bit status mana yang perlu Anda ubah. Anda dapat mengubah status item dengan menggunakan pesan LVM_SETITEMSTATE. Anda dapat menentukan status item saat membuatnya atau saat mengubah atributnya dengan menggunakan pesan LVM_SETITEM. Untuk menentukan status item saat ini, gunakan pesan LVM_GETITEMSTATE atau LVM_GETITEM.

Untuk mengatur gambar overlay item, anggota stateMask dari struktur LVITEM harus menyertakan nilai LVIS_OVERLAYMASK, dan anggota status harus menyertakan indeks berbasis satu gambar overlay yang digeser ke kiri 8 bit dengan menggunakan makro INDEXTOOVERLAYMASK. Indeks bisa nol untuk menentukan tidak ada gambar overlay.

Untuk mengatur gambar status item, anggota stateMask dari struktur LVITEM harus menyertakan nilai LVIS_STATEIMAGEMASK, dan anggota status harus menyertakan indeks berbasis satu gambar status yang digeser ke kiri 12 bit dengan menggunakan makro INDEXTOSTATEIMAGEMASK. Indeks bisa nol untuk menentukan tidak ada gambar status.

Item Panggilan Balik dan Masker Panggilan Balik

Untuk setiap itemnya, kontrol tampilan daftar biasanya menyimpan teks label, indeks daftar gambar ikon item, dan sekumpulan bendera bit untuk status item. Anda dapat menentukan item panggilan balik atau mengubah masker panggilan balik kontrol untuk menunjukkan bahwa aplikasi, bukan kontrol, menyimpan beberapa atau semua informasi ini. Anda mungkin ingin menggunakan panggilan balik jika aplikasi Anda menyimpan beberapa informasi ini.

Item panggilan balik dalam kontrol tampilan daftar adalah item tempat aplikasi menyimpan indeks teks atau ikon, atau keduanya. Anda dapat menentukan item panggilan balik saat mengirim pesan LVM_INSERTITEM untuk menambahkan item ke kontrol tampilan daftar. Jika aplikasi menyimpan teks untuk item atau subitem, atur anggota pszText dari struktur LVITEM item ke LPSTR_TEXTCALLBACK. Jika aplikasi menyimpan indeks ikon untuk item, atur anggota iImage dari struktur LVITEM item ke I_IMAGECALLBACK.

Masker panggilan balik dari kontrol tampilan daftar adalah sekumpulan bendera bit yang menentukan status item tempat aplikasi, bukan kontrol, menyimpan data saat ini. Masker panggilan balik berlaku untuk semua item kontrol, tidak seperti penetapan item panggilan balik, yang berlaku untuk item tertentu. Masker panggilan balik adalah nol secara default, yang berarti bahwa kontrol tampilan daftar menyimpan semua informasi status item. Setelah membuat kontrol tampilan daftar dan menginisialisasi itemnya, Anda dapat mengirim pesan LVM_SETCALLBACKMASK untuk mengubah masker panggilan balik. Untuk mengambil masker panggilan balik saat ini, kirim pesan LVM_GETCALLBACKMASK.

Saat kontrol tampilan daftar harus menampilkan atau mengurutkan item tampilan daftar tempat aplikasi menyimpan informasi panggilan balik, kontrol mengirimkan kode pemberitahuan LVN_GETDISPINFO ke jendela induk kontrol. Pesan ini menentukan struktur NMLVDISPINFO yang berisi jenis informasi yang diperlukan dan mengidentifikasi item atau subitem yang akan diambil. Jendela induk harus memproses LVN_GETDISPINFO untuk menyediakan data yang diminta.

Jika kontrol tampilan daftar mendeteksi perubahan informasi panggilan balik item, seperti perubahan informasi teks, ikon, atau status, kontrol akan mengirim kode pemberitahuan LVN_SETDISPINFO untuk memberi tahu Anda tentang perubahan tersebut.

Jika Anda mengubah atribut item panggilan balik atau bit status, Anda menggunakan pesan LVM_UPDATE untuk memaksa kontrol mengecat ulang item. Pesan ini juga menyebabkan kontrol mengatur itemnya jika memiliki gaya LVS_AUTOARRANGE. Anda dapat menggunakan pesan LVM_REDRAWITEMS untuk menggambar ulang rentang item dengan membatalkan bagian yang sesuai dari area klien kontrol tampilan daftar.

Dengan menggunakan item panggilan balik dan masker panggilan balik secara efektif, Anda dapat memastikan bahwa setiap atribut item hanya dipertahankan di satu tempat. Melakukan ini dapat menyederhanakan aplikasi Anda, tetapi satu-satunya ruang yang disimpan adalah memori yang jika tidak diperlukan untuk menyimpan label item dan teks subitem.

Posisi Item Tampilan Daftar

Setiap item tampilan daftar memiliki posisi dan ukuran, yang dapat Anda ambil dan atur menggunakan pesan. Anda juga dapat menentukan item mana, jika ada, yang berada pada posisi tertentu. Posisi item tampilan daftar ditentukan dalam koordinat tampilan, yang merupakan koordinat klien yang diimbangi oleh posisi gulir.

Untuk mengambil dan mengatur posisi item, gunakan pesan LVM_GETITEMPOSITION dan LVM_SETITEMPOSITION. LVM_GETITEMPOSITION berfungsi untuk semua tampilan, tetapi LVM_SETITEMPOSITION hanya berfungsi untuk tampilan ikon dan ikon kecil.

Anda dapat menentukan item mana, jika ada, berada di lokasi tertentu dengan menggunakan pesan LVM_HITTEST.

Untuk mengambil persegi panjang pembatas untuk item daftar atau hanya untuk ikon atau labelnya, gunakan pesan LVM_GETITEMRECT.

Mengatur, Mengurutkan, dan Menemukan Item

Anda dapat menggunakan pesan tampilan daftar untuk menyusun dan mengurutkan item dan menemukan item berdasarkan atribut atau posisinya. Mengatur reposisi item untuk meratakan kisi, tetapi indeks item tidak berubah. Pengurutan mengubah urutan item (dan indeks yang sesuai) lalu memposisikannya kembali. Anda hanya dapat mengatur item dalam tampilan ikon dan ikon kecil, tetapi Anda dapat mengurutkan item dalam tampilan apa pun. Untuk menemukan item, Anda mengirim pesan tampilan daftar yang menentukan lokasi item atau properti.

Untuk mengatur item, gunakan pesan LVM_ARRANGE. Anda dapat memastikan bahwa item disusun setiap saat dengan menentukan gaya jendela LVS_AUTOARRANGE .

Untuk mengurutkan item, gunakan pesan LVM_SORTITEMS. Saat Anda mengurutkan menggunakan pesan ini, Anda menentukan fungsi panggilan balik yang ditentukan aplikasi yang dipanggil kontrol tampilan daftar untuk membandingkan urutan relatif dari dua item. Kontrol meneruskan ke fungsi perbandingan data item yang terkait dengan masing-masing dari dua item. Data item adalah nilai yang ditentukan dalam anggota lParam dari struktur LVITEM item saat dimasukkan ke dalam daftar. Dengan menentukan data item yang sesuai dan menyediakan fungsi perbandingan yang sesuai, Anda dapat mengurutkan item menurut labelnya, oleh subitem apa pun, atau oleh properti lainnya. Perhatikan bahwa mengurutkan item tidak menyusun ulang subitem yang sesuai. Ketika item diurutkan ulang, subitem yang sesuai dibawa bersama mereka; artinya, seluruh baris dijaga bersama-sama. Untuk mengurutkan kolom secara terpisah satu sama lain, melepaskan subitem dari itemnya, Anda harus meregenerasi kolom setelah mengurutkan menggunakan LVM_SETITEM.

Anda dapat memastikan bahwa kontrol tampilan daftar selalu diurutkan dengan menentukan gaya jendela LVS_SORTASCENDING atau LVS_SORTDESCENDING. Kontrol dengan gaya ini menggunakan teks label item untuk mengurutkannya dalam urutan naik atau turun. Anda tidak dapat menyediakan fungsi perbandingan saat menggunakan gaya jendela ini. Jika kontrol tampilan daftar memiliki salah satu gaya ini, pesan LVM_INSERTITEM akan gagal jika Anda mencoba menyisipkan item yang memiliki LPSTR_TEXTCALLBACK sebagai anggota pszText dari struktur LVITEM-nya.

Anda dapat menemukan item tampilan daftar dengan properti tertentu dengan menggunakan pesan LVM_FINDITEM. Anda dapat menemukan item tampilan daftar yang berada dalam status tertentu dan memiliki hubungan tertentu dengan item tertentu dengan menggunakan pesan LVM_GETNEXTITEM. Misalnya, Anda dapat mengambil item yang dipilih berikutnya di sebelah kanan item tertentu.

Kolom Tampilan Daftar

Kolom mengontrol cara item dan subitemnya ditampilkan dalam tampilan laporan. Setiap kolom memiliki judul dan lebar dan dikaitkan dengan subitem tertentu; subitem zero adalah ikon dan label item. Atribut kolom ditentukan oleh struktur LVCOLUMN.

Untuk menambahkan kolom ke kontrol tampilan daftar, gunakan pesan LVM_INSERTCOLUMN. Untuk menghapus kolom, gunakan pesan LVM_DELETECOLUMN.

Catatan

Menghapus kolom nol kontrol tampilan daftar hanya didukung di ComCtl32.dll versi 6 dan yang lebih baru. Versi 5 juga mendukung penghapusan kolom nol, tetapi hanya setelah Anda menggunakan CCM_SETVERSION untuk mengatur versi ke 5 atau yang lebih baru. Versi sebelum versi 5 tidak mendukung penghapusan nol kolom.

 

Anda dapat mengambil dan mengubah properti kolom yang sudah ada dengan menggunakan pesan LVM_GETCOLUMN dan LVM_SETCOLUMN. Untuk mengambil atau mengubah lebar kolom, gunakan pesan LVM_GETCOLUMNWIDTH dan LVM_SETCOLUMNWIDTH.

Kecuali gaya jendela LVS_NOCOLUMNHEADER ditentukan, header kolom muncul dalam tampilan laporan. Pengguna dapat mengklik header kolom, menyebabkan kode pemberitahuan LVN_COLUMNCLICK dikirim ke jendela induk. Biasanya, jendela induk mengurutkan kontrol tampilan daftar menurut kolom yang ditentukan saat klik ini terjadi. Pengguna juga dapat menyeret panduan kolom di antara header untuk mengukur kolom.

Kontrol tampilan daftar dapat menampilkan gambar di samping judul kolom. Untuk menerapkan fitur ini, tentukan nilai LVCF_IMAGE dan tetapkan indeks gambar ke anggota iImage dalam struktur LVCOLUMN .

Kontrol tampilan daftar dapat mengatur urutan tampilan kolom. Untuk menerapkan fitur ini, tentukan nilai LVCF_ORDER dan tetapkan urutan kolom ke anggota iOrder dalam struktur LVCOLUMN . Urutan kolom berbasis nol dan dalam urutan kiri ke kanan. Misalnya, nol menunjukkan kolom paling kiri.

Posisi Gulir Tampilan Daftar

Kecuali gaya jendela LVS_NOSCROLL ditentukan, kontrol tampilan daftar dapat digulir untuk menampilkan lebih banyak item daripada yang dapat pas di area klien kontrol. Anda dapat mengambil posisi gulir kontrol tampilan daftar dan informasi terkait, menggulir kontrol tampilan daftar dengan jumlah tertentu, atau menggulir kontrol tampilan daftar sehingga item daftar tertentu terlihat.

Dalam tampilan ikon atau tampilan ikon kecil, posisi gulir saat ini ditentukan oleh asal tampilan. Asal tampilan adalah kumpulan koordinat, relatif terhadap area kontrol tampilan daftar yang terlihat, yang sesuai dengan koordinat tampilan (0, 0). Untuk mengambil asal tampilan saat ini, gunakan pesan LVM_GETORIGIN. Pesan ini hanya boleh digunakan dalam tampilan ikon atau ikon kecil; ini mengembalikan kesalahan dalam tampilan daftar atau laporan.

Dalam tampilan daftar atau laporan, posisi gulir saat ini ditentukan oleh indeks teratas. Indeks teratas adalah indeks item pertama yang terlihat dalam kontrol tampilan daftar. Untuk mengambil indeks teratas saat ini, gunakan pesan LVM_GETTOPINDEX. Pesan ini mengembalikan hasil yang valid hanya dalam tampilan daftar atau laporan; menampilkan nol dalam ikon atau tampilan ikon kecil.

Anda dapat menggunakan pesan LVM_GETVIEWRECT untuk mengambil persegi panjang pembatas semua item dalam kontrol tampilan daftar, relatif terhadap area kontrol yang terlihat.

Pesan LVM_GETCOUNTPERPAGE mengembalikan jumlah item yang pas di satu halaman kontrol tampilan daftar. Pesan ini mengembalikan hasil yang valid hanya dalam tampilan daftar dan laporan; dalam ikon dan tampilan ikon kecil, menampilkan jumlah total item.

Untuk menggulir kontrol tampilan daftar dengan jumlah tertentu, gunakan pesan LVM_SCROLL. Dengan menggunakan pesan LVM_ENSUREVISIBLE, Anda dapat menggulir kontrol tampilan daftar, jika perlu, untuk memastikan bahwa item tertentu terlihat.

Pengeditan Label Tampilan Daftar

Kontrol tampilan daftar yang memiliki gaya jendela LVS_EDITLABELS memungkinkan pengguna mengedit label item di tempat. Pengguna mulai mengedit dengan mengklik label item yang memiliki fokus. Atau, aplikasi dapat mulai mengedit secara otomatis dengan menggunakan pesan LVM_EDITLABEL. Kontrol tampilan daftar memberi tahu jendela induk saat pengeditan dimulai dan kapan dibatalkan atau selesai. Saat pengeditan selesai, jendela induk bertanggung jawab untuk memperbarui label item, jika sesuai.

Saat pengeditan label dimulai, kontrol edit dibuat, diposisikan, dan diinisialisasi. Sebelum ditampilkan, kontrol tampilan daftar mengirimkan jendela induknya kode pemberitahuan LVN_BEGINLABELEDIT . Jika Anda perlu mengubah proses pengeditan label, Anda dapat menerapkan handler untuk pemberitahuan ini.

Salah satu penggunaan untuk handler pemberitahuan LVN_BEGINLABELEDIT adalah mengontrol label mana yang dapat diedit pengguna. Untuk mencegah pengeditan label, kembalikan nilai bukan nol. Untuk menyesuaikan pengeditan label, minta handler pemberitahuan mengambil handel ke kontrol edit dengan mengirim pesan LVM_GETEDITCONTROL ke kontrol tampilan daftar. Setelah menanganinya, Anda dapat menyesuaikan kontrol edit dengan mengirim pesan EM_XXX biasa. Misalnya, untuk membatasi jumlah teks yang dapat dimasukkan pengguna, kirim kontrol edit pesan EM_LIMITTEXT . Anda dapat mengubah teks default kontrol edit dengan SetWindowText. Anda bahkan dapat mensubkelas kontrol edit untuk mencegat dan membuang karakter yang tidak valid.

Saat pengeditan label dibatalkan atau selesai, kontrol tampilan daftar mengirimkan jendela induknya kode pemberitahuan LVN_ENDLABELEDIT . Parameter lParam adalah alamat struktur NMLVDISPINFO . Anggota item dari struktur ini adalah struktur LVITEM yang anggota iItem-nya mengidentifikasi item. Jika pengeditan dibatalkan, anggota pszText dari struktur LVITEM adalah NULL; jika tidak, pszText adalah alamat teks yang diedit. Jendela induk bertanggung jawab untuk memperbarui label item jika ingin menyimpan label baru.

Warna Tampilan Daftar

Aplikasi dapat mengambil dan mengatur tiga warna untuk kontrol tampilan daftar.

Warna	Pesan yang digunakan untuk mengambil dan mengatur warna
Warna teks	LVM_GETTEXTCOLOR, LVM_SETTEXTCOLOR
Warna latar belakang teks	LVM_GETTEXTBKCOLOR, LVM_SETTEXTBKCOLOR
Warna latar belakang jendela	LVM_GETBKCOLOR, LVM_SETBKCOLOR

 

Untuk mengkustomisasi tampilan kontrol tampilan daftar secara lebih signifikan, gunakan NM_CUSTOMDRAW (tampilan daftar) atau gunakan gaya visual (lihat Gaya Visual dan Mengaktifkan Gaya Visual).

Mengatur Item Daftar menurut Grup

Fitur pengelompokan kontrol tampilan daftar memungkinkan Anda mengelompokkan kumpulan item terkait secara logis secara visual. Grup dapat dibuat berdasarkan properti item, atribut, atau karakteristik lainnya. Grup ini biasanya dipisahkan pada layar dengan header horizontal yang berisi nama grup. Cuplikan layar berikut menunjukkan item yang dikelompokkan.

Anda menggunakan struktur LVGROUP untuk menyimpan informasi tentang grup, seperti teks header dan footer, status grup saat ini, dan sebagainya. API pengelompokan menyertakan pesan yang memungkinkan Anda mengelola grup dan elemen grup dengan menambahkan item ke grup, menambahkan grup ke tampilan, mengurutkan item grup, dan mengkueri grup untuk ukuran item dan informasi lainnya. Misalnya, Anda dapat mengatur dan mengambil parameter tampilan untuk setiap grup dengan menggunakan makro ListView_SetGroupMetrics dan ListView_GetGroupMetrics.

Pengelompokan tersedia di semua tampilan kecuali tampilan daftar. Ini tidak tersedia pada kontrol yang memiliki gaya LVS_OWNERDATA.

Untuk informasi selengkapnya, lihat Menggunakan Kontrol Tampilan Daftar.

Tanda Penyisipan

Tanda penyisipan memperlihatkan pengguna tempat item yang diseret akan ditempatkan. Tanda penyisipan saat ini ditampilkan saat pengguna menyeret item ke menu Mulai atau bilah Luncur Cepat. Tanda penyisipan juga berfungsi untuk daftar yang diatur ke susun otomatis. Saat pengguna menyeret item ke titik di antara dua item lain, tanda penyisipan memperlihatkan lokasi baru item yang diharapkan. Cuplikan layar berikut menunjukkan tanda penyisipan.

Elemen API tanda penyisipan memungkinkan penempatan tanda penyisipan dengan menyediakan pesan dan bendera yang melakukan deteksi hit, yang menentukan lokasi dan tampilan tanda penyisipan menurut item, dan kueri tersebut untuk informasi tentang ukuran dan tampilan tanda penyisipan saat ini.

Baca juga

• Sampel kontrol tampilan daftar virtual