À propos des zones de liste
Un contrôle de zone de liste contient une liste simple à partir de laquelle l’utilisateur peut généralement sélectionner un ou plusieurs éléments. Les zones de liste offrent une flexibilité limitée par rapport aux contrôles Affichage de liste .
Les éléments de zone de liste peuvent être représentés par des chaînes de texte, des bitmaps ou les deux. Si la zone de liste n’est pas assez grande pour afficher tous les éléments de la zone de liste à la fois, la zone de liste fournit une barre de défilement. L’utilisateur fait défiler les éléments de la zone de liste et applique ou supprime les status de sélection si nécessaire. La sélection d’un élément de zone de liste modifie son apparence visuelle, généralement en remplaçant les couleurs de texte et d’arrière-plan par celles spécifiées par les métriques du système d’exploitation pertinentes. Lorsque l’utilisateur sélectionne ou désélectionne un élément, le système envoie un message de notification à la fenêtre parente de la zone de liste.
Pour une application ANSI, le système convertit le texte d’une zone de liste en Unicode à l’aide de la page de codes CP_ACP . Cela peut entraîner des problèmes. Par exemple, les caractères romains accentués dans une zone de liste non-Unicode dans Windows, la version japonaise sortira brouillée. Pour résoudre ce problème, compilez l’application au format Unicode ou utilisez une zone de liste dessinée par le propriétaire.
Cette section traite des sujets suivants :
- Création d’une zone de liste
- Types et styles de zone de liste
- Fonctions de zone de liste
- Messages de notification à partir de zones de liste
- Messages vers les zones de liste
- Traitement des messages de fenêtre par défaut
- Zones de liste dessinées par le propriétaire
- Faire glisser les zones de liste
Création d’une zone de liste
Le moyen le plus simple de créer une zone de liste dans une boîte de dialogue consiste à la faire glisser de la boîte à outils de Microsoft Visual Studio vers votre ressource de boîte de dialogue. Pour créer une zone de liste de manière dynamique, ou pour créer une zone de liste dans une fenêtre autre qu’une boîte de dialogue, utilisez la fonction CreateWindowEx , en spécifiant la classe de fenêtre WC_LISTBOX et les styles de zone de liste appropriés.
Types et styles de zone de liste
Il existe deux types de zones de liste : sélection unique (par défaut) et sélection multiple. Dans une zone de liste à sélection unique, l’utilisateur ne peut sélectionner qu’un seul élément à la fois. Dans une zone de liste à sélection multiple, l’utilisateur peut sélectionner plusieurs éléments à la fois. Pour créer une zone de liste à sélection multiple, spécifiez le style LBS_MULTIPLESEL ou LBS_EXTENDEDSEL .
L’apparence et le fonctionnement d’une zone de liste sont contrôlés par les styles de zone de liste et les styles de fenêtre. Ces styles indiquent si la liste est triée, organisée en plusieurs colonnes, dessinée par l’application, etc. Les dimensions et les styles d’une zone de liste sont généralement définis dans un modèle de boîte de dialogue inclus dans les ressources d’une application.
Notes
Pour utiliser des styles visuels avec ces contrôles, une application doit inclure un manifeste et appeler InitCommonControls au début du programme. Pour plus d’informations sur les styles visuels, consultez Styles visuels. Pour plus d’informations sur les manifestes, consultez Activation des styles visuels.
Fonctions de zone de liste
La fonction DlgDirList remplace le contenu d’une zone de liste par les noms des lecteurs, répertoires et fichiers qui correspondent à un ensemble de critères spécifié. La fonction DlgDirSelectEx récupère la sélection actuelle dans une zone de liste initialisée par DlgDirList. Ces fonctions permettent à l’utilisateur de sélectionner un lecteur, un répertoire ou un fichier à partir d’une zone de liste sans taper l’emplacement et le nom du fichier.
En outre, la fonction GetListBoxInfo retourne le nombre d’éléments par colonne dans une zone de liste spécifiée.
Messages de notification à partir de zones de liste
Lorsqu’un événement se produit dans une zone de liste, la zone de liste envoie un code de notification, sous la forme d’un message WM_COMMAND , à la procédure de boîte de dialogue de la fenêtre propriétaire. Les codes de notification de zone de liste sont envoyés lorsqu’un utilisateur sélectionne, double-clique ou annule un élément de zone de liste ; lorsque la zone de liste reçoit ou perd le focus clavier ; et lorsque le système ne peut pas allouer suffisamment de mémoire pour une demande de zone de liste. Un message WM_COMMAND contient l’identificateur de zone de liste dans le mot d’ordre inférieur du paramètre wParam et le code de notification dans le mot d’ordre supérieur. Le paramètre lParam contient le handle de fenêtre de contrôle.
Une procédure de boîte de dialogue n’est pas nécessaire pour traiter ces messages ; la procédure de fenêtre par défaut les traite.
Une application doit surveiller et traiter les codes de notification de zone de liste suivants.
| Code de notification | Description |
|---|---|
| LBN_DBLCLK | L’utilisateur double-clique sur un élément dans la zone de liste. |
| LBN_ERRSPACE | La zone de liste ne peut pas allouer suffisamment de mémoire pour répondre à une demande. |
| LBN_KILLFOCUS | La zone de liste perd le focus clavier. |
| LBN_SELCANCEL | L’utilisateur annule la sélection d’un élément dans la zone de liste. |
| LBN_SELCHANGE | La sélection dans une zone de liste est sur le point de changer. |
| LBN_SETFOCUS | La zone de liste reçoit le focus clavier. |
Messages vers les zones de liste
Une procédure de boîte de dialogue peut envoyer des messages à une zone de liste pour ajouter, supprimer, examiner et modifier des éléments de zone de liste. Par exemple, une procédure de boîte de dialogue peut envoyer un message LB_ADDSTRING à une zone de liste pour ajouter un élément, et un message LB_GETSEL pour déterminer si l’élément est sélectionné. D’autres messages définissent et récupèrent des informations sur la taille, l’apparence et le comportement de la zone de liste. Par exemple, le message LB_SETHORIZONTALEXTENT définit la largeur de défilement d’une zone de liste. Une procédure de boîte de dialogue peut envoyer n’importe quel message à une zone de liste à l’aide de la fonction SendMessage ou SendDlgItemMessage .
Un élément de zone de liste est souvent référencé par son index, un entier qui représente la position de l’élément dans la zone de liste. L’index du premier élément d’une zone de liste est 0, l’index du deuxième élément est 1, et ainsi de suite.
Le tableau suivant décrit la façon dont la procédure de zone de liste prédéfinie répond aux messages de zone de liste.
| Message | response |
|---|---|
| LB_ADDFILE | Insère un fichier dans une zone de liste de répertoires qui est remplie par la fonction DlgDirList et récupère l’index de la zone de liste de l’élément inséré. |
| LB_ADDSTRING | Ajoute une chaîne à une zone de liste et retourne son index. |
| LB_DELETESTRING | Supprime une chaîne d’une zone de liste et retourne le nombre de chaînes qui restent dans la liste. |
| LB_DIR | Ajoute une liste de noms de fichiers à une zone de liste et retourne l’index du nom de fichier ajouté. |
| LB_FINDSTRING | Retourne l’index de la première chaîne dans la zone de liste qui commence par une chaîne spécifiée. |
| LB_FINDSTRINGEXACT | Retourne l’index de la chaîne dans la zone de liste qui est égal à une chaîne spécifiée. |
| LB_GETANCHORINDEX | Retourne l’index de l’élément que la souris a sélectionné pour la dernière fois. |
| LB_GETCARETINDEX | Retourne l’index de l’élément qui a le rectangle de focus. |
| LB_GETCOUNT | Retourne le nombre d’éléments dans la zone de liste. |
| LB_GETCURSEL | Retourne l’index de l’élément actuellement sélectionné. |
| LB_GETHORIZONTALEXTENT | Retourne la largeur de défilement, en pixels, d’une zone de liste. |
| LB_GETITEMDATA | Retourne la valeur associée à l’élément spécifié. |
| LB_GETITEMHEIGHT | Retourne la hauteur, en pixels, d’un élément dans une zone de liste. |
| LB_GETITEMRECT | Récupère les coordonnées client de l’élément de zone de liste spécifié. |
| LB_GETLOCALE | Récupère les paramètres régionaux de la zone de liste. Le mot d’ordre élevé contient le code pays/région et le mot de bas ordre contient l’identificateur de langue. |
| LB_GETSEL | Retourne l’état de sélection d’un élément de zone de liste. |
| LB_GETSELCOUNT | Retourne le nombre d’éléments sélectionnés dans une zone de liste à sélection multiple. |
| LB_GETSELITEMS | Crée un tableau des index de tous les éléments sélectionnés dans une zone de liste à sélection multiple et retourne le nombre total d’éléments sélectionnés. |
| LB_GETTEXT | Récupère la chaîne associée à un élément spécifié et la longueur de la chaîne. |
| LB_GETTEXTLEN | Retourne la longueur, en caractères, de la chaîne associée à un élément spécifié. |
| LB_GETTOPINDEX | Retourne l’index du premier élément visible dans une zone de liste. |
| LB_INITSTORAGE | Alloue de la mémoire pour le nombre spécifié d’éléments et les chaînes associées. |
| LB_INSERTSTRING | Insère une chaîne à un index spécifié dans une zone de liste. |
| LB_ITEMFROMPOINT | Récupère l’index de base zéro de l’élément le plus proche du point spécifié dans une zone de liste. |
| LB_RESETCONTENT | Supprime tous les éléments d’une zone de liste. |
| LB_SELECTSTRING | Sélectionne la première chaîne qui correspond à un préfixe spécifié. |
| LB_SELITEMRANGE | Sélectionne une plage d’éléments spécifiée dans une zone de liste. |
| LB_SELITEMRANGEEX | Sélectionne une plage d’éléments spécifiée si l’index du premier élément de la plage est inférieur à l’index du dernier élément de la plage. Annule la sélection dans la plage si l’index du premier élément est supérieur au dernier. |
| LB_SETANCHORINDEX | Définit l’élément que la souris a sélectionné en dernier sur un élément spécifié. |
| LB_SETCARETINDEX | Définit le rectangle de focus sur un élément de zone de liste spécifié. |
| LB_SETCOLUMNWIDTH | Définit la largeur, en pixels, de toutes les colonnes d’une zone de liste. |
| LB_SETCOUNT | Définit le nombre d’éléments dans une zone de liste. |
| LB_SETCURSEL | Sélectionne un élément de zone de liste spécifié. |
| LB_SETHORIZONTALEXTENT | Définit la largeur de défilement, en pixels, d’une zone de liste. |
| LB_SETITEMDATA | Associe une valeur à un élément de zone de liste. |
| LB_SETITEMHEIGHT | Définit la hauteur, en pixels, d’un ou plusieurs éléments d’une zone de liste. |
| LB_SETLOCALE | Définit les paramètres régionaux d’une zone de liste et retourne l’identificateur de paramètres régionaux précédent. |
| LB_SETSEL | Sélectionne un élément dans une zone de liste à sélection multiple. |
| LB_SETTABSTOPS | Définit les taquets de tabulation sur ceux spécifiés dans un tableau spécifié. |
| LB_SETTOPINDEX | Fait défiler la zone de liste pour que l’élément spécifié se trouve en haut de la plage visible. |
Traitement des messages de fenêtre par défaut
La procédure de fenêtre de la classe de fenêtre de zone de liste prédéfinie effectue le traitement par défaut de tous les messages que la zone de liste ne traite pas. Lorsque la procédure de zone de liste retourne FALSE pour un message, la procédure de fenêtre prédéfinie vérifie le message et effectue des actions par défaut, comme indiqué dans le tableau suivant.
| Message | Action par défaut |
|---|---|
| WM_CHAR | Déplace la sélection vers le premier élément qui commence par le caractère que l’utilisateur a tapé. Si la zone de liste a le style LBS_OWNERDRAW , aucune action ne se produit. Plusieurs caractères tapés dans un court intervalle sont traités comme un groupe, et le premier élément qui commence par cette série de caractères est sélectionné. |
| WM_CREATE | Crée une zone de liste vide. |
| WM_DESTROY | Détruit la zone de liste et libère toutes les ressources qu’il utilise. |
| Transmet le message à la procédure de boîte de dialogue ou au processus de fenêtre parente. | |
| WM_ENABLE | Si le contrôle est visible, invalide le rectangle afin que les chaînes puissent être peintes en gris. |
| WM_ERASEBKGND | Efface l’arrière-plan d’une zone de liste. Si la zone de liste a le style LBS_OWNERDRAW , l’arrière-plan n’est pas effacé. |
| WM_GETDLGCODE | Retourne DLGC_WANTARROWS | DLGC_WANTCHARS, indiquant que la procédure de zone de liste par défaut traite les touches de direction et WM_CHAR messages. |
| WM_GETFONT | Retourne un handle à la police active pour la zone de liste. |
| WM_HSCROLL | Fait défiler la zone de liste horizontalement. |
| WM_KEYDOWN | Traite les clés virtuelles pour le défilement. La clé virtuelle est l’index de l’élément vers lequel déplacer le caret. La sélection n’est pas modifiée. |
| WM_KILLFOCUS | Désactive le caret et le détruit. Envoie un code de notification LBN_KILLFOCUS au propriétaire de la zone de liste. |
| WM_LBUTTONDBLCLK | Suit la souris dans la zone cliente de la zone de liste. Cela permet à l’utilisateur d’annuler une sélection si le bouton de la souris est relâché en dehors de la zone cliente de la zone de liste. |
| WM_LBUTTONDOWN | Suit la souris dans la zone cliente de la zone de liste. Cela permet à l’utilisateur d’annuler une sélection si le bouton de la souris est relâché en dehors de la zone cliente de la zone de liste. |
| WM_LBUTTONUP | Suit la souris dans la zone cliente de la zone de liste. Cela permet à l’utilisateur d’annuler une sélection si le bouton de la souris est relâché en dehors de la zone cliente de la zone de liste. |
| WM_MOUSEMOVE | Suit la souris dans la zone cliente de la zone de liste. Cela permet à l’utilisateur d’annuler une sélection si le bouton de la souris est relâché en dehors de la zone cliente de la zone de liste. |
| WM_PAINT | Effectue une opération de peinture sous-classée à l’aide du handle de zone de liste dans le contexte de l’appareil (DC). |
| WM_SETFOCUS | Active le caret et envoie un code de notification LBN_SETFOCUS au propriétaire de la zone de liste. |
| WM_SETFONT | Définit une nouvelle police pour la zone de liste. |
| WM_SETREDRAW | Définit ou efface l’indicateur de redessinage en fonction de la valeur de wParam. |
| WM_SIZE | Redimensionne la zone de liste en un nombre intégral d’éléments. |
| WM_VSCROLL | Fait défiler la zone de liste verticalement. |
La procédure de zone de liste prédéfinie transmet tous les autres messages à DefWindowProc pour le traitement par défaut.
Owner-Drawn zones de liste
Une application peut créer une zone de liste dessinée par le propriétaire pour assumer la responsabilité de la peinture des éléments de liste. La fenêtre parente ou la boîte de dialogue d’une zone de liste dessinée par le propriétaire (son propriétaire) reçoit WM_DRAWITEM messages lorsqu’une partie de la zone de liste doit être peinte. Une zone de liste dessinée par le propriétaire peut répertorier des informations autres que, ou en plus, des chaînes de texte.
Le propriétaire d’une zone de liste dessinée par le propriétaire doit traiter le message WM_DRAWITEM . Ce message est envoyé chaque fois qu’une partie de la zone de liste doit être redessinée. Le propriétaire peut avoir besoin de traiter d’autres messages, en fonction des styles spécifiés pour la zone de liste.
Une application peut créer une zone de liste dessinée par le propriétaire en spécifiant le style LBS_OWNERDRAWFIXED ou LBS_OWNERDRAWVARIABLE . Si tous les éléments de liste de la zone de liste ont la même hauteur, comme des chaînes ou des icônes, une application peut utiliser le style LBS_OWNERDRAWFIXED . Si les éléments de liste ont une hauteur variable (par exemple, des bitmaps de taille différente), une application peut utiliser le style LBS_OWNERDRAWVARIABLE .
Le propriétaire d’une zone de liste dessinée par le propriétaire peut traiter un message WM_MEASUREITEM pour spécifier les dimensions des éléments de liste. Si l’application crée la zone de liste à l’aide du style LBS_OWNERDRAWFIXED , le système n’envoie le message WM_MEASUREITEM qu’une seule fois. Les dimensions spécifiées par le propriétaire sont utilisées pour tous les éléments de liste. Si le style LBS_OWNERDRAWVARIABLE est utilisé, le système envoie un message WM_MEASUREITEM pour chaque élément de liste ajouté à la zone de liste. Le propriétaire peut déterminer ou définir la hauteur d’un élément de liste à tout moment à l’aide des messages LB_GETITEMHEIGHT et LB_SETITEMHEIGHT , respectivement.
Si les informations affichées dans une zone de liste dessinée par le propriétaire incluent du texte, une application peut suivre le texte de chaque élément de liste en spécifiant le style LBS_HASSTRINGS . Les zones de liste avec le style LBS_SORT sont triées en fonction de ce texte. Si une zone de liste est triée, mais n’est pas du style LBS_HASSTRINGS , le propriétaire doit traiter le message WM_COMPAREITEM .
Dans une zone de liste dessinée par le propriétaire, le propriétaire doit effectuer le suivi des éléments de liste qui contiennent des informations autres que ou en plus du texte. Pour ce faire, vous pouvez enregistrer le handle dans les informations en tant que données d’élément à l’aide du message LB_SETITEMDATA . Pour libérer les objets de données associés aux éléments d’une zone de liste, le propriétaire peut traiter le message WM_DELETEITEM .
Pour obtenir un exemple de zone de liste dessinée par le propriétaire, consultez How to Create an Owner-Drawn List Box.
Faire glisser les zones de liste
Une zone de liste glisser est un type spécial de zone de liste qui permet à l’utilisateur de faire glisser des éléments d’un emplacement vers un autre. Une application peut utiliser une zone de liste glisser pour afficher des chaînes dans une séquence particulière et permettre à l’utilisateur de modifier la séquence en faisant glisser les éléments en position.
Création de zones de liste glisser
Les zones de liste de glisser ont les mêmes styles de fenêtre et traitent les mêmes messages que les zones de liste standard. Pour créer une zone de liste glisser, créez d’abord une zone de liste standard, puis appelez la fonction MakeDragList . Pour convertir une zone de liste d’une boîte de dialogue en zone de liste de glisser, vous pouvez appeler MakeDragList lorsque le WM_INITDIALOG message est traité.
Faire glisser les messages de zone de liste
Une zone de liste glisser avertit la fenêtre parente des événements de glisser en lui envoyant un message de liste de glisser. La fenêtre parente doit traiter le message de liste de glissement.
La zone de liste glisser enregistre ce message lorsque la fonction MakeDragList est appelée. Pour récupérer l’identificateur de message (valeur numérique) du message de liste de glisser, appelez la fonction RegisterWindowMessage et spécifiez la valeur DRAGLISTMSGSTRING.
Le paramètre wParam du message de liste de glisser est l’identificateur de contrôle de la zone de liste glisser. Le paramètre lParam est l’adresse d’une structure DRAGLISTINFO , qui contient le code de notification de l’événement de glisser et d’autres informations. La valeur de retour du message dépend de la notification.
Faire glisser les codes de notification de zone de liste
Le code de notification de liste de glisser, qui est identifié par le membre uNotification de la structure DRAGLISTINFO incluse avec le message de liste de glisser, peut être DL_BEGINDRAG, DL_DRAGGING, DL_CANCELDRAG ou DL_DROPPED.
Le code de notification DL_BEGINDRAG est envoyé lorsque le curseur se trouve sur un élément de liste et que l’utilisateur clique sur le bouton gauche de la souris. La fenêtre parente peut retourner TRUE pour commencer l’opération de glisser ou FALSE pour interdire le glissement. De cette façon, la fenêtre parente peut activer le glisser-déplacer pour certains éléments de liste et le désactiver pour d’autres. Vous pouvez déterminer quel élément de liste se trouve à l’emplacement spécifié à l’aide de la fonction LBItemFromPt .
Si le glissement est en vigueur, le code de notification DL_DRAGGING est envoyé chaque fois que la souris est déplacée, ou à intervalles réguliers si la souris n’est pas déplacée. La fenêtre parente doit d’abord déterminer l’élément de liste sous le curseur à l’aide de LBItemFromPt , puis dessiner l’icône d’insertion à l’aide de la fonction DrawInsert . En spécifiant TRUE pour le paramètre bAutoScroll de LBItemFromPt, vous pouvez faire défiler la zone de liste d’une ligne si le curseur se trouve au-dessus ou au-dessous de sa zone cliente. La valeur retournée pour cette notification spécifie le type de curseur de souris que la zone de liste glisser doit définir.
Le code de notification DL_CANCELDRAG est envoyé si l’utilisateur annule une opération de glissement en cliquant sur le bouton droit de la souris ou en appuyant sur la touche ÉCHAP. Le code de notification DL_DROPPED est envoyé si l’utilisateur termine une opération de glissement en relâchant le bouton gauche de la souris, même si le curseur ne se trouve pas sur un élément de liste. La zone de liste glisser libère la capture de la souris avant d’envoyer l’une ou l’autre notification. La valeur de retour de ces deux notifications est ignorée. Faire glisser la liste