Tentang Kotak Daftar
Kontrol kotak daftar berisi daftar sederhana tempat pengguna umumnya dapat memilih satu atau beberapa item. Kotak daftar memberikan fleksibilitas terbatas dibandingkan dengan kontrol Tampilan Daftar.
Item kotak daftar dapat diwakili oleh string teks, bitmap, atau keduanya. Jika kotak daftar tidak cukup besar untuk menampilkan semua item kotak daftar sekaligus, kotak daftar menyediakan bilah gulir. Pengguna menggulir item kotak daftar dan menerapkan atau menghapus status pilihan seperlunya. Memilih item kotak daftar mengubah tampilan visualnya, biasanya dengan mengubah warna teks dan latar belakang menjadi yang ditentukan oleh metrik sistem operasi yang relevan. Saat pengguna memilih atau membatalkan pilihan item, sistem mengirim pesan pemberitahuan ke jendela induk kotak daftar.
Untuk aplikasi ANSI, sistem mengonversi teks dalam kotak daftar ke Unicode dengan menggunakan halaman kode CP_ACP. Hal ini dapat menyebabkan masalah. Misalnya, karakter Romawi beraksen dalam kotak daftar non-Unicode di Windows, versi Jepang akan keluar kacau. Untuk memperbaikinya, kompilasikan aplikasi sebagai Unicode atau gunakan kotak daftar yang digambar oleh pemilik.
Bagian ini membahas topik berikut:
- Membuat Kotak Daftar
- Tipe dan Gaya Kotak Daftar
- Fungsi Kotak Daftar
- Pesan Pemberitahuan dari Kotak Daftar
- Pesan ke Kotak Daftar
- Pemrosesan Pesan Jendela Default
- Owner-Drawn Kotak Daftar
- Kotak Daftar Seret
Membuat Kotak Daftar
Cara term mudah untuk membuat kotak daftar dalam kotak dialog adalah dengan menyeretnya dari Kotak Alat di Microsoft Visual Studio ke sumber daya dialog Anda. Untuk membuat kotak daftar secara dinamis, atau untuk membuat kotak daftar di jendela selain kotak dialog, gunakan fungsiCreateWindowEx, menentukan kelas jendela WC_LISTBOX dan gaya kotak daftar yang sesuai.
Jenis dan Gaya Kotak Daftar
Ada dua jenis kotak daftar: pilihan tunggal (default) dan beberapa pilihan. Dalam kotak daftar pilihan tunggal, pengguna hanya dapat memilih satu item pada satu waktu. Dalam kotak daftar beberapa pilihan, pengguna dapat memilih lebih dari satu item pada satu waktu. Untuk membuat kotak daftar beberapa pilihan, tentukan LBS_MULTIPLESEL atau gaya LBS_EXTENDEDSEL.
Tampilan dan pengoperasian kotak daftar dikontrol oleh gaya kotak daftar dan gaya jendela. Gaya ini menunjukkan apakah daftar diurutkan, disusun dalam beberapa kolom, digambar oleh aplikasi, dan sebagainya. Dimensi dan gaya kotak daftar biasanya ditentukan dalam templat kotak dialog yang disertakan dalam sumber daya aplikasi.
Nota
Untuk menggunakan gaya visual dengan kontrol ini, aplikasi harus menyertakan manifes dan harus memanggil InitCommonControls di awal program. Untuk informasi tentang gaya visual, lihat Visual Styles. Untuk informasi mengenai manifest, lihat Mengaktifkan Gaya Visual.
Fungsi Kotak Daftar
Fungsi DlgDirList menggantikan konten kotak daftar dengan nama drive, direktori, dan file yang cocok dengan serangkaian kriteria tertentu. Fungsi DlgDirSelectEx mengambil pilihan saat ini dalam kotak daftar yang diinisialisasi oleh DlgDirList. Fungsi-fungsi ini memungkinkan pengguna untuk memilih drive, direktori, atau file dari kotak daftar tanpa mengetik lokasi dan nama file.
Selain itu, fungsiGetListBoxInfo mengembalikan jumlah item per kolom dalam kotak daftar tertentu.
Pesan Pemberitahuan dari Kotak Daftar
Saat peristiwa terjadi dalam kotak daftar, kotak daftar mengirim kode pemberitahuan, dalam bentuk pesan WM_COMMAND, ke prosedur kotak dialog jendela pemilik. Kode pemberitahuan kotak daftar dikirim saat pengguna memilih, mengklik ganda, atau membatalkan item kotak daftar; saat kotak daftar menerima atau kehilangan fokus keyboard; dan ketika sistem tidak dapat mengalokasikan cukup memori untuk permintaan kotak daftar. Pesan WM_COMMAND berisi pengidentifikasi kotak daftar dalam kata dengan urutan rendah dari parameter wParam, dan kode pemberitahuan dalam kata dengan urutan tinggi. Parameter lParam berisi handle jendela kontrol.
Prosedur kotak dialog tidak diperlukan untuk memproses pesan ini; prosedur jendela default memprosesnya.
Aplikasi harus memantau dan memproses kode pemberitahuan kotak daftar berikut.
| Kode pemberitahuan | Deskripsi |
|---|---|
| LBN_DBLCLK | Pengguna mengklik dua kali item dalam kotak daftar. |
| LBN_ERRSPACE | Kotak daftar tidak dapat mengalokasikan cukup memori untuk memenuhi permintaan. |
| LBN_KILLFOCUS | Kotak daftar kehilangan fokus keyboard. |
| LBN_SELCANCEL | Pengguna membatalkan pilihan item dalam kotak daftar. |
| LBN_SELCHANGE | Pilihan dalam kotak daftar akan berubah. |
| LBN_SETFOCUS | Kotak daftar menerima fokus keyboard. |
Pesan ke Kotak Daftar
Prosedur kotak dialog bisa mengirim pesan ke kotak daftar untuk menambahkan, menghapus, memeriksa, dan mengubah item kotak daftar. Misalnya, prosedur kotak dialog dapat mengirim pesan LB_ADDSTRING ke kotak daftar untuk menambahkan item, dan pesan LB_GETSEL untuk menentukan apakah item dipilih. Pesan lain mengatur dan mengambil informasi tentang ukuran, tampilan, dan perilaku kotak daftar. Misalnya, pesan LB_SETHORIZONTALEXTENT mengatur lebar kotak daftar yang dapat digulir. Prosedur kotak dialog dapat mengirim pesan apa pun ke kotak daftar dengan menggunakan fungsi SendMessage atau SendDlgItemMessage.
Item kotak daftar sering dirujuk oleh indeks , bilangan bulat yang mewakili posisi item dalam kotak daftar. Indeks item pertama dalam kotak daftar adalah 0, indeks item kedua adalah 1, dan sebagainya.
Tabel berikut ini menjelaskan bagaimana prosedur kotak daftar yang telah ditentukan sebelumnya merespons pesan kotak daftar.
| Pesan | Jawaban |
|---|---|
| LB_ADDFILE | Menyisipkan file ke dalam kotak daftar direktori yang diisi oleh fungsi DlgDirList dan mengambil indeks kotak daftar item yang disisipkan. |
| LB_ADDSTRING | Menambahkan string ke kotak daftar dan mengembalikan indeksnya. |
| LB_DELETESTRING | Menghapus string dari kotak daftar dan mengembalikan jumlah string yang tetap ada dalam daftar. |
| LB_DIR | Menambahkan daftar nama file ke kotak daftar dan mengembalikan indeks nama file terakhir yang ditambahkan. |
| LB_FINDSTRING | Mengembalikan indeks string pertama dalam kotak daftar yang dimulai dengan string tertentu. |
| LB_FINDSTRINGEXACT | Mengembalikan indeks string dalam kotak daftar yang sama dengan string yang ditentukan. |
| LB_GETANCHORINDEX | Mengembalikan indeks item yang terakhir dipilih mouse. |
| LB_GETCARETINDEX | Mengembalikan indeks item yang memiliki persegi panjang fokus. |
| LB_GETCOUNT | Mengembalikan jumlah item dalam kotak daftar. |
| LB_GETCURSEL | Mengembalikan indeks item yang saat ini dipilih. |
| LB_GETHORIZONTALEXTENT | Mengembalikan lebar yang dapat digulir, dalam piksel, dari kotak daftar. |
| LB_GETITEMDATA | Mengembalikan nilai yang terkait dengan item yang ditentukan. |
| LB_GETITEMHEIGHT | Mengembalikan tinggi, dalam piksel, dari item dalam kotak daftar. |
| LB_GETITEMRECT | Mengambil koordinat klien dari item pada kotak daftar yang ditentukan. |
| LB_GETLOCALE | Mengambil lokal kotak daftar. Kata berurutan tinggi berisi kode negara/wilayah dan kata berurutan rendah berisi pengidentifikasi bahasa. |
| LB_GETSEL | Mengembalikan status pilihan item kotak daftar. |
| LB_GETSELCOUNT | Mengembalikan jumlah item terpilih dalam kotak daftar beberapa pilihan. |
| LB_GETSELITEMS | Membuat array indeks semua item yang dipilih dalam kotak daftar beberapa pilihan dan mengembalikan jumlah total item yang dipilih. |
| LB_GETTEXT | Mengambil string yang terkait dengan item tertentu dan juga panjang string tersebut. |
| LB_GETTEXTLEN | Mengembalikan panjang, dalam karakter, dari string yang terkait dengan item tertentu. |
| LB_GETTOPINDEX | Mengembalikan indeks item pertama yang terlihat dalam kotak daftar. |
| LB_INITSTORAGE | Mengalokasikan memori untuk jumlah item yang ditentukan dan string terkaitnya. |
| LB_INSERTSTRING | Menyisipkan string pada indeks tertentu dalam kotak daftar. |
| LB_ITEMFROMPOINT | Mengambil indeks berbasis nol dari item yang terdekat dengan titik yang ditentukan dalam kotak daftar. |
| LB_RESETCONTENT | Menghapus semua item dari kotak daftar. |
| LB_SELECTSTRING | Memilih string pertama yang ditemukan yang cocok dengan awalan tertentu. |
| LB_SELITEMRANGE | Memilih rentang item tertentu dalam kotak daftar. |
| LB_SELITEMRANGEEX | Memilih rentang item yang ditentukan jika indeks item pertama dalam rentang kurang dari indeks item terakhir dalam rentang. Membatalkan pilihan dalam rentang jika indeks item pertama lebih besar dari yang terakhir. |
| LB_SETANCHORINDEX | Menyetel item yang terakhir dipilih mouse ke item yang ditentukan. |
| LB_SETCARETINDEX | Mengatur persegi panjang fokus ke item kotak daftar tertentu. |
| LB_SETCOLUMNWIDTH | Mengatur lebar, dalam piksel, dari semua kolom dalam kotak daftar. |
| LB_SETCOUNT | Mengatur jumlah item dalam kotak daftar. |
| LB_SETCURSEL | Memilih item kotak daftar tertentu. |
| LB_SETHORIZONTALEXTENT | Mengatur lebar yang dapat digulir, dalam piksel, dari kotak daftar. |
| LB_SETITEMDATA | Mengaitkan nilai dengan item kotak daftar. |
| LB_SETITEMHEIGHT | Mengatur tinggi, dalam piksel, item atau beberapa item dalam kotak daftar. |
| LB_SETLOCALE | Mengatur lokal kotak daftar dan mengembalikan pengidentifikasi lokal sebelumnya. |
| LB_SETSEL | Memilih item dalam kotak daftar beberapa pilihan. |
| LB_SETTABSTOPS | Mengatur perhentian tab sesuai dengan yang ditentukan dalam array tertentu. |
| LB_SETTOPINDEX | Menggulir kotak daftar sehingga item yang ditentukan berada di bagian atas rentang yang terlihat. |
Pemrosesan Pesan Jendela Default
Prosedur jendela untuk kelas jendela kotak daftar yang telah ditentukan sebelumnya melakukan pemrosesan default untuk semua pesan yang tidak diproses kotak daftar. Saat prosedur kotak daftar mengembalikan FALSE untuk pesan, prosedur jendela yang telah ditentukan sebelumnya memeriksa pesan dan melakukan tindakan default, seperti yang diperlihatkan dalam tabel berikut.
| Pesan | Tindakan default |
|---|---|
| WM_CHAR | Memindahkan pilihan ke item pertama yang dimulai dengan karakter yang dititik pengguna. Jika kotak daftar memiliki gaya LBS_OWNERDRAW, tidak ada tindakan yang terjadi. Beberapa karakter yang diketik dalam interval singkat diperlakukan sebagai grup, dan item pertama yang dimulai dengan rangkaian karakter tersebut dipilih. |
| WM_CREATE | Membuat kotak daftar kosong. |
| WM_DESTROY | Menghancurkan kotak daftar dan membebaskan sumber daya apa pun yang digunakannya. |
| Meneruskan pesan ke prosedur kotak dialog atau proses jendela induk. | |
| WM_ENABLE | Jika kontrol terlihat, membuat persegi panjang tidak valid sehingga string dapat dicat abu-abu. |
| WM_ERASEBKGND | Menghapus latar belakang kotak daftar. Jika kotak daftar memiliki gaya LBS_OWNERDRAW, latar belakang tidak dihapus. |
| WM_GETDLGCODE | Mengembalikan DLGC_WANTARROWS | DLGC_WANTCHARS, menunjukkan bahwa prosedur kotak daftar default memproses tombol panah dan pesan WM_CHAR. |
| WM_GETFONT | Mengembalikan handle ke font saat ini untuk kotak pilihan. |
| WM_HSCROLL | Menggulir kotak daftar secara horizontal. |
| WM_KEYDOWN | Memproses kunci virtual untuk menggulir. Kunci virtual adalah indeks item untuk memindahkan tanda sisipan ke posisi yang ditentukan. Pilihan tidak diubah. |
| WM_KILLFOCUS | Mematikan kursor dan menghancurkannya. Mengirim kode pemberitahuan LBN_KILLFOCUS ke pemilik kotak daftar. |
| WM_LBUTTONDBLCLK | Melacak mouse di area kotak daftar klien. Ini memungkinkan pengguna untuk membatalkan pilihan jika tombol mouse dirilis di luar area klien kotak daftar. |
| WM_LBUTTONDOWN | Melacak mouse di area klien kotak daftar. Ini memungkinkan pengguna untuk membatalkan pilihan jika tombol mouse dirilis di luar area klien kotak daftar. |
| WM_LBUTTONUP | Melacak mouse di area klien kotak daftar. Ini memungkinkan pengguna untuk membatalkan pilihan jika tombol mouse dirilis di luar area klien kotak daftar. |
| WM_MOUSEMOVE | Melacak kursor mouse di area klien daftar kotak. Ini memungkinkan pengguna untuk membatalkan pilihan jika tombol mouse dirilis di luar area klien kotak daftar. |
| WM_PAINT | Melakukan operasi cat subkelas dengan menggunakan handel kotak daftar ke konteks perangkat (DC). |
| WM_SETFOCUS | Mengaktifkan kursor dan mengirim kode pemberitahuan LBN_SETFOCUS ke pemilik kotak pilihan. |
| WM_SETFONT | Mengatur font baru untuk kotak daftar. |
| WM_SETREDRAW | Mengatur atau menghapus tanda redraw berdasarkan nilai wParam. |
| WM_SIZE | Mengubah ukuran kotak daftar menjadi jumlah item integral. |
| WM_VSCROLL | Menggeser kotak daftar secara vertikal. |
Prosedur kotak daftar yang telah ditentukan sebelumnya meneruskan semua pesan lain keDefWindowProcuntuk pemrosesan default.
Kotak Daftar Owner-Drawn
Aplikasi dapat membuat kotak daftar yang digambar oleh aplikasi sendiri untuk bertanggung jawab menggambar item dalam daftar. Jendela induk atau kotak dialog kotak daftar yang digambar pemilik (pemiliknya) menerima pesan WM_DRAWITEM saat sebagian kotak daftar perlu dicat. Kotak daftar yang digambar secara kustom dapat mencantumkan informasi lain selain teks biasa.
Pemilik kotak daftar yang digambar pemilik harus memproses pesan WM_DRAWITEM. Pesan ini dikirim setiap kali sebagian kotak daftar harus digambar ulang. Pemilik mungkin perlu memproses pesan lain, tergantung pada gaya yang ditentukan untuk kotak daftar.
Aplikasi dapat membuat kotak daftar yang digambar pemilik dengan menentukan gaya LBS_OWNERDRAWFIXED atau LBS_OWNERDRAWVARIABLE. Jika semua item daftar dalam kotak daftar memiliki tinggi yang sama, seperti string atau ikon, aplikasi dapat menggunakan gaya LBS_OWNERDRAWFIXED. Jika item daftar memiliki tinggi yang bervariasi (misalnya, bitmap dengan ukuran yang berbeda) aplikasi dapat menggunakan gaya LBS_OWNERDRAWVARIABLE.
Pemilik kotak daftar yang digambar pemilik dapat memproses pesan WM_MEASUREITEM untuk menentukan dimensi item daftar. Jika aplikasi membuat kotak daftar dengan menggunakan gaya LBS_OWNERDRAWFIXED, sistem hanya mengirim pesan WM_MEASUREITEM sekali. Dimensi yang ditentukan oleh pemilik digunakan untuk semua item daftar. Jika gaya LBS_OWNERDRAWVARIABLE digunakan, sistem mengirim pesan WM_MEASUREITEM untuk setiap item daftar yang ditambahkan ke kotak daftar. Pemilik dapat menentukan atau mengatur tinggi item daftar kapan saja dengan menggunakan pesan LB_GETITEMHEIGHT dan LB_SETITEMHEIGHT.
Jika informasi yang ditampilkan dalam kotak daftar yang digambar pemilik menyertakan teks, aplikasi dapat melacak teks untuk setiap item daftar dengan menentukan gaya LBS_HASSTRINGS. Kotak daftar dengan gaya LBS_SORT diurutkan berdasarkan teks ini. Jika kotak daftar diurutkan, tetapi bukan gaya LBS_HASSTRINGS, pemilik harus memproses pesan WM_COMPAREITEM.
Dalam kotak daftar yang ditentukan oleh pemilik, pemilik harus melacak item daftar yang berisi informasi selain atau di samping teks. Salah satu cara yang nyaman untuk melakukan ini adalah dengan menyimpan handle ke informasi sebagai data item dengan menggunakan pesan LB_SETITEMDATA. Untuk membebaskan objek data yang terkait dengan item dalam kotak daftar, pemilik dapat memproses pesan WM_DELETEITEM.
Untuk contoh kotak daftar yang ditarik oleh pemilik, lihat Cara Membuat Kotak Daftar Owner-Drawn.
Seret Kotak Daftar Pilihan
Kotak daftar seret adalah tipe kotak daftar khusus yang memungkinkan pengguna menyeret item dari satu posisi ke posisi lainnya. Aplikasi dapat menggunakan kotak daftar seret untuk menampilkan string dalam urutan tertentu dan memungkinkan pengguna mengubah urutan dengan menyeret item ke posisi.
Membuat Kotak Daftar Tarik
Kotak daftar seret memiliki gaya tampilan yang sama dan memproses pesan yang sama dengan kotak daftar standar. Untuk membuat kotak daftar seret, pertama-tama buat kotak daftar standar lalu panggil fungsiMakeDragList. Untuk mengonversi kotak daftar dalam kotak dialog ke kotak daftar seret, Anda bisa memanggil MakeDragList saat pesan WM_INITDIALOG diproses.
Seret Pesan Kotak Daftar
Kotak daftar seret memberi tahu jendela induk peristiwa seret dengan mengirimkannya pesan daftar seret. Jendela induk harus memproses pesan dari daftar tarik.
Kotak daftar seret mendaftarkan pesan ini saat fungsi MakeDragList dipanggil. Untuk mendapatkan pengidentifikasi pesan (nilai numerik) dari pesan daftar yang diseret, panggil fungsi RegisterWindowMessage dan tentukan nilai DRAGLISTMSGSTRING.
Parameter wParam dari pesan drag list adalah pengidentifikasi kontrol untuk kotak drag list. Parameter lParam adalah alamat suatu struktur DRAGLISTINFO, yang berisi kode notifikasi untuk acara drag dan informasi lainnya. Nilai pengembalian pesan tergantung pada pemberitahuan.
Kode Pemberitahuan untuk Kotak Daftar Tarik
Kode pemberitahuan daftar seret, yang diidentifikasi oleh uNotification anggota strukturDRAGLISTINFO yang disertakan dengan pesan daftar seret, dapat DL_BEGINDRAG, DL_DRAGGING, DL_CANCELDRAG, atau DL_DROPPED.
Kode pemberitahuan DL_BEGINDRAG dikirim ketika kursor berada di item daftar dan pengguna mengklik tombol mouse kiri. Jendela induk dapat mengembalikan TRUE untuk memulai operasi seret atau FALSE untuk melarang penyeretan. Dengan cara ini, jendela induk dapat mengaktifkan penyeretan untuk beberapa item daftar dan menonaktifkannya untuk item lainnya. Anda dapat menentukan item daftar mana yang berada di lokasi yang ditentukan dengan menggunakan fungsiLBItemFromPt.
Jika penyeretan berlaku, kode pemberitahuan DL_DRAGGING dikirim setiap kali mouse dipindahkan, atau secara berkala jika mouse tidak dipindahkan. Jendela induk harus terlebih dahulu menentukan item daftar di bawah kursor dengan menggunakan LBItemFromPt lalu menggambar ikon sisipkan dengan menggunakan fungsiDrawInsert. Dengan menentukan TRUE untuk parameter bAutoScroll dari LBItemFromPt, Anda dapat menyebabkan kotak daftar menggulir satu baris jika kursor berada di atas atau di bawah area kliennya. Nilai yang Anda kembalikan pada notifikasi ini menentukan jenis kursor mouse yang harus diatur oleh kotak daftar seret.
Kode pemberitahuan DL_CANCELDRAG dikirim jika pengguna membatalkan operasi seret dengan mengklik tombol kanan mouse atau menekan tombol ESC. Kode pemberitahuan DL_DROPPED dikirim jika pengguna menyelesaikan operasi seret dengan melepaskan tombol mouse kiri, meskipun kursor tidak berada di atas item daftar. Kotak daftar seret melepaskan penangkapan mouse sebelum mengirimkan salah satu notifikasi. Nilai pengembalian dari kedua pemberitahuan ini diabaikan. Seret Daftar