À propos des contrôles d’info-bulle

Les info-bulles s’affichent automatiquement ou s’affichent lorsque l’utilisateur met en pause le pointeur de la souris sur un outil ou un autre élément d’interface utilisateur. L’info-bulle apparaît près du pointeur et disparaît lorsque l’utilisateur clique sur un bouton de la souris, éloigne le pointeur de l’outil ou attend simplement quelques secondes.

Le contrôle d’info-bulle dans l’illustration suivante affiche des informations sur un fichier sur le bureau Windows. Lorsque vous déplacez la souris sur l’illustration, vous devez également voir une info-bulle dynamique qui contient du texte descriptif.

Cette section décrit le fonctionnement des contrôles d’info-bulle et la façon dont vous les créez.

• Comportement et apparence de l’info-bulle
• Création de contrôles d’info-bulle
• Activation des contrôles d’info-bulle
• Outils de prise en charge
• Affichage du texte
• Messagerie et notification
• Test des résultats
• Traitement des messages par défaut

Comportement et apparence de l’info-bulle

Les contrôles d’info-bulle peuvent afficher une seule ligne de texte ou plusieurs lignes. Leurs coins peuvent être arrondis ou carrés. Ils peuvent ou non avoir une tige qui pointe vers les outils comme un ballon de discours de dessin animé. Le texte de l’info-bulle peut être stationnaire ou peut se déplacer avec le pointeur de la souris, appelé suivi. Le texte stationnaire peut être affiché à côté d’un outil ou il peut être affiché sur un outil, appelé « in-place ». Les info-bulles standard sont stationnaires, affichent une seule ligne de texte, ont des coins carrés et n’ont pas de tige pointant vers l’outil.

Les info-bulles de suivi, qui sont prises en charge par la version 4.70 des contrôles communs, changent dynamiquement de position à l’écran. En mettant à jour rapidement la position, ces contrôles d’info-bulle semblent se déplacer en douceur, ou « suivre ». Celles-ci sont utiles lorsque vous souhaitez que le texte de l’info-bulle suive la position du pointeur de la souris à mesure qu’il se déplace. Pour plus d’informations sur le suivi des info-bulles et un exemple de code montrant comment vous les créez, consultez Info-bulles de suivi.

Les info-bulles multilignes, qui sont également prises en charge par la version 4.70 des contrôles communs, affichent du texte sur plusieurs lignes. Ils sont utiles pour afficher de longs messages. Pour plus d’informations et un exemple montrant comment créer des info-bulles multilignes, consultez Info-bulles multilignes.

Les info-bulles sont affichées dans une zone avec des coins arrondis et une tige pointant vers l’outil. Elles peuvent être monolignes ou multilignes. L’illustration suivante montre une info-bulle avec la tige et le rectangle dans leurs positions par défaut. Pour plus d’informations sur les info-bulles et un exemple montrant comment les créer, consultez Utilisation de contrôles d’info-bulle.

Une info-bulle peut également avoir un texte de titre et une icône, comme illustré dans l’illustration suivante. Notez que l’info-bulle doit avoir du texte ; si elle n’a que du texte de titre, l’info-bulle ne s’affiche pas. En outre, l’icône n’apparaît pas, sauf s’il existe un titre.

Parfois, les chaînes de texte sont coupées parce qu’elles sont trop longues pour être affichées complètement dans une petite fenêtre. Les info-bulles sur place permettent d’afficher des chaînes de texte pour les objets qui ont été clippés, comme le nom de fichier dans l’illustration suivante. Pour obtenir un exemple montrant comment créer des info-bulles sur place, consultez Info-bulles sur place.

Le curseur doit pointer sur un outil pendant un certain temps avant que l’info-bulle ne s’affiche. La durée par défaut de ce délai d’expiration est contrôlée par le temps de double-clic de l’utilisateur et est généralement d’environ une demi-seconde. Pour spécifier une valeur de délai d’expiration autre que celle par défaut, envoyez au contrôle d’info-bulle un message TTM_SETDELAYTIME .

Création de contrôles d’info-bulle

Pour créer un contrôle d’info-bulle, appelez CreateWindowEx et spécifiez la classe de fenêtre TOOLTIPS_CLASS . Cette classe est inscrite lors du chargement de la DLL de contrôle commun. Pour vous assurer que cette DLL est chargée, incluez la fonction InitCommonControlsEx dans votre application. Vous devez définir explicitement un contrôle d’info-bulle comme le plus haut. Sinon, elle peut être couverte par la fenêtre parente. Le fragment de code suivant montre comment créer un contrôle d’info-bulle.

HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            hwndParent, NULL, hinstMyDll,
                            NULL);

SetWindowPos(hwndTip, HWND_TOPMOST,0, 0, 0, 0,
             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

La procédure de fenêtre du contrôle d’info-bulle définit automatiquement la taille, la position et la visibilité du contrôle. La hauteur de la fenêtre d’info-bulle est basée sur la hauteur de la police actuellement sélectionnée dans le contexte de l’appareil pour le contrôle d’info-bulle. La largeur varie en fonction de la longueur de la chaîne actuellement dans la fenêtre d’info-bulle.

Activation des contrôles d’info-bulle

Un contrôle d’info-bulle peut être actif ou inactif. Lorsqu’il est actif, le texte de l’info-bulle s’affiche lorsque le pointeur de la souris se trouve sur un outil. Lorsqu’il est inactif, le texte de l’info-bulle n’apparaît pas, même si le pointeur se trouve sur un outil. Le message TTM_ACTIVATE active et désactive un contrôle d’info-bulle.

Outils de prise en charge

Un contrôle d’info-bulle peut prendre en charge un nombre quelconque d’outils. Pour prendre en charge un outil particulier, vous devez inscrire l’outil auprès du contrôle d’info-bulle en envoyant au contrôle le message TTM_ADDTOOL . Le message inclut l’adresse d’une structure TOOLINFO , qui fournit les informations dont le contrôle d’info-bulle a besoin pour afficher le texte de l’outil. Le membre uID de la structure TOOLINFO est défini par l’application. Chaque fois que vous ajoutez un outil, votre application fournit un identificateur unique. Le membre cbSize de la structure TOOLINFO est obligatoire et doit spécifier la taille de la structure.

Un contrôle d’info-bulle prend en charge les outils implémentés en tant que fenêtres (comme les fenêtres enfants ou les fenêtres de contrôle) et en tant que zones rectangulaires dans la zone cliente d’une fenêtre. Lorsque vous ajoutez un outil implémenté en tant que zone rectangulaire, le membre hwnd de la structure TOOLINFO doit spécifier le handle dans la fenêtre qui contient la zone, et le membre rect doit spécifier les coordonnées client du rectangle englobant de la zone. En outre, le membre uID doit spécifier l’identificateur défini par l’application pour l’outil.

Lorsque vous ajoutez un outil implémenté en tant que fenêtre, le membre uID de la structure TOOLINFO doit contenir le handle de fenêtre de l’outil. En outre, le membre uFlags doit spécifier la valeur TTF_IDISHWND , qui indique au contrôle d’info-bulle d’interpréter le membre uID comme un handle de fenêtre.

Affichage du texte

Lorsque vous ajoutez un outil à un contrôle d’info-bulle, le membre lpszText de la structure TOOLINFO doit spécifier l’adresse de la chaîne à afficher pour l’outil. Après avoir ajouté un outil, vous pouvez modifier le texte à l’aide du message TTM_UPDATETIPTEXT .

Si le mot d’ordre supérieur de lpszText est égal à zéro, le mot d’ordre inférieur doit être l’identificateur d’une ressource de chaîne. Lorsque le contrôle d’info-bulle a besoin du texte, le système charge la ressource de chaîne spécifiée à partir de l’application instance identifiée par le membre postérieur de la structure TOOLINFO.

Si vous spécifiez la valeur LPSTR_TEXTCALLBACK dans le membre lpszText , le contrôle d’info-bulle avertit la fenêtre spécifiée dans le membre hwnd de la structure TOOLINFOchaque fois que le contrôle d’info-bulle doit afficher du texte pour l’outil. Le contrôle d’info-bulle envoie le code de notification TTN_GETDISPINFO à la fenêtre. Le message inclut l’adresse d’une structure NMTTDISPINFO , qui contient le handle de fenêtre ainsi que l’identificateur défini par l’application pour l’outil. La fenêtre examine la structure pour déterminer l’outil pour lequel le texte est nécessaire, et elle remplit les membres de structure appropriés avec les informations dont le contrôle d’info-bulle a besoin pour afficher la chaîne.

De nombreuses applications créent des barres d’outils contenant des outils qui correspondent aux commandes de menu. Pour ces outils, il est pratique que le contrôle d’info-bulle affiche le même texte que l’élément de menu correspondant. Le système supprime automatiquement les caractères d’accélérateur d’esperluette (&) de toutes les chaînes passées à un contrôle d’info-bulle et termine la chaîne au premier caractère de tabulation (\t), sauf si le contrôle a le style TTS_NOPREFIX .

Pour récupérer le texte d’un outil, utilisez le message TTM_GETTEXT .

Messagerie et notification

Le texte de l’info-bulle s’affiche normalement lorsque le pointeur de la souris pointe sur une zone, généralement le rectangle défini par un outil tel qu’un contrôle bouton. Toutefois, Microsoft Windows envoie uniquement des messages liés à la souris à la fenêtre qui contient le pointeur, et non au contrôle d’info-bulle lui-même. Les informations relatives à la souris doivent être relayées au contrôle d’info-bulle pour qu’il affiche le texte de l’info-bulle à l’heure et à l’endroit appropriés.

Vous pouvez avoir des messages relayés automatiquement si :

• L’outil est un contrôle ou est défini en tant que rectangle dans la structure TOOLINFO de l’outil.
• La fenêtre associée à l’outil se trouve dans le même thread que le contrôle d’info-bulle.

Si ces deux conditions sont remplies, définissez l’indicateur TTF_SUBCLASS dans le membre uFlags de la structure TOOLINFO de l’outil lorsque vous ajoutez l’outil au contrôle d’info-bulle avec TTM_ADDTOOL. Les messages de souris nécessaires sont alors relayés automatiquement vers le contrôle d’info-bulle.

Définir TTF_SUBCLASS pour que les messages de la souris aient été relayés au contrôle est suffisant pour la plupart des besoins. Toutefois, cela ne fonctionnera pas dans les cas où il n’existe aucune connexion directe entre le contrôle d’info-bulle et la fenêtre de l’outil. Par exemple, si un outil est implémenté en tant que zone rectangulaire dans une fenêtre définie par l’application, la procédure de fenêtre reçoit les messages de la souris. La définition de TTF_SUBCLASS suffit pour vous assurer qu’elles sont transmises au contrôle. Toutefois, si un outil est implémenté en tant que fenêtre définie par le système, les messages de souris sont envoyés à cette fenêtre et ne sont pas directement disponibles pour l’application. Dans ce cas, vous devez sous-classer la fenêtre ou utiliser un crochet de message pour accéder aux messages de la souris. Vous devez ensuite relayer explicitement les messages de la souris vers le contrôle d’info-bulle avec TTM_RELAYEVENT. Pour obtenir un exemple d’utilisation de TTM_RELAYEVENT, consultez Info-bulles de suivi.

Lorsqu’un contrôle d’info-bulle reçoit un message WM_MOUSEMOVE , il détermine si le pointeur de la souris se trouve dans le rectangle englobant d’un outil. Si c’est le cas, le contrôle d’info-bulle définit un minuteur. À la fin de l’intervalle de délai d’attente, le contrôle d’info-bulle vérifie la position du pointeur pour voir s’il s’est déplacé. Si ce n’est pas le cas, le contrôle d’info-bulle récupère le texte de l’outil et affiche l’info-bulle. Le contrôle d’info-bulle continue d’afficher la fenêtre jusqu’à ce qu’il reçoive un message de bouton vers le haut ou vers le bas relayé ou jusqu’à ce qu’un message WM_MOUSEMOVE indique que le pointeur s’est déplacé en dehors du rectangle englobant de l’outil.

Un contrôle d’info-bulle a en fait trois durées d’expiration qui lui sont associées. La durée initiale est la durée pendant laquelle le pointeur de la souris doit rester immobile dans le rectangle englobant d’un outil avant l’affichage de la fenêtre d’info-bulle. La durée du reaffinement correspond à la longueur du délai avant l’affichage des fenêtres d’info-bulle suivantes lorsque le pointeur passe d’un outil à un autre. La durée de la fenêtre contextuelle correspond à la durée pendant laquelle la fenêtre d’info-bulle reste affichée avant d’être masquée. Autrement dit, si le pointeur reste stationnaire dans le rectangle englobant après l’affichage de la fenêtre d’info-bulle, la fenêtre d’info-bulle est automatiquement masquée à la fin de la durée de la fenêtre contextuelle. Vous pouvez ajuster toutes les durées de délai d’attente à l’aide du message TTM_SETDELAYTIME .

Si une application inclut un outil implémenté en tant que zone rectangulaire et que la taille ou la position du contrôle change, l’application peut utiliser le message TTM_NEWTOOLRECT pour signaler la modification au contrôle d’info-bulle. Une application n’a pas besoin de signaler les modifications de taille et de position d’un outil implémenté en tant que fenêtre, car le contrôle d’info-bulle utilise la poignée de fenêtre de l’outil pour déterminer si le pointeur de la souris se trouve sur l’outil, et non sur le rectangle englobant de l’outil.

Lorsqu’une info-bulle est sur le point d’être affichée, le contrôle d’info-bulle envoie à la fenêtre propriétaire un TTN_SHOW code de notification. La fenêtre propriétaire reçoit un code de notification TTN_POP lorsqu’une info-bulle est sur le point d’être masquée. Chaque code de notification est envoyé dans le contexte d’un message WM_NOTIFY .

Test des résultats

Le message TTM_HITTEST vous permet de récupérer les informations qu’un contrôle d’info-bulle conserve sur l’outil occupant un point particulier. Le message inclut une structure TTHITTESTINFO qui contient un handle de fenêtre, les coordonnées d’un point et l’adresse d’une structure TOOLINFO . Le contrôle d’info-bulle détermine si un outil occupe le point et, le cas échéant, remplit TOOLINFO avec des informations sur l’outil.

Traitement des messages par défaut

Le tableau suivant décrit les messages gérés par la procédure de fenêtre pour le contrôle d’info-bulle.