Bagikan melalui


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

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