Partager via

À propos des contrôles List-View

  • Article

Consultez l’exemple de contrôle Listview virtuel.

Un contrôle list-view est une fenêtre qui affiche une collection d’éléments. Les contrôles list-view offrent plusieurs façons d’organiser et d’afficher des éléments et sont beaucoup plus flexibles que les simples zones de liste. Par exemple, des informations supplémentaires sur chaque élément peuvent être affichées dans des colonnes à droite de l’icône et de l’étiquette.

styles et affichages List-View

Les contrôles d’affichage de liste peuvent afficher des éléments dans cinq vues différentes. Le style de fenêtre du contrôle spécifie la vue par défaut. D’autres styles de fenêtre spécifient l’alignement des éléments et des fonctionnalités spécifiques aux contrôles. Le tableau suivant décrit les vues.

Nom de l'affichage Description
Affichage icône Spécifié par le style de fenêtre LVS_ICON ou en passant LV_VIEW_ICON avec le message LVM_SETVIEW . Chaque élément s'affiche sous forme d'une icône de taille normale, avec une étiquette placée au-dessous. L’utilisateur peut faire glisser les éléments vers n’importe quel emplacement dans la fenêtre d’affichage de liste.
Affichage d’icônes de petite taille Spécifié par le style de fenêtre LVS_SMALLICON ou en passant LV_VIEW_SMALLICON avec LVM_SETVIEW. Chaque élément apparaît sous la forme d’une petite icône avec l’étiquette à droite de celui-ci. L’utilisateur peut faire glisser les éléments vers n’importe quel emplacement.
Affichage Liste Spécifié par le style de fenêtre LVS_LIST ou en passant LV_VIEW_LIST avec LVM_SETVIEW. Chaque élément apparaît sous la forme d’une petite icône avec une étiquette à droite de celui-ci. Les éléments sont organisés en colonnes et l’utilisateur ne peut pas les faire glisser vers un emplacement arbitraire.
Vue Rapport (détails) Spécifié par le style de fenêtre LVS_REPORT ou en passant LV_VIEW_DETAILS avec LVM_SETVIEW. Chaque élément s’affiche sur sa propre ligne, avec des informations organisées en colonnes. La colonne la plus à gauche est toujours justifiée à gauche et contient la petite icône et l’étiquette. Les colonnes suivantes contiennent des sous-éléments spécifiés par l’application. Chaque colonne a un en-tête, sauf si vous spécifiez également le style de fenêtre LVS_NOCOLUMNHEADER .
Mode Mosaïque Version 6 et ultérieure. Spécifié en transmettant LV_VIEW_TILE avec LVM_SETVIEW. Chaque élément apparaît sous la forme d’une icône de taille réelle avec une étiquette d’une ou plusieurs lignes à côté.

 

Les captures d’écran suivantes utilisent des vues pour afficher différentes quantités d’informations sur chacun des sept animaux de compagnie. Les vues montrent comment les informations peuvent apparaître sur Windows Vista. Les styles visuels du contrôle ont été définis sur le thème « Explorer » à l’aide de SetWindowTheme.

La capture d’écran suivante montre l’affichage des détails.

capture d’écran montrant des informations dans cinq colonnes et sept lignes

La capture d’écran suivante montre l’affichage des icônes.

capture d’écran qui montre uniquement le nom de chaque animal et une icône indiquant l’espèce

La capture d’écran suivante montre l’affichage liste.

capture d’écran qui montre, pour chaque animal de compagnie, une grande icône à côté du texte du nom, de la race et du prix de l’animal

La capture d’écran suivante montre la vue mosaïque.

vue mosaïque.

Vous pouvez modifier le type d’affichage après avoir créé un contrôle d’affichage de liste. Pour récupérer et modifier le style de fenêtre, utilisez les fonctions GetWindowLong et SetWindowLong . Pour déterminer les styles de fenêtre de l’affichage actuel, utilisez la valeur LVS_TYPEMASK .

Vous pouvez contrôler la façon dont les éléments sont organisés dans une icône ou une petite vue icône en spécifiant le LVS_ALIGNTOP (par défaut) ou LVS_ALIGNLEFT style de fenêtre.

Vous pouvez modifier l’alignement après avoir créé un contrôle d’affichage de liste. Pour déterminer l’alignement actuel, utilisez la valeur LVS_ALIGNMASK .

D’autres styles de fenêtre fournissent d’autres options, telles que la possibilité pour un utilisateur de modifier des étiquettes ou de sélectionner plusieurs éléments à la fois. Pour obtenir la liste complète, consultez Styles de fenêtre List-View.

Styles List-View étendus

Les styles de contrôle d’affichage de liste étendus fournissent des options telles que des zones de case activée, des barres de défilement plates, des lignes de grille et un suivi à chaud. Pour obtenir la liste complète, consultez Styles List-View étendus. Vous n’accédez pas aux styles d’affichage de liste étendus de la même manière que les styles de fenêtre standard. Vous n’utilisez pas les fonctions GetWindowLong et SetWindowLong pour apporter des modifications de style étendues.

Il existe deux messages qui définissent et récupèrent des informations de style étendu, LVM_SETEXTENDEDLISTVIEWSTYLE et LVM_GETEXTENDEDLISTVIEWSTYLE. Au lieu d’envoyer les messages explicitement, vous pouvez utiliser les macros correspondantes suivantes : ListView_SetExtendedListViewStyle, ListView_SetExtendedListViewStyleEx et ListView_GetExtendedListViewStyle.

Style de List-View virtuel

Une vue de liste virtuelle est un contrôle list-view qui a le style LVS_OWNERDATA . Ce style permet au contrôle de gérer des millions d’éléments, car le propriétaire reçoit la charge de la gestion des données d’élément. Cela vous permet d’utiliser le contrôle d’affichage de liste virtuel avec de grandes bases de données d’informations, où des méthodes spécifiques d’accès aux données sont déjà en place.

Un contrôle d’affichage de liste virtuel conserve très peu d’informations sur les éléments lui-même. À l’exception de la sélection d’élément et des informations de focus, le propriétaire du contrôle doit gérer toutes les informations d’élément. D’autres processus demandent des informations d’élément au propriétaire à l’aide de LVN_GETDISPINFO codes de notification.

Étant donné que ce type de contrôle de liste est destiné aux jeux de données volumineux, il est recommandé de mettre en cache les données d’élément demandées pour améliorer les performances de récupération. L’affichage liste fournit un mécanisme d’indication de cache pour faciliter l’optimisation du cache. L’indicateur est implémenté sous la forme d’un code de notification LVN_ODCACHEHINT .

Création d’un contrôle List-View virtuel

Vous créez des contrôles d’affichage de liste virtuelle à l’aide de la fonction CreateWindow ou CreateWindowEx , en spécifiant le style de fenêtre LVS_OWNERDATA dans le cadre du paramètre de fonction dwStyle . Le basculement dynamique vers et depuis le style LVS_OWNERDATA n’est pas pris en charge.

Vous pouvez utiliser le style LVS_OWNERDATA en combinaison avec la plupart des autres styles de fenêtre, à l’exception du style LVS_SORTASCENDING ou LVS_SORTDESCENDING . Tous les contrôles d’affichage de liste virtuelle sont par défaut au style LVS_AUTOARRANGE .

Pour permettre l’affichage des éléments dans la liste, vous devez d’abord envoyer le message LVM_SETITEMCOUNT , soit explicitement, soit à l’aide de la macro ListView_SetItemCountEx .

Les messages suivants ne sont pas pris en charge sous le style LVS_OWNERDATA : LVM_ENABLEGROUPVIEW, LVM_GETITEMTEXT, LVM_SETTILEINFO et LVM_MAPIDTOINDEX.

Problèmes de compatibilité

Les quatre styles d’affichage de liste (icône, petite icône, liste et affichage rapport) prennent en charge le style LVS_OWNERDATA . Les contrôles d’affichage de liste qui ont le style LVS_OWNERDATA ne stockent aucune information spécifique à l’élément. Par conséquent, les seuls indicateurs d’état d’élément valides que vous pouvez appliquer à un élément sont LVIS_SELECTED et LVIS_FOCUSED. Aucune autre information d’état n’est stockée. En particulier, le contrôle d’affichage de liste ne conserve pas d’images d’état ou de superposition pour chaque élément. Toutefois, vous pouvez demander au contrôle d’affichage de liste d’interroger votre application pour ces images en lui envoyant un message LVM_SETCALLBACKMASK .

La plupart des messages de contrôle list-view et les macros associées sont entièrement pris en charge. Toutefois, certains messages présentent des limitations ou ne sont pas pris en charge lorsque vous utilisez le style LVS_OWNERDATA . Le tableau suivant récapitule les messages affectés.

Message Limitation
LVM_ARRANGE Ne prend pas en charge le style LVA_SNAPTOGRID .
LVM_DELETEALLITEMS Définit le nombre d’éléments sur zéro et efface toutes les variables de sélection internes, mais il ne supprime pas réellement d’éléments. Elle effectue un rappel de notification.
LVM_DELETEITEM Est pris en charge uniquement pour l’intégrité de la sélection et ne supprime pas réellement un élément.
LVM_GETITEMSTATE Retourne uniquement les états de focus et de sélection (c’est-à-dire les états stockés par le contrôle d’affichage de liste).
LVM_GETNEXTITEM Ne prend pas en charge les critères de recherche d’affichage de liste LVNI_CUT, LVNI_HIDDEN ou LVNI_DROPHILITED. Tous les autres critères sont pris en charge.
LVM_GETWORKAREAS Non prise en charge.
LVM_INSERTITEM Est pris en charge uniquement pour l’intégrité de la sélection.
LVM_SETITEM Non prise en charge. Pour définir l’état de l’élément, utilisez le message ListView_SetItemState .
LVM_SETITEMCOUNT Définit le nombre d’éléments actuellement dans la liste. Si le contrôle d’affichage de liste envoie une notification qui demande des données pour n’importe quel élément jusqu’à l’ensemble maximal, le propriétaire doit être prêt à fournir ces données. Les paramètres de message prennent en charge les contrôles d’affichage de liste virtuel.
LVM_SETITEMPOSITION Non prise en charge.
LVM_SETITEMSTATE Autorise uniquement la modification des états de sélection et de focus pour l’élément.
LVM_SETITEMTEXT Non prise en charge. Il incombe à l’application de conserver les textes des éléments.
LVM_SETWORKAREAS Non prise en charge.
LVM_SORTITEMS Non prise en charge. Il incombe à l’application de présenter les éléments dans l’ordre souhaité.

 

Gestion des codes de notification de contrôle de List-View virtuel

Les contrôles d’affichage de liste avec le style LVS_OWNERDATA envoient les mêmes codes de notification que les autres contrôles d’affichage de liste et deux autres : LVN_ODCACHEHINT et LVN_ODFINDITEM. Voici les notifications les plus courantes envoyées par le contrôle d’affichage de liste avec le style LVS_OWNERDATA .

Notification Description
LVN_GETDISPINFO Un contrôle d’affichage de liste virtuel conserve très peu d’informations sur les éléments par lui-même. Par conséquent, il envoie souvent le code de notification LVN_GETDISPINFO pour demander des informations sur l’élément. Ce message est géré de la même façon que les éléments de rappel dans un contrôle de liste standard. Étant donné que le nombre d’éléments pris en charge par le contrôle peut être très élevé, la mise en cache des données d’élément améliore les performances. Lors de la gestion des LVN_GETDISPINFO, le propriétaire du contrôle tente d’abord de fournir les informations d’élément demandées à partir du cache (pour plus d’informations, consultez Gestion du cache). Si l’élément demandé n’est pas mis en cache, le propriétaire doit être prêt à fournir les informations par d’autres moyens.
LVN_ODCACHEHINT Un affichage de liste virtuelle envoie le code de notification LVN_ODCACHEHINT pour vous aider à optimiser le cache. Le code de notification fournit des valeurs d’index inclusives pour une plage d’éléments qu’il recommande de mettre en cache. Lors de la réception du code de notification, le propriétaire doit être prêt à charger le cache avec les informations d’élément pour la plage demandée afin que les informations soient facilement disponibles lorsqu’un message LVN_GETDISPINFO est envoyé.
LVN_ODFINDITEM Le code de notification LVN_ODFINDITEM est envoyé par un contrôle d’affichage de liste virtuel lorsque le contrôle a besoin que le propriétaire trouve un élément de rappel particulier. Le code de notification est envoyé lorsque le contrôle d’affichage de liste reçoit un accès rapide à la clé ou lorsqu’il reçoit un message LVM_FINDITEM . Les informations de recherche sont envoyées sous la forme d’une structure LVFINDINFO , qui est membre de la structure NMLVFINDITEM . Le propriétaire doit être prêt à rechercher un élément qui correspond aux informations fournies par le contrôle d’affichage de liste. Le propriétaire retourne l’index de l’élément en cas de réussite, ou -1 si aucun élément correspondant n’est trouvé.

 

Gestion du cache

Un contrôle d’affichage de liste avec le style LVS_OWNERDATA produit un grand nombre de codes de notification LVN_GETDISPINFO et, pour faciliter l’optimisation du cache, un message LVN_ODCACHEHINT . LVN_ODCACHEHINT messages fournissent des informations sur les éléments recommandés à inclure dans le cache. Ces messages sont envoyés en tant que messages WM_NOTIFY , la valeur lParam faisant office d’adresse d’une structure NMLVCACHEHINT .

La structure NMLVCACHEHINT comprend deux membres entiers, iFrom et iTo, qui représentent les points de terminaison inclusifs d’une plage d’éléments qui seront probablement nécessaires. Le propriétaire doit être prêt à charger le cache avec les informations d’élément pour chacun des éléments dans la plage recommandée.

Le contrôle de liste a souvent besoin d’informations sur l’élément pour le premier élément (décalage 0). Le code de notification LVN_ODCACHEHINT peut ne pas toujours inclure l’élément 0, mais il doit toujours être inclus dans le cache.

Les derniers éléments de la liste sont souvent consultés. Par conséquent, le propriétaire peut vouloir conserver un deuxième cache qui inclut les éléments à la fin de la liste. La plage demandée de LVN_ODCACHEHINT peut être vérifiée par rapport au cache de fin pour le rendre disponible automatiquement au lieu de recharger la même plage de terminaison à chaque fois.

List-View zones de travail

Les contrôles d’affichage de liste prennent en charge les zones de travail, qui sont des zones virtuelles rectangulaires que le contrôle d’affichage de liste utilise pour organiser ses éléments. Une zone de travail n’est pas une fenêtre et ne peut pas avoir de bordure visible. Par défaut, le contrôle list-view n’a aucune zone de travail. En créant une zone de travail, vous pouvez créer une bordure vide à gauche, en haut ou à droite des éléments ou afficher une barre de défilement horizontale quand il n’y en a pas normalement.

Lorsqu’une zone de travail est créée, les éléments qui se trouvent dans la zone de travail deviennent membres de la zone de travail. De même, si un élément est déplacé dans une zone de travail, l’élément devient membre de cette zone de travail. Si un élément ne se trouve dans aucune zone de travail, il devient automatiquement membre de la première zone de travail (index 0). Pour placer un nouvel élément dans une zone de travail spécifique, vous devez d’abord créer l’élément, puis utiliser le LVM_SETITEMPOSITION ou le message LVM_SETITEMPOSITION32 pour le déplacer dans la zone de travail souhaitée.

L’illustration suivante est un exemple de contrôle d’affichage de liste qui contient quatre zones de travail, chacune dans un quadrant différent de la zone cliente.

capture d’écran d’un contrôle d’affichage de liste avec une zone de travail dans chaque quadrant de la zone cliente

Plusieurs zones de travail peuvent être utilisées pour créer différentes zones dans une même vue. Vous pouvez créer des zones dans une seule vue qui ont des significations différentes. Par exemple, une vue d’un système de fichiers peut avoir une zone pour les fichiers en lecture/écriture et une autre zone pour les fichiers en lecture seule. L’utilisateur peut classer les éléments en les plaçant dans différentes zones de travail. Si un fichier est déplacé dans la zone en lecture seule, il devient automatiquement en lecture seule.

Plusieurs zones de travail peuvent se croiser, mais tous les éléments qui se trouvent dans l’intersection deviennent membres de la zone avec l’index inférieur ; il est donc préférable d’éviter cette situation. Lors du tri de plusieurs zones de travail, les éléments sont triés par rapport aux autres éléments de la même zone de travail.

Le nombre de zones de travail peut être récupéré avec le message LVM_GETNUMBEROFWORKAREAS . Les zones de travail sont modifiées avec le message LVM_SETWORKAREAS et peuvent être récupérées avec le message LVM_GETWORKAREAS . Ces deux messages prennent l’adresse d’un tableau de structures RECT comme lParam et le nombre de structures RECT comme wParam. Les membres gauche et supérieur de ces structures spécifient les coordonnées de l’angle supérieur gauche (l’origine) de la zone de travail, et les membres de droite et inférieur spécifient l’angle inférieur droit de la zone de travail. Toutes les coordonnées se trouvent dans les coordonnées client de l’affichage de liste. Le nombre maximal de zones de travail autorisées est défini par la valeur LV_MAX_WORKAREAS .

La modification de la zone de travail n’a aucun effet sur les contrôles d’affichage de liste qui ont la vue LVS_LIST ou LVS_REPORT , mais les zones de travail sont conservées lorsque le type d’affichage est modifié. Avec les vues LVS_ICON et LVS_SMALLICON , la zone de travail peut être modifiée pour modifier la façon dont les éléments sont affichés. En rendant la largeur de la zone de travail (de droite à gauche) supérieure à la largeur du client du contrôle, les éléments sont encapsulés à cette largeur et la barre de défilement horizontale s’affiche. En rendant la largeur de la zone de travail plus étroite que la largeur de la zone cliente du contrôle, les éléments sont encapsulés dans la zone de travail et non dans la zone cliente. Si vous définissez le membre gauche ou supérieur sur une valeur positive, les éléments sont affichés à partir de la zone de travail, ce qui crée un espace vide entre le bord du contrôle et les éléments. Un espace vide peut également être créé entre le bord droit du contrôle et les éléments en rendant la largeur de la zone de travail inférieure à la largeur du client du contrôle.

List-View Listes d’images

Par défaut, un contrôle d’affichage de liste n’affiche pas d’images d’élément. Pour afficher des images d’élément, vous devez créer des listes d’images et les associer au contrôle . Un contrôle d’affichage de liste peut avoir trois listes d’images :

  • Liste d’images qui contient des icônes de taille réelle affichées lorsque le contrôle est en mode Icône.
  • Liste d’images qui contient de petites icônes affichées lorsque le contrôle est en mode petite icône, en mode liste ou en mode rapport.
  • Liste d’images qui contient des images d’état, qui sont affichées à gauche de l’icône de taille réelle ou petite. Vous pouvez utiliser des images d’état, telles que des zones de case activée activées et désactivées, pour indiquer les états d’élément définis par l’application. Les images d’état sont affichées en mode icône, en mode petite icône, en mode liste et en mode rapport.

Les listes d’images d’icônes de taille réelle et de petite taille peuvent également contenir des images superposées, qui sont conçues pour être dessinées en toute transparence sur les icônes d’élément.

Pour utiliser des images superposées dans un contrôle d’affichage de liste :

  1. Appelez la fonction ImageList_SetOverlayImage pour affecter un index d’image de superposition à une image dans les listes d’images d’icônes de taille réelle et de petite taille. Une image superposée est identifiée par un index de base unique.
  2. Vous pouvez associer un index d’image de superposition à un élément lorsque vous appelez la macro ListView_InsertItem ou ListView_SetItem . Utilisez la macro INDEXTOOVERLAYMASK pour spécifier un index d’image de superposition dans le membre d’état de la structure LVITEM de l’élément. Vous devez également définir le LVIS_OVERLAYMASK bits dans le membre stateMask .

Si une liste d’images d’état est spécifiée, un contrôle d’affichage de liste réserve de l’espace à gauche de l’icône de chaque élément pour une image d’état.

Pour associer une image d’état à un élément, utilisez la macro INDEXTOSTATEIMAGEMASK pour spécifier un index d’image d’état dans le membre d’état de la structure LVITEM . L’index identifie une image dans la liste des images d’état du contrôle. Bien que les index de liste d’images soient de base zéro, le contrôle utilise des index de base unique pour identifier les images d’état. Un index d’image d’état égal à zéro indique qu’un élément n’a pas d’image d’état.

Par défaut, lorsqu’un contrôle d’affichage de liste est détruit, il détruit les listes d’images qui lui sont affectées. Toutefois, si un contrôle d’affichage de liste a le style de fenêtre LVS_SHAREIMAGELISTS , l’application est responsable de la destruction des listes d’images lorsqu’elles ne sont plus utilisées. Vous devez spécifier ce style si vous affectez les mêmes listes d’images à plusieurs contrôles d’affichage de liste ; sinon, plusieurs contrôles peuvent tenter de détruire la même liste d’images.

List-View éléments et sous-éléments

Chaque élément d’un contrôle d’affichage de liste a une icône, une étiquette, un état actuel et une valeur définie par l’application. En utilisant des messages d’affichage de liste, vous pouvez ajouter, modifier et supprimer des éléments, ainsi que récupérer des informations sur les éléments.

Chaque élément peut avoir un ou plusieurs sous-éléments. Un sous-élément est une chaîne qui, en mode Rapport, s’affiche dans une colonne distincte de l’icône et de l’étiquette de l’élément. Pour spécifier le texte d’un sous-élément, utilisez le message LVM_SETITEMTEXT ou LVM_SETITEM . Tous les éléments d’un contrôle d’affichage de liste ont le même nombre de sous-éléments. Le nombre de sous-éléments est déterminé par le nombre de colonnes dans le contrôle list-view. Lorsque vous ajoutez une colonne à un contrôle list-view, vous spécifiez son index sous-élément associé.

La structure LVITEM définit un élément ou un sous-élément d’affichage de liste. Le membre iItem est l’index de base zéro de l’élément. Le membre iSubItem est l’index de base un d’un sous-élément ou zéro si la structure contient des informations sur un élément. D’autres membres spécifient le texte, l’icône, l’état et les données de l’élément. Les données d’élément sont une valeur définie par l’application associée à un élément d’affichage de liste.

Pour ajouter un élément à un contrôle list-view, utilisez le message LVM_INSERTITEM , en spécifiant l’adresse d’une structure LVITEM . Avant d’ajouter plusieurs éléments, vous pouvez envoyer au contrôle un message LVM_SETITEMCOUNT , en spécifiant le nombre d’éléments qu’il contiendra finalement. Ce message permet au contrôle d’affichage de liste de réallouer ses structures de données internes une seule fois plutôt que chaque fois que vous ajoutez un élément. Vous pouvez déterminer le nombre d’éléments dans un contrôle d’affichage de liste à l’aide du message LVM_GETITEMCOUNT . Si vous ajoutez un grand nombre d’éléments à un contrôle d’affichage de liste, vous pouvez accélérer le processus en désactivant le redessinage avant d’ajouter les éléments, puis en activant le redessinage après l’ajout des éléments. Utilisez le message WM_SETREDRAW pour activer et désactiver le redessinage.

Pour modifier les attributs d’un élément d’affichage de liste, utilisez le message LVM_SETITEM en spécifiant l’adresse d’une structure LVITEM . Le membre mask de cette structure spécifie les attributs d’élément que vous souhaitez modifier. Par exemple, pour modifier uniquement le texte d’un élément ou d’un sous-élément, utilisez le message LVM_SETITEMTEXT .

Pour récupérer des informations sur un élément d’affichage de liste, utilisez le message LVM_GETITEM , en spécifiant l’adresse de la structure LVITEM à remplir. Le membre mask de cette structure spécifie les attributs d’élément à récupérer. Pour récupérer uniquement le texte d’un élément ou d’un sous-élément, utilisez le message LVM_GETITEMTEXT .

Pour supprimer un élément d’affichage de liste, utilisez le message LVM_DELETEITEM . Vous pouvez supprimer tous les éléments d’un contrôle d’affichage de liste à l’aide du message LVM_DELETEALLITEMS .

List-View États de l’élément

L’état d’un élément est une valeur qui spécifie la disponibilité de l’élément, indique les actions de l’utilisateur ou reflète d’une autre manière la status de l’élément. Un contrôle d’affichage de liste modifie certains bits d’état, par exemple lorsque l’utilisateur sélectionne un élément. Une application peut modifier d’autres bits d’état pour désactiver ou masquer l’élément ou pour spécifier une image de superposition ou une image d’état. Pour plus d’informations sur les images superposées et les images d’état, consultez Listes d’images d’affichage de liste.

L’état d’un élément est spécifié par le membre d’état de la structure LVITEM . Lorsque vous spécifiez ou modifiez l’état d’un élément, le membre stateMask spécifie les bits d’état que vous devez modifier. Vous pouvez modifier l’état d’un élément à l’aide du message LVM_SETITEMSTATE . Vous pouvez spécifier l’état d’un élément lorsque vous le créez ou lorsque vous modifiez ses attributs à l’aide du message LVM_SETITEM . Pour déterminer l’état actuel d’un élément, utilisez le message LVM_GETITEMSTATE ou LVM_GETITEM .

Pour définir l’image de superposition d’un élément, le membre stateMask de la structure LVITEM doit inclure la valeur LVIS_OVERLAYMASK , et le membre d’état doit inclure l’index de base unique de l’image de superposition décalée de 8 bits vers la gauche à l’aide de la macro INDEXTOOVERLAYMASK . L’index peut être égal à zéro pour ne spécifier aucune image superposée.

Pour définir l’image d’état d’un élément, le membre stateMask de la structure LVITEM doit inclure la valeur LVIS_STATEIMAGEMASK , et le membre d’état doit inclure l’index de base unique de l’image d’état décalée de 12 bits vers la gauche à l’aide de la macro INDEXTOSTATEIMAGEMASK . L’index peut être égal à zéro pour ne spécifier aucune image d’état.

Éléments de rappel et masque de rappel

Pour chacun de ses éléments, un contrôle d’affichage de liste stocke généralement le texte de l’étiquette, l’index de liste d’images des icônes de l’élément et un ensemble d’indicateurs de bits pour l’état de l’élément. Vous pouvez définir des éléments de rappel ou modifier le masque de rappel du contrôle pour indiquer que l’application, plutôt que le contrôle, stocke tout ou partie de ces informations. Vous pouvez utiliser des rappels si votre application stocke certaines de ces informations.

Un élément de rappel dans un contrôle d’affichage de liste est un élément pour lequel l’application stocke l’index de texte ou d’icône, ou les deux. Vous pouvez définir des éléments de rappel lorsque vous envoyez le message LVM_INSERTITEM pour ajouter un élément au contrôle d’affichage de liste. Si l’application stocke le texte de l’élément ou du sous-élément, définissez le membre pszText de la structure LVITEM de l’élément sur LPSTR_TEXTCALLBACK. Si l’application stocke l’index d’icône d’un élément, définissez le membre iImage de la structure LVITEM de l’élément sur I_IMAGECALLBACK.

Le masque de rappel d’un contrôle d’affichage de liste est un ensemble d’indicateurs de bits qui spécifient les états d’élément pour lesquels l’application, plutôt que le contrôle, stocke les données actuelles. Le masque de rappel s’applique à tous les éléments du contrôle, contrairement à la désignation d’élément de rappel qui s’applique à un élément spécifique. Le masque de rappel est égal à zéro par défaut, ce qui signifie que le contrôle d’affichage de liste stocke toutes les informations sur l’état de l’élément. Après avoir créé un contrôle d’affichage de liste et initialisé ses éléments, vous pouvez envoyer le message LVM_SETCALLBACKMASK pour modifier le masque de rappel. Pour récupérer le masque de rappel actuel, envoyez le message LVM_GETCALLBACKMASK .

Lorsqu’un contrôle d’affichage de liste doit afficher ou trier un élément d’affichage de liste pour lequel l’application stocke des informations de rappel, le contrôle envoie le code de notification LVN_GETDISPINFO à la fenêtre parente du contrôle. Ce message spécifie une structure NMLVDISPINFO qui contient le type d’informations requises et identifie l’élément ou le sous-élément à récupérer. La fenêtre parente doit traiter LVN_GETDISPINFO pour fournir les données demandées.

Si le contrôle d’affichage de liste détecte une modification dans les informations de rappel d’un élément, comme une modification du texte, de l’icône ou des informations d’état, le contrôle envoie un code de notification LVN_SETDISPINFO pour vous informer de la modification.

Si vous modifiez les attributs ou les bits d’état d’un élément de rappel, vous utilisez le message LVM_UPDATE pour forcer le contrôle à repeindre l’élément. Ce message oblige également le contrôle à organiser ses éléments s’il a le style LVS_AUTOARRANGE . Vous pouvez utiliser le message LVM_REDRAWITEMS pour redessiner une plage d’éléments en invalidant les parties correspondantes de la zone cliente du contrôle d’affichage de liste.

En utilisant efficacement les éléments de rappel et le masque de rappel, vous pouvez vous assurer que chaque attribut d’élément est conservé dans un seul emplacement. Cela peut simplifier votre application, mais le seul espace enregistré est la mémoire qui serait autrement nécessaire pour stocker les étiquettes d’élément et le texte sous-élément.

List-View position de l’élément

Chaque élément d’affichage de liste a une position et une taille, que vous pouvez récupérer et définir à l’aide de messages. Vous pouvez également déterminer quel élément, le cas échéant, se trouve à une position spécifiée. La position des éléments d’affichage de liste est spécifiée dans les coordonnées d’affichage, qui sont des coordonnées clientes décalées par la position de défilement.

Pour récupérer et définir la position d’un élément, utilisez les messages LVM_GETITEMPOSITION et LVM_SETITEMPOSITION . LVM_GETITEMPOSITION fonctionne pour tous les affichages, mais LVM_SETITEMPOSITION fonctionne uniquement pour les vues icônes et petites icônes.

Vous pouvez déterminer quel élément, le cas échéant, se trouve à un emplacement particulier à l’aide du message LVM_HITTEST .

Pour récupérer le rectangle englobant d’un élément de liste ou uniquement pour son icône ou son étiquette, utilisez le message LVM_GETITEMRECT .

Organisation, tri et recherche d’éléments

Vous pouvez utiliser des messages d’affichage de liste pour organiser et trier des éléments et rechercher des éléments en fonction de leurs attributs ou positions. L’organisation repositionne les éléments pour les aligner sur une grille, mais les index des éléments ne changent pas. Le tri modifie la séquence d’éléments (et leurs index correspondants), puis les repositionne en conséquence. Vous pouvez organiser les éléments uniquement dans les icônes et les petites icônes, mais vous pouvez trier les éléments dans n’importe quel affichage. Pour rechercher des éléments, vous envoyez des messages d’affichage de liste qui spécifient un emplacement ou une propriété d’élément.

Pour organiser les éléments, utilisez le message LVM_ARRANGE . Vous pouvez vous assurer que les éléments sont organisés à tout moment en spécifiant le style de fenêtre LVS_AUTOARRANGE .

Pour trier des éléments, utilisez le message LVM_SORTITEMS . Lorsque vous triez à l’aide de ce message, vous spécifiez une fonction de rappel définie par l’application que le contrôle list-view appelle pour comparer l’ordre relatif de deux éléments. Le contrôle transmet à la fonction de comparaison les données d’élément associées à chacun des deux éléments. Les données d’élément sont la valeur spécifiée dans le membre lParam de la structure LVITEM de l’élément lors de son insertion dans la liste. En spécifiant les données d’élément appropriées et en fournissant une fonction de comparaison appropriée, vous pouvez trier les éléments par leur étiquette, par n’importe quel sous-élément ou par toute autre propriété. Notez que le tri des éléments ne réorganise pas les sous-éléments correspondants. Lorsque les éléments sont réorganisés, leurs sous-éléments correspondants sont transportés avec eux ; c’est-à-dire que des lignes entières sont conservées ensemble. Pour classer les colonnes séparément les unes des autres, en détachant les sous-éléments de leurs éléments, vous devez régénérer les colonnes après le tri à l’aide de LVM_SETITEM.

Vous pouvez vous assurer qu’un contrôle d’affichage de liste est toujours trié en spécifiant le style de fenêtre LVS_SORTASCENDING ou LVS_SORTDESCENDING . Les contrôles avec ces styles utilisent le texte d’étiquette des éléments pour les trier par ordre croissant ou décroissant. Vous ne pouvez pas fournir une fonction de comparaison lors de l’utilisation de ces styles de fenêtre. Si un contrôle d’affichage de liste a l’un de ces styles, 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 .

Vous pouvez trouver un élément d’affichage de liste avec des propriétés spécifiques à l’aide du message LVM_FINDITEM . Vous pouvez trouver un élément list-view qui est dans un état spécifié et qui a une relation spécifiée avec un élément donné à l’aide du message LVM_GETNEXTITEM . Par exemple, vous pouvez récupérer l’élément sélectionné suivant à droite d’un élément spécifié.

colonnes List-View

Les colonnes contrôlent la façon dont les éléments et leurs sous-éléments sont affichés en mode rapport. Chaque colonne a un titre et une largeur et est associée à un sous-élément spécifique ; sous-élément zéro est l’icône et l’étiquette de l’élément. Les attributs d’une colonne sont définis par une structure LVCOLUMN .

Pour ajouter une colonne à un contrôle list-view, utilisez le message LVM_INSERTCOLUMN . Pour supprimer une colonne, utilisez le message LVM_DELETECOLUMN .

Notes

La suppression de la colonne zéro d’un contrôle list-view n’est prise en charge que dans ComCtl32.dll version 6 et ultérieure. La version 5 prend également en charge la suppression de la colonne zéro, mais uniquement après avoir utilisé CCM_SETVERSION pour définir la version sur 5 ou version ultérieure. Les versions antérieures à la version 5 ne prennent pas en charge la suppression de la colonne zéro.

 

Vous pouvez récupérer et modifier les propriétés d’une colonne existante à l’aide des messages LVM_GETCOLUMN et LVM_SETCOLUMN . Pour récupérer ou modifier la largeur d’une colonne, utilisez les messages LVM_GETCOLUMNWIDTH et LVM_SETCOLUMNWIDTH .

Sauf si le style de fenêtre LVS_NOCOLUMNHEADER est spécifié, les en-têtes de colonne s’affichent en mode rapport. L’utilisateur peut cliquer sur un en-tête de colonne, ce qui entraîne l’envoi d’un code de notification LVN_COLUMNCLICK à la fenêtre parente. En règle générale, la fenêtre parente trie le contrôle list-view par la colonne spécifiée lorsque ce clic se produit. L’utilisateur peut également faire glisser les repères de colonne entre les en-têtes pour dimensionner les colonnes.

Les contrôles d’affichage de liste peuvent afficher des images en regard des titres de colonne. Pour implémenter cette fonctionnalité, spécifiez la valeur LVCF_IMAGE et affectez l’index de l’image au membre iImage dans la structure LVCOLUMN .

Les contrôles d’affichage de liste peuvent définir l’ordre dans lequel les colonnes sont affichées. Pour implémenter cette fonctionnalité, spécifiez la valeur LVCF_ORDER et affectez l’ordre des colonnes au membre iOrder dans la structure LVCOLUMN . L’ordre des colonnes est de base zéro et est dans l’ordre de gauche à droite. Par exemple, zéro indique la colonne la plus à gauche.

position de défilement List-View

À moins que le style de fenêtre LVS_NOSCROLL ne soit spécifié, un contrôle d’affichage de liste peut être fait défiler pour afficher plus d’éléments que ne peut tenir dans la zone cliente du contrôle. Vous pouvez récupérer la position de défilement d’un contrôle list-view et les informations associées, faire défiler un contrôle list-view d’une quantité spécifiée ou faire défiler un contrôle list-view pour qu’un élément de liste spécifié soit visible.

En mode icône ou petite icône, la position de défilement actuelle est définie par l’origine de la vue. L’origine de la vue est l’ensemble de coordonnées, par rapport à la zone visible du contrôle list-view, qui correspondent aux coordonnées d’affichage (0, 0). Pour récupérer l’origine de la vue actuelle, utilisez le message LVM_GETORIGIN . Ce message ne doit être utilisé que dans une icône ou une petite vue d’icône ; il retourne une erreur dans la vue liste ou rapport.

En mode liste ou rapport, la position de défilement actuelle est définie par l’index supérieur. L’index supérieur est l’index du premier élément visible dans le contrôle list-view. Pour récupérer l’index supérieur actuel, utilisez le message LVM_GETTOPINDEX . Ce message retourne un résultat valide uniquement en mode liste ou rapport ; il retourne zéro dans l’icône ou la petite vue icône.

Vous pouvez utiliser le message LVM_GETVIEWRECT pour récupérer le rectangle englobant de tous les éléments d’un contrôle de liste, par rapport à la zone visible du contrôle.

Le message LVM_GETCOUNTPERPAGE retourne le nombre d’éléments qui correspondent à une page du contrôle list-view. Ce message retourne un résultat valide uniquement dans les affichages liste et rapport ; dans les icônes et les petites icônes, il retourne le nombre total d’éléments.

Pour faire défiler un contrôle d’affichage de liste d’une quantité spécifique, utilisez le message LVM_SCROLL . À l’aide du message LVM_ENSUREVISIBLE, vous pouvez faire défiler le contrôle list-view, si nécessaire, pour vous assurer qu’un élément spécifié est visible.

List-View Modification d’étiquette

Un contrôle d’affichage de liste qui a le style de fenêtre LVS_EDITLABELS permet à un utilisateur de modifier les étiquettes d’élément en place. L’utilisateur commence à modifier en cliquant sur l’étiquette d’un élément qui a le focus. Une application peut également commencer à modifier automatiquement à l’aide du message LVM_EDITLABEL . Le contrôle list-view avertit la fenêtre parente lorsque la modification commence et quand elle est annulée ou terminée. Une fois la modification terminée, la fenêtre parente est responsable de la mise à jour de l’étiquette de l’élément, le cas échéant.

Lorsque la modification d’étiquette commence, un contrôle d’édition est créé, positionné et initialisé. Avant de s’afficher, le contrôle list-view envoie à sa fenêtre parente un code de notification LVN_BEGINLABELEDIT . Si vous devez modifier le processus de modification des étiquettes, vous pouvez implémenter un gestionnaire pour cette notification.

Une utilisation pour un gestionnaire de notifications LVN_BEGINLABELEDIT consiste à contrôler les étiquettes que l’utilisateur peut modifier. Pour empêcher la modification d’étiquette, retournez une valeur différente de zéro. Pour personnaliser la modification d’étiquette, faites en charge au gestionnaire de notifications de récupérer un handle dans le contrôle d’édition en envoyant un message LVM_GETEDITCONTROL au contrôle list-view. Une fois que vous disposez de ce handle, vous pouvez personnaliser le contrôle d’édition en envoyant les messages EM_XXX habituels. Par instance, pour limiter la quantité de texte qu’un utilisateur peut entrer, envoyez au contrôle d’édition un message EM_LIMITTEXT. Vous pouvez modifier le texte par défaut du contrôle d’édition avec SetWindowText. Vous pouvez même sous-classer le contrôle d’édition pour intercepter et ignorer des caractères non valides.

Lorsque la modification d’étiquette est annulée ou terminée, un contrôle d’affichage de liste envoie à sa fenêtre parente un LVN_ENDLABELEDIT code de notification. Le paramètre lParam est l’adresse d’une structure NMLVDISPINFO . Le membre d’élément de cette structure est une structure LVITEM dont le membre iItem identifie l’élément. Si la modification est annulée, le membre pszText de la structure LVITEM est NULL ; sinon, pszText est l’adresse du texte modifié. La fenêtre parente est responsable de la mise à jour de l’étiquette de l’élément si elle souhaite conserver la nouvelle étiquette.

couleurs List-View

Une application peut récupérer et définir trois couleurs pour un contrôle d’affichage de liste.

Color Messages utilisés pour récupérer et définir les couleurs
Couleur du texte LVM_GETTEXTCOLOR, LVM_SETTEXTCOLOR
Couleur d’arrière-plan du texte LVM_GETTEXTBKCOLOR, LVM_SETTEXTBKCOLOR
Couleur d’arrière-plan de la fenêtre LVM_GETBKCOLOR, LVM_SETBKCOLOR

 

Pour personnaliser plus considérablement l’apparence d’un contrôle d’affichage de liste, utilisez NM_CUSTOMDRAW (affichage liste) ou utilisez des styles visuels (voir Styles visuels et Activation des styles visuels).

Organisation des éléments de liste par groupe

Les fonctionnalités de regroupement du contrôle list-view vous permettent de regrouper visuellement des ensembles d’éléments liés logiquement. Les groupes peuvent être créés en fonction des propriétés d’élément, des attributs ou d’autres caractéristiques. Ces groupes sont généralement séparés à l’écran par un en-tête horizontal qui contient le nom du groupe. La capture d’écran suivante montre les éléments regroupés.

capture d’écran d’un contrôle d’affichage de liste, avec des chiens dans un groupe et des chats dans un autre groupe

Vous utilisez la structure LVGROUP pour stocker des informations sur un groupe, telles que le texte d’en-tête et de pied de page, l’état actuel du groupe, etc. L’API de regroupement inclut des messages qui vous permettent de gérer des groupes et des éléments de groupe en ajoutant des éléments à des groupes, en ajoutant des groupes aux affichages, en triant des éléments de groupe et en interrogeant des groupes pour la taille des éléments et d’autres informations. Par exemple, vous pouvez définir et récupérer des paramètres d’affichage pour chaque groupe à l’aide des macros ListView_SetGroupMetrics et ListView_GetGroupMetrics .

Le regroupement est disponible dans tous les affichages à l’exception de l’affichage liste. Il n’est pas disponible sur les contrôles qui ont le style LVS_OWNERDATA .

Pour plus d’informations, consultez Utilisation de contrôles List-View.

Marques d’insertion

Les marques d’insertion indiquent aux utilisateurs où les éléments déplacés seront placés. Les marques d’insertion s’affichent actuellement lorsque l’utilisateur fait glisser un élément dans le menu Démarrer ou la barre de lancement rapide. La marque d’insertion fonctionne également pour les listes qui sont définies sur autoarrangement. Quand un utilisateur fait glisser un élément vers un point entre deux autres éléments, la marque d'insertion indique le nouvel emplacement prévu de l'élément. La capture d’écran suivante montre une marque d’insertion.

capture d’écran montrant une marque d’insertion lors du glissement d’un fichier entre deux autres dans un contrôle d’affichage de liste

Les éléments API de marque d’insertion permettent le placement des marques d’insertion en fournissant des messages et des indicateurs qui effectuent la détection d’accès, qui spécifient l’emplacement et l’apparence de la marque d’insertion par élément, et qui recherchent des informations sur la taille et l’apparence actuelles de la marque d’insertion.

Voir aussi