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, kompilasi aplikasi sebagai Unicode atau gunakan kotak daftar yang digambar 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
- Kotak Daftar Yang Digambar Pemilik
- Seret Kotak Daftar
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 fungsi CreateWindowEx, menentukan kelas jendela WC_LISTBOX dan gaya kotak daftar yang sesuai.
Tipe 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.
Catatan
Untuk menggunakan gaya visual dengan kontrol ini, aplikasi harus menyertakan manifes dan harus memanggil InitCommonControls di awal program. Untuk informasi tentang gaya visual, lihat Gaya Visual. Untuk informasi tentang manifes, 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 , fungsi GetListBoxInfo 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 berurutan rendah dari parameter wParam , dan kode pemberitahuan dalam kata berurutan tinggi. Parameter lParam berisi handel 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 indeksnya, 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 | Respons |
|---|---|
| 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 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 panjang string. |
| 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 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 ke 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, membatalkan persegi panjang 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 handel ke font saat ini untuk kotak daftar. |
| WM_HSCROLL | Menggulir kotak daftar secara horizontal. |
| WM_KEYDOWN | Memproses kunci virtual untuk menggulir. Kunci virtual adalah indeks item untuk memindahkan tanda sisipan. Pilihan tidak diubah. |
| WM_KILLFOCUS | Mematikan tanda sisipan dan menghancurkannya. Mengirim kode pemberitahuan LBN_KILLFOCUS ke pemilik kotak daftar. |
| WM_LBUTTONDBLCLK | Melacak mouse di area klien kotak daftar. 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 mouse di area klien kotak daftar. 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 tanda sisipan dan mengirim kode pemberitahuan LBN_SETFOCUS ke pemilik kotak daftar. |
| WM_SETFONT | Mengatur font baru untuk kotak daftar. |
| WM_SETREDRAW | Mengatur atau menghapus bendera redraw berdasarkan nilai wParam. |
| WM_SIZE | Mengubah ukuran kotak daftar menjadi jumlah item integral. |
| WM_VSCROLL | Menggulir kotak daftar secara vertikal. |
Prosedur kotak daftar yang telah ditentukan sebelumnya meneruskan semua pesan lain ke DefWindowProc untuk pemrosesan default.
Kotak Daftar Yang Digambar Pemilik
Aplikasi dapat membuat kotak daftar yang digambar pemilik untuk bertanggung jawab atas pengecatan item 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 pemilik dapat mencantumkan informasi selain, atau selain, string teks.
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 digambar pemilik, pemilik harus melacak item daftar yang berisi informasi selain atau selain teks. Salah satu cara mudah untuk melakukan ini adalah dengan menyimpan handel 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 digambar pemilik, lihat Cara Membuat Kotak Daftar Yang Digambar Pemilik.
Seret Kotak Daftar
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 Seret
Kotak daftar seret memiliki gaya jendela yang sama dan proses pesan yang sama dengan kotak daftar standar. Untuk membuat kotak daftar seret, pertama-tama buat kotak daftar standar lalu panggil fungsi MakeDragList. 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 daftar seret.
Kotak daftar seret mendaftarkan pesan ini saat fungsi MakeDragList dipanggil. Untuk mengambil pengidentifikasi pesan (nilai numerik) dari pesan daftar seret, panggil fungsi RegisterWindowMessage dan tentukan nilai DRAGLISTMSGSTRING.
Parameter wParam dari pesan daftar seret adalah pengidentifikasi kontrol untuk kotak daftar seret. Parameter lParam adalah alamat struktur DRAGLISTINFO , yang berisi kode pemberitahuan untuk peristiwa seret dan informasi lainnya. Nilai pengembalian pesan tergantung pada pemberitahuan.
Seret Kode Pemberitahuan Kotak Daftar
Kode pemberitahuan daftar seret, yang diidentifikasi oleh anggota uNotification dari struktur DRAGLISTINFO 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 orang lain. Anda dapat menentukan item daftar mana yang berada di lokasi yang ditentukan dengan menggunakan fungsi LBItemFromPt.
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 fungsi DrawInsert. Dengan menentukan TRUE untuk parameter bAutoScroll LBItemFromPt, Anda dapat menyebabkan kotak daftar menggulir satu baris jika kursor berada di atas atau di bawah area kliennya. Nilai yang Anda kembalikan untuk pemberitahuan ini menentukan jenis kursor mouse yang harus diatur 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 merilis tombol mouse kiri, meskipun kursor bukan atas item daftar. Kotak daftar seret melepaskan tangkapan mouse sebelum mengirim salah satu pemberitahuan. Nilai pengembalian dari kedua pemberitahuan ini diabaikan. Seret Daftar