macro ListView_InsertItem (commctrl.h)

Article
10/24/2024

Insère un nouvel élément dans un contrôle d’affichage de liste. Vous pouvez utiliser cette macro ou envoyer explicitement le message LVM_INSERTITEM.

Syntaxe

int ListView_InsertItem(
         HWND     hwnd,
   const LPLVITEM pitem
);

Paramètres

hwnd

Type : HWND

Handle du contrôle list-view.

pitem

Type : const LPLVITEM

Pointeur vers une structure LVITEM qui spécifie les attributs de l’élément d’affichage de liste. Utilisez l'membre iItem pour spécifier l’index de base zéro auquel le nouvel élément doit être inséré. Si cette valeur est supérieure au nombre d’éléments actuellement contenus par le contrôle listview, le nouvel élément est ajouté à la fin de la liste et affecté l’index correct. Examinez la valeur de retour de la macro pour déterminer l’index réel affecté à l’élément.

Valeur de retour

Type : int

Retourne l’index du nouvel élément en cas de réussite, ou -1 sinon.

Remarques

Vous ne pouvez pas utiliser ListView_InsertItem ou LVM_INSERTITEM pour insérer des sous-éléments. Le membre iSubItem de la structure LVITEM doit être égal à zéro. Consultez LVM_SETITEM pour plus d’informations sur la définition des sous-éléments.

Si un contrôle d’affichage de liste a le style LVS_EX_CHECKBOXES défini, toute valeur placée dans les bits 12 à 15 de l’état membre de la structure LVITEM sera ignorée. Lorsqu’un élément est ajouté avec ce jeu de styles, il est toujours défini sur l’état non activé.

Si un contrôle d’affichage de liste a le style de fenêtre LVS_SORTASCENDING ou LVS_SORTDESCENDING, un message LVM_INSERTITEM échoue si vous essayez d’insérer un élément qui a LPSTR_TEXTCALLBACK en tant que membre pszText de sa structure LVITEM.

La macro ListView_InsertItem insère le nouvel élément à la position appropriée dans l’ordre de tri si les conditions suivantes contiennent :

Vous utilisez l’un des styles LVS_SORTXXX.
Vous n’utilisez pas le style LVS_OWNERDRAW.
Le membre pszText de la structure pointée par pitem n’est pas défini sur LPSTR_TEXTCALLBACK.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	commctrl.h

Partager via