Struktur LVITEMA (commctrl.h)

Artikel
08/22/2023

Menentukan atau menerima atribut item tampilan daftar. Struktur ini telah diperbarui untuk mendukung nilai masker baru (LVIF_INDENT) yang memungkinkan inden item. Struktur ini menggantikan struktur LV_ITEM .

Sintaks

typedef struct tagLVITEMA {
  UINT   mask;
  int    iItem;
  int    iSubItem;
  UINT   state;
  UINT   stateMask;
  LPSTR  pszText;
  int    cchTextMax;
  int    iImage;
  LPARAM lParam;
  int    iIndent;
  int    iGroupId;
  UINT   cColumns;
  PUINT  puColumns;
  int    *piColFmt;
  int    iGroup;
} LVITEMA, *LPLVITEMA;

Anggota

mask

Jenis: UINT

Kumpulan bendera yang menentukan anggota struktur ini mana yang berisi data yang akan diatur atau anggota mana yang diminta. Anggota ini dapat mengatur satu atau beberapa bendera berikut:

Nilai	Makna
LVIF_COLFMT	Windows Vista dan yang lebih baru. Anggota piColFmt valid atau harus diatur. Jika bendera ini digunakan, anggota cColumns valid atau harus diatur.
LVIF_COLUMNS	Anggota cColumns valid atau harus ditetapkan.
LVIF_DI_SETITEM	Sistem operasi harus menyimpan informasi item daftar yang diminta dan tidak memintanya lagi. Bendera ini hanya digunakan dengan kode pemberitahuan LVN_GETDISPINFO .
LVIF_GROUPID	Anggota iGroupId valid atau harus diatur. Jika bendera ini tidak diatur ketika pesan LVM_INSERTITEM dikirim, nilai iGroupId diasumsikan I_GROUPIDCALLBACK.
LVIF_IMAGE	Anggota iImage valid atau harus ditetapkan.
LVIF_INDENT	Anggota iIndent valid atau harus diatur.
LVIF_NORECOMPUTE	Kontrol tidak akan menghasilkan LVN_GETDISPINFO untuk mengambil informasi teks jika menerima pesan LVM_GETITEM . Sebaliknya, anggota pszText akan berisi LPSTR_TEXTCALLBACK.
LVIF_PARAM	Anggota lParam valid atau harus diatur.
LVIF_STATE	Anggota negara bagian valid atau harus ditetapkan.
LVIF_TEXT	Anggota pszText valid atau harus diatur.

iItem

Jenis: int

Indeks berbasis nol dari item yang dirujuk oleh struktur ini.

iSubItem

Jenis: int

Indeks berbasis satu dari subitem yang dirujuk struktur ini, atau nol jika struktur ini mengacu pada item daripada subitem.

state

Jenis: UINT

Menunjukkan status item, gambar status, dan gambar overlay. Anggota stateMask menunjukkan bit yang valid dari anggota ini.

Bit 0 hingga 7 dari anggota ini berisi bendera status item. Ini bisa menjadi satu atau beberapa nilai status item .

Bit 8 hingga 11 anggota ini menentukan indeks gambar overlay berbasis satu. Daftar gambar ikon berukuran penuh dan daftar gambar ikon kecil dapat memiliki gambar overlay. Gambar overlay ditumpokan di atas gambar ikon item. Jika bit ini nol, item tidak memiliki gambar overlay. Untuk mengisolasi bit ini, gunakan masker LVIS_OVERLAYMASK . Untuk mengatur indeks gambar overlay di anggota ini, Anda harus menggunakan makro INDEXTOOVERLAYMASK . Gambar overlay daftar gambar diatur dengan fungsi ImageList_SetOverlayImage .

Bit 12 hingga 15 dari anggota ini menentukan indeks gambar status. Gambar status ditampilkan di samping ikon item untuk menunjukkan status yang ditentukan aplikasi. Jika bit ini nol, item tidak memiliki gambar status. Untuk mengisolasi bit ini, gunakan masker LVIS_STATEIMAGEMASK . Untuk mengatur indeks gambar status, gunakan makro INDEXTOSTATEIMAGEMASK . Indeks gambar status menentukan indeks gambar dalam daftar gambar status yang harus digambar. Daftar gambar status ditentukan dengan pesan LVM_SETIMAGELIST .

stateMask

Jenis: UINT

Nilai yang menentukan bit anggota status mana yang akan diambil atau dimodifikasi. Misalnya, mengatur anggota ini ke LVIS_SELECTED hanya akan menyebabkan status pilihan item diambil.

Anggota ini memungkinkan Anda mengubah satu atau beberapa status item tanpa harus mengambil semua status item terlebih dahulu. Misalnya, mengatur anggota ini ke LVIS_SELECTED dan status ke nol akan menyebabkan status pemilihan item dibersihkan, tetapi tidak ada status lain yang akan terpengaruh.

Untuk mengambil atau mengubah semua status, atur anggota ini ke (UINT)-1.

Anda dapat menggunakan makro ListView_SetItemState untuk mengatur dan menghapus bit.

pszText

Jenis: LPTSTR

Jika struktur menentukan atribut item, pszText adalah penunjuk ke string yang dihentikan null yang berisi teks item. Saat menanggapi pemberitahuan LVN_GETDISPINFO , pastikan pointer ini tetap valid hingga setelah pemberitahuan berikutnya diterima.

Jika struktur menerima atribut item, pszText adalah penunjuk ke buffer yang menerima teks item. Perhatikan bahwa meskipun kontrol tampilan daftar memungkinkan string panjang apa pun disimpan sebagai teks item, hanya 259 TCHARs pertama yang ditampilkan.

Jika nilai pszText LPSTR_TEXTCALLBACK, item tersebut adalah item panggilan balik. Jika teks panggilan balik berubah, Anda harus secara eksplisit mengatur pszText ke LPSTR_TEXTCALLBACK dan memberi tahu kontrol tampilan daftar perubahan dengan mengirim pesan LVM_SETITEM atau LVM_SETITEMTEXT .

Jangan atur pszText ke LPSTR_TEXTCALLBACK jika kontrol tampilan daftar memiliki gaya LVS_SORTASCENDING atau LVS_SORTDESCENDING .

cchTextMax

Jenis: int

Jumlah TCHARdalam buffer yang diacu oleh pszText, termasuk NULL yang mengakhiri.

Anggota ini hanya digunakan ketika struktur menerima atribut item. Ini diabaikan ketika struktur menentukan atribut item. Misalnya, cchTextMax diabaikan selama LVM_SETITEM dan LVM_INSERTITEM. Ini baca-saja selama LVN_GETDISPINFO dan pemberitahuan LVN_ lainnya.

Catatan Jangan pernah menyalin lebih dari cchTextMaxTCHARs—di mana cchTextMax menyertakan NULL yang mengakhiri—ke pszText selama pemberitahuan LVN_, jika tidak, program Anda dapat gagal.

iImage

Jenis: int

Indeks ikon item dalam daftar gambar kontrol. Ini berlaku untuk daftar gambar besar dan kecil. Jika anggota ini adalah nilai I_IMAGECALLBACK, jendela induk bertanggung jawab untuk menyimpan indeks. Dalam hal ini, kontrol tampilan daftar mengirimkan kode pemberitahuan LVN_GETDISPINFO induk untuk mengambil indeks saat perlu menampilkan gambar.

lParam

Jenis: LPARAM

Nilai khusus untuk item. Jika Anda menggunakan pesan LVM_SORTITEMS , kontrol tampilan daftar meneruskan nilai ini ke fungsi perbandingan yang ditentukan aplikasi. Anda juga dapat menggunakan pesan LVM_FINDITEM untuk mencari kontrol tampilan daftar untuk item dengan nilai lParam tertentu.

iIndent

Jenis: int

Versi 4.70. Jumlah lebar gambar untuk mengindentasi item. Indentasi tunggal sama dengan lebar gambar item. Oleh karena itu, nilai 1 mengindentasi item dengan lebar satu gambar, nilai 2 inden dengan dua gambar, dan sebagainya. Perhatikan bahwa bidang ini hanya didukung untuk item. Mencoba mengatur indentasi subitem akan menyebabkan fungsi panggilan gagal.

iGroupId

Jenis: int

Versi 6.0 Pengidentifikasi grup tempat item berada, atau salah satu nilai berikut.

Nilai	Makna
I_GROUPIDCALLBACK	Kontrol tampilan daftar mengirimkan kode pemberitahuan LVN_GETDISPINFO induk untuk mengambil indeks grup.
I_GROUPIDNONE	Item bukan milik grup.

cColumns

Jenis: UINT

Versi 6.0 Jumlah kolom data (subitem) yang akan ditampilkan untuk item ini dalam tampilan petak peta. Nilai maksimum adalah 20. Jika nilai ini I_COLUMNSCALLBACK, ukuran array kolom dan array itu sendiri (puColumns) diperoleh dengan mengirim pemberitahuan LVN_GETDISPINFO .

puColumns

Jenis: PUINT

Versi 6.0 Penunjuk ke array indeks kolom, menentukan kolom mana yang ditampilkan untuk item ini, dan urutan kolom tersebut.

piColFmt

Jenis: int*

Windows Vista: Tidak diimplementasikan. Windows 7 dan yang lebih baru: Penunjuk ke array bendera berikut (sendiri atau dalam kombinasi), menentukan format setiap subitem dalam tampilan petak peta yang diperluas.

Nilai	Makna
LVCFMT_LINE_BREAK	Memaksa kolom untuk membungkus ke bagian atas daftar kolom berikutnya.
LVCFMT_FILL	Mengisi sisa area petak peta. Mungkin memiliki judul.
LVCFMT_WRAP	Memungkinkan kolom untuk membungkus dalam ruang yang tersisa dalam daftar kolomnya.
LVCFMT_NO_TITLE	Menghapus judul dari subitem.
LVCFMT_TILE_PLACEMENTMASK	Setara dengan kombinasi LVCFMT_LINE_BREAK dan LVCFMT_FILL.

iGroup

Jenis: int

Windows Vista: Indeks grup item. Hanya berlaku untuk data/panggilan balik pemilik (item tunggal dalam beberapa grup).

Keterangan

Struktur LVITEM digunakan dengan beberapa pesan, termasuk LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM, dan LVM_DELETEITEM.

Dalam tampilan petak peta, nama item ditampilkan di sebelah kanan ikon. Anda dapat menentukan subitem tambahan (terkait dengan kolom dalam tampilan detail), untuk ditampilkan pada baris di bawah nama item. Array puColumns berisi indeks subitem yang akan ditampilkan. Indeks harus lebih besar dari 0, karena subitem 0, nama item, sudah ditampilkan. Informasi kolom juga dapat diatur dalam struktur LVTILEINFO saat memodifikasi item daftar.

Misalnya kode, lihat Menggunakan Kontrol List-View.

Catatan Comctl32.dll versi 6 tidak dapat didistribusikan ulang tetapi disertakan dalam Windows atau yang lebih baru. Untuk menggunakan Comctl32.dll versi 6, tentukan dalam manifes. Untuk informasi selengkapnya tentang manifes, lihat Mengaktifkan Gaya Visual.

Catatan

Header commctrl.h mendefinisikan LVITEM sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Header	commctrl.h

Bagikan melalui

Struktur LVITEMA (commctrl.h)

Sintaks

Anggota

Keterangan

Persyaratan

Saran dan Komentar

Sumber Daya Tambahan: