ListView_InsertItem Makro (commctrl.h)

Artikel
10/24/2024

Fügt ein neues Element in ein Listenansicht-Steuerelement ein. Sie können dieses Makro verwenden oder die LVM_INSERTITEM Nachricht explizit senden.

Syntax

int ListView_InsertItem(
         HWND     hwnd,
   const LPLVITEM pitem
);

Parameter

hwnd

Typ: HWND-

Ein Handle für das Listenansicht-Steuerelement.

pitem

Typ: const LPLVITEM

Ein Zeiger auf eine LVITEM- Struktur, die die Attribute des Listenansichtselements angibt. Verwenden Sie das iItem Member, um den nullbasierten Index anzugeben, an dem das neue Element eingefügt werden soll. Wenn dieser Wert größer als die Anzahl der Elemente ist, die derzeit im Listenansichtssteuerelement enthalten sind, wird das neue Element am Ende der Liste angefügt und dem richtigen Index zugewiesen. Überprüfen Sie den Rückgabewert des Makros, um den tatsächlichen Index zu bestimmen, der dem Element zugewiesen ist.

Rückgabewert

Typ: int

Gibt den Index des neuen Elements zurück, wenn das Element erfolgreich verläuft oder andernfalls -1.

Bemerkungen

Sie können ListView_InsertItem oder LVM_INSERTITEM nicht zum Einfügen von Unterelementen verwenden. Das iSubItem- Mitglied der LVITEM--Struktur muss null sein. Informationen zum Festlegen von Unterelementen finden Sie unter LVM_SETITEM.

Wenn ein Listenansichtssteuerelement den LVS_EX_CHECKBOXES Formatvorlagensatz aufweist, werden alle Werte in Bits 12 bis 15 des Zustands Member der LVITEM--Struktur ignoriert. Wenn ein Element mit diesem Formatvorlagensatz hinzugefügt wird, wird es immer auf den nicht aktivierten Zustand festgelegt.

Wenn ein Listenansichtssteuerelement entweder das LVS_SORTASCENDING- oder LVS_SORTDESCENDING Fensterformat aufweist, schlägt eine LVM_INSERTITEM Nachricht fehl, wenn Sie versuchen, ein Element einzufügen, das als pszText-Element Element seiner LVITEM- Struktur LPSTR_TEXTCALLBACK hat.

Das ListView_InsertItem Makro fügt das neue Element an der richtigen Position in die Sortierreihenfolge ein, wenn die folgenden Bedingungen enthalten sind:

Sie verwenden eine der LVS_SORTXXX Formatvorlagen.
Sie verwenden die LVS_OWNERDRAW Formatvorlage nicht.
Das pszText- Element der Struktur, auf die Pitem- verweist, ist nicht auf LPSTR_TEXTCALLBACK festgelegt.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	commctrl.h

Freigeben über