La classe CToolTipCtrl

Encapsule les fonctionnalités d’un « contrôle d’info-bulle », une petite fenêtre contextuelle qui affiche une seule ligne de texte décrivant l’objectif d’un outil dans une application.

Syntaxe

class CToolTipCtrl : public CWnd

Membres

Constructeurs publics

Méthodes publiques

Notes

Un « outil » est une fenêtre, telle qu’une fenêtre enfant ou un contrôle, ou une zone rectangulaire définie par l’application dans la zone cliente d’une fenêtre. Une info-bulle est masquée la plupart du temps, apparaissant uniquement lorsque l’utilisateur place le curseur sur un outil et le laisse pendant environ une demi-seconde. L’info-bulle s’affiche près du curseur et disparaît lorsque l’utilisateur clique sur un bouton de souris ou déplace le curseur hors de l’outil.

CToolTipCtrl fournit la fonctionnalité permettant de contrôler l’heure et la durée initiales de l’info-bulle, les largeurs de marge entourant le texte de l’info-bulle, la largeur de la fenêtre d’info-bulle elle-même et la couleur d’arrière-plan et de texte de l’info-bulle. Un seul contrôle d’info-bulle peut fournir des informations pour plusieurs outils.

La CToolTipCtrl classe fournit les fonctionnalités du contrôle d’info-bulle commun Windows. Ce contrôle (et par conséquent la CToolTipCtrl classe) est disponible uniquement pour les programmes exécutés sous Windows 95/98 et Windows NT versions 3.51 et ultérieures.

Pour plus d’informations sur l’activation des info-bulles, consultez Conseils d’outil dans Windows non dérivé de CFrameWnd.

Pour plus d’informations sur l’utilisation CToolTipCtrl, consultez Contrôles et utilisation CToolTipCtrl.

Hiérarchie d'héritage

CObject

CCmdTarget

CWnd

CToolTipCtrl

Spécifications

En-tête : afxcmn.h

CToolTipCtrl::Activate

Appelez cette fonction pour activer ou désactiver un contrôle d’info-bulle.

void Activate(BOOL bActivate);

Paramètres

bActivate
Spécifie si le contrôle d’info-bulle doit être activé ou désactivé.

Notes

Si bActivate c’est TRUEle cas, le contrôle est activé ; s’il FALSEest désactivé.

Lorsqu’un contrôle d’info-bulle est actif, les informations d’info-bulle s’affichent lorsque le curseur se trouve sur un outil inscrit auprès du contrôle ; lorsqu’il est inactif, les informations d’info-bulle ne s’affichent pas, même lorsque le curseur se trouve sur un outil.

Exemple

Consultez l’exemple pour CPropertySheet::GetTabControl.

CToolTipCtrl::AddTool

Inscrit un outil auprès du contrôle d’info-bulle.

BOOL AddTool(
    CWnd* pWnd,
    UINT nIDText,
    LPCRECT lpRectTool = NULL,
    UINT_PTR nIDTool = 0);

BOOL AddTool(
    CWnd* pWnd,
    LPCTSTR lpszText = LPSTR_TEXTCALLBACK,
    LPCRECT lpRectTool = NULL,
    UINT_PTR nIDTool = 0);

Paramètres

pWnd
Pointeur vers la fenêtre qui contient l’outil.

nIDText
ID de la ressource de chaîne qui contient le texte de l’outil.

lpRectTool
Pointeur vers une RECT structure contenant les coordonnées du rectangle englobant de l’outil. Les coordonnées sont relatives au coin supérieur gauche de la zone cliente de la fenêtre identifiée par pWnd.

nIDTool
ID de l’outil.

lpszText
Pointeur vers le texte de l’outil. Si ce paramètre contient la valeur LPSTR_TEXTCALLBACK, TTN_NEEDTEXT les messages de notification sont envoyés au parent de la fenêtre vers laquelle pWnd pointe.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0.

Notes

Les lpRectTool paramètres doivent nIDTool être valides, ou s’il lpRectTool s’agit NULLde nIDTool 0.

Un contrôle d’info-bulle peut être associé à plusieurs outils. Appelez cette fonction pour inscrire un outil auprès du contrôle d’info-bulle, afin que les informations stockées dans l’info-bulle s’affichent lorsque le curseur se trouve sur l’outil.

Exemple

Consultez l’exemple pour CPropertySheet::GetTabControl.

CToolTipCtrl::AdjustRect

Convertit entre le rectangle d’affichage de texte d’un contrôle d’info-bulle et son rectangle de fenêtre.

BOOL AdjustRect(
    LPRECT lprc,
    BOOL bLarger = TRUE);

Paramètres

lprc
Pointeur vers une RECT structure qui contient un rectangle de fenêtre d’info-bulle ou un rectangle d’affichage de texte.

bLarger
Si TRUE, lprc est utilisé pour spécifier un rectangle d’affichage de texte et reçoit le rectangle de fenêtre correspondant. Si FALSE, lprc est utilisé pour spécifier un rectangle de fenêtre et reçoit le rectangle d’affichage de texte correspondant.

Valeur de retour

Différent de zéro si le rectangle est correctement ajusté ; sinon 0.

Notes

Cette fonction membre calcule le rectangle d’affichage de texte d’un contrôle d’info-bulle à partir de son rectangle de fenêtre, ou le rectangle de fenêtre d’info-bulle nécessaire pour afficher un rectangle d’affichage de texte spécifié.

Cette fonction membre implémente le comportement du message TTM_ADJUSTRECT Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::Create

Crée un contrôle d’info-bulle et l’attache à un CToolTipCtrl objet.

virtual BOOL Create(CWnd* pParentWnd, DWORD dwStyle = 0);

Paramètres

pParentWnd
Spécifie la fenêtre parente du contrôle d’info-bulle, généralement un CDialog. Il ne doit pas être NULL.

dwStyle
Spécifie le style du contrôle d’info-bulle. Pour plus d’informations, consultez la section Remarques.

Valeur de retour

Différent de zéro si l’objet CToolTipCtrl est correctement créé ; sinon, 0.

Notes

Vous construisez une CToolTipCtrl étape en deux étapes. Tout d’abord, appelez le constructeur pour construire l’objet CToolTipCtrl , puis appelez-le Create pour créer le contrôle d’info-bulle et l’attacher à l’objet CToolTipCtrl .

Le dwStyle paramètre peut être n’importe quelle combinaison de styles de fenêtre. En outre, un contrôle d’info-bulle a deux styles spécifiques à la classe : TTS_ALWAYSTIP et TTS_NOPREFIX.

Un contrôle d’info-bulle a les WS_POPUP styles de fenêtre et WS_EX_TOOLWINDOW de fenêtre, que vous les spécifiiez lors de la création du contrôle.

Pour créer un contrôle d’info-bulle avec des styles windows étendus, appelez CToolTipCtrl::CreateEx au lieu de Create.

Exemple

Consultez l’exemple pour CPropertySheet::GetTabControl.

CToolTipCtrl::CreateEx

Crée un contrôle (fenêtre enfant) et l’associe à l’objet CToolTipCtrl .

virtual BOOL CreateEx(
    CWnd* pParentWnd,
    DWORD dwStyle = 0,
    DWORD dwStyleEx = 0);

Paramètres

pParentWnd
Pointeur vers la fenêtre qui est le parent du contrôle.

dwStyle
Spécifie le style du contrôle d’info-bulle. Pour plus d’informationsCreate, consultez la section Remarques.

dwStyleEx
Spécifie le style étendu du contrôle en cours de création. Pour obtenir la liste des styles Windows étendus, consultez le dwExStyle paramètre correspondant CreateWindowEx dans le Kit de développement logiciel (SDK) Windows.

Valeur de retour

Différent de zéro s’il réussit sinon 0.

Notes

Utilisez CreateEx plutôt que d’appliquer Create des styles Windows étendus, spécifiés par le préface WS_EX_de style étendu Windows.

CToolTipCtrl::CToolTipCtrl

Construit un objet CToolTipCtrl.

CToolTipCtrl();

Notes

Vous devez appeler Create après avoir construit l’objet.

Exemple

// Declare a CToolTipCtrl object.
CToolTipCtrl m_ToolTipCtrl;

CToolTipCtrl::DelTool

Supprime l’outil spécifié par pWnd et nIDTool de la collection d’outils pris en charge par un contrôle d’info-bulle.

void DelTool(
    CWnd* pWnd,
    UINT_PTR nIDTool = 0);

Paramètres

pWnd
Pointeur vers la fenêtre qui contient l’outil.

nIDTool
ID de l’outil.

CToolTipCtrl::GetBubbleSize

Récupère la taille de l’info-bulle.

CSize GetBubbleSize(LPTOOLINFO lpToolInfo) const;

Paramètres

lpToolInfo
Pointeur vers la structure de TOOLINFO l’info-bulle.

Valeur de retour

Taille de l’info-bulle.

Notes

Cette fonction membre implémente le comportement du message TTM_GETBUBBLESIZE Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::GetCurrentTool

Récupère des informations, telles que la taille, la position et le texte, de la fenêtre d’info-bulle affichée par le contrôle d’info-bulle actuel.

BOOL GetCurrentTool(LPTOOLINFO lpToolInfo) const;

Paramètres

lpToolInfo
[out] Pointeur vers une TOOLINFO structure qui reçoit des informations sur la fenêtre d’info-bulle actuelle.

Valeur de retour

TRUE si les informations sont récupérées avec succès ; sinon, FALSE.

Notes

Cette méthode envoie le TTM_GETCURRENTTOOL message, qui est décrit dans le Kit de développement logiciel (SDK) Windows.

Exemple

L’exemple de code suivant récupère des informations sur la fenêtre d’info-bulle actuelle.

{
    //Get information about the current tooltip. 
    TOOLINFO tInfo = {0};
    tInfo.cbSize = sizeof(TOOLINFO);
    CToolBarCtrl& m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
    CToolTipCtrl* m_toolTip = m_toolBarCtrl.GetToolTips();
    BOOL bRet = m_toolTip->GetCurrentTool( &tInfo );
}

CToolTipCtrl::GetDelayTime

Récupère les durées initiales, contextuelles et reshows actuellement définies pour un contrôle d’info-bulle.

int GetDelayTime(DWORD dwDuration) const;

Paramètres

dwDuration
Indicateur qui spécifie la valeur de durée à récupérer. Ce paramètre peut avoir l'une des valeurs suivantes :

• TTDT_AUTOPOP Récupérez la durée pendant laquelle la fenêtre d’info-bulle reste visible si le pointeur est stationnaire dans le rectangle englobant d’un outil.

• TTDT_INITIAL Récupérez la durée pendant laquelle le pointeur doit rester stationnaire dans le rectangle englobant d’un outil avant l’affichage de la fenêtre d’info-bulle.

• TTDT_RESHOW Récupérez la durée nécessaire pour que les fenêtres d’info-bulle suivantes s’affichent à mesure que le pointeur passe d’un outil à un autre.

Valeur de retour

Délai spécifié, en millisecondes

Notes

Cette fonction membre implémente le comportement du message TTM_GETDELAYTIME Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::GetMargin

Récupère le jeu de marges supérieure, gauche, inférieure et droite pour une fenêtre d’info-bulle.

void GetMargin(LPRECT lprc) const;

Paramètres

lprc
Adresse d’une RECT structure qui recevra les informations de marge. Les membres de la RECT structure ne définissent pas de rectangle englobant. Dans le cadre de ce message, les membres de la structure sont interprétés comme suit :

Notes

Cette fonction membre implémente le comportement du message TTM_GETMARGIN Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::GetMaxTipWidth

Récupère la largeur maximale d’une fenêtre d’info-bulle.

int GetMaxTipWidth() const;

Valeur de retour

Largeur maximale d’une fenêtre d’info-bulle.

Notes

Cette fonction membre implémente le comportement du message TTM_GETMAXTIPWIDTH Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::GetText

Récupère le texte qu’un contrôle d’info-bulle conserve pour un outil.

void GetText(
    CString& str,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0) const;

Paramètres

str
Référence à un CString objet qui reçoit le texte de l’outil.

pWnd
Pointeur vers la fenêtre qui contient l’outil.

nIDTool
ID de l’outil.

Notes

Les pWnd paramètres et nIDTool les paramètres identifient l’outil. Si cet outil a été précédemment inscrit auprès du contrôle d’info-bulle par le biais d’un appel précédent, CToolTipCtrl::AddTooll’objet référencé par le str paramètre reçoit le texte de l’outil.

CToolTipCtrl::GetTipBkColor

Récupère la couleur d’arrière-plan dans une fenêtre d’info-bulle.

COLORREF GetTipBkColor() const;

Valeur de retour

Valeur COLORREF qui représente la couleur d’arrière-plan.

Notes

Cette fonction membre implémente le comportement du message TTM_GETTIPBKCOLOR Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::GetTipTextColor

Récupère la couleur du texte dans une fenêtre d’info-bulle.

COLORREF GetTipTextColor() const;

Valeur de retour

Valeur COLORREF qui représente la couleur du texte.

Notes

Cette fonction membre implémente le comportement du message TTM_GETTIPTEXTCOLOR Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::GetTitle

Récupère le titre du contrôle d’info-bulle actuel.

void GetTitle(PTTGETTITLE pttgt) const;

Paramètres

pttgt
[out] Pointeur vers une TTGETTITLE structure qui contient des informations sur le contrôle d’info-bulle. Lorsque cette méthode est retournée, le pszTitle membre de la TTGETTITLE structure pointe vers le texte du titre.

Notes

Cette méthode envoie le TTM_GETTITLE message, qui est décrit dans le Kit de développement logiciel (SDK) Windows.

CToolTipCtrl::GetToolCount

Récupère le nombre d’outils inscrits auprès du contrôle d’info-bulle.

int GetToolCount() const;

Valeur de retour

Nombre d’outils inscrits auprès du contrôle d’info-bulle.

CToolTipCtrl::GetToolInfo

Récupère les informations qu’un contrôle d’info-bulle conserve sur un outil.

BOOL GetToolInfo(
    CToolInfo& ToolInfo,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0) const;

Paramètres

ToolInfo
Référence à un TOOLINFO objet qui reçoit le texte de l’outil.

pWnd
Pointeur vers la fenêtre qui contient l’outil.

nIDTool
ID de l’outil.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0.

Notes

Les hwnd membres de uId la TOOLINFO structure référencée en CToolInfo identifiant l’outil. Si cet outil a été inscrit auprès du contrôle d’info-bulle via un appel AddToolprécédent, la TOOLINFO structure est remplie d’informations sur l’outil.

CToolTipCtrl::HitTest

Teste un point pour déterminer s’il se trouve dans le rectangle englobant de l’outil donné et, le cas échéant, récupérer des informations sur l’outil.

BOOL HitTest(
    CWnd* pWnd,
    CPoint pt,
    LPTOOLINFO lpToolInfo) const;

Paramètres

pWnd
Pointeur vers la fenêtre qui contient l’outil.

pt
Pointeur vers un CPoint objet contenant les coordonnées du point à tester.

lpToolInfo
Pointeur vers la TOOLINFO structure qui contient des informations sur l’outil.

Valeur de retour

Différent de zéro si le point spécifié par les informations de test de positionnement se trouve dans le rectangle englobant de l’outil ; sinon 0.

Notes

Si cette fonction retourne une valeur différente de zéro, la structure pointée par lpToolInfo est remplie d’informations sur l’outil dans lequel se trouve le rectangle du point.

La TTHITTESTINFO structure est définie comme suit :

typedef struct _TT_HITTESTINFO { // tthti
    HWND hwnd;   // handle of tool or window with tool
    POINT pt;    // client coordinates of point to test
    TOOLINFO ti; // receives information about the tool
} TTHITTESTINFO, FAR * LPHITTESTINFO;

• hwnd

  Spécifie le handle de l’outil.

• pt

  Spécifie les coordonnées d’un point si le point se trouve dans le rectangle englobant de l’outil.

• ti

  Informations sur l’outil. Pour plus d’informations sur la TOOLINFO structure, consultez CToolTipCtrl::GetToolInfo.

CToolTipCtrl::Pop

Supprime une fenêtre d’info-bulle affichée de l’affichage.

void Pop();

Notes

Cette fonction membre implémente le comportement du message TTM_POP Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::Popup

Provoque l’affichage du contrôle d’info-bulle actuel aux coordonnées du dernier message de la souris.

void Popup();

Notes

Cette méthode envoie le TTM_POPUP message, qui est décrit dans le Kit de développement logiciel (SDK) Windows.

Exemple

L’exemple de code suivant affiche une fenêtre d’info-bulle.

{
   // Display the most recent tooltip.
   CToolBarCtrl &m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
   CToolTipCtrl *m_toolTip = m_toolBarCtrl.GetToolTips();
   m_toolTip->Popup();
}

CToolTipCtrl::RelayEvent

Transmet un message de souris à un contrôle d’info-bulle pour le traitement.

void RelayEvent(LPMSG lpMsg);

Paramètres

lpMsg
Pointeur vers une MSG structure qui contient le message à relayer.

Notes

Un contrôle d’info-bulle traite uniquement les messages suivants, qui sont envoyés à celui-ci par RelayEvent:

Exemple

Consultez l’exemple pour CPropertySheet::GetTabControl.

CToolTipCtrl::SetDelayTime

Définit le délai d’un contrôle d’info-bulle.

void SetDelayTime(UINT nDelay);

void SetDelayTime(
    DWORD dwDuration,
    int iTime);

Paramètres

nDelay
Spécifie le nouveau délai, en millisecondes.

dwDuration
Indicateur qui spécifie la valeur de durée à récupérer. Consultez CToolTipCtrl::GetDelayTime une description des valeurs valides.

iTime
Délai spécifié, en millisecondes.

Notes

Le délai est la durée pendant laquelle le curseur doit rester sur un outil avant l’affichage de la fenêtre d’info-bulle. Le délai par défaut est de 500 millisecondes.

CToolTipCtrl::SetMargin

Définit les marges supérieure, gauche, inférieure et droite d’une fenêtre d’info-bulle.

void SetMargin(LPRECT lprc);

Paramètres

lprc
Adresse d’une RECT structure qui contient les informations de marge à définir. Les membres de la RECT structure ne définissent pas de rectangle englobant. Consultez CToolTipCtrl::GetMargin une description des informations de marge.

Notes

Cette fonction membre implémente le comportement du message TTM_SETMARGIN Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::SetMaxTipWidth

Définit la largeur maximale d’une fenêtre d’info-bulle.

int SetMaxTipWidth(int iWidth);

Paramètres

iWidth
Largeur maximale de la fenêtre d’info-bulle à définir.

Valeur de retour

Largeur maximale précédente de la pointe.

Notes

Cette fonction membre implémente le comportement du message TTM_SETMAXTIPWIDTH Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::SetTipBkColor

Définit la couleur d’arrière-plan dans une fenêtre d’info-bulle.

void SetTipBkColor(COLORREF clr);

Paramètres

clr
Nouvelle couleur d’arrière-plan.

Notes

Cette fonction membre implémente le comportement du message TTM_SETTIPBKCOLOR Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::SetTipTextColor

Définit la couleur du texte dans une fenêtre d’info-bulle.

void SetTipTextColor(COLORREF clr);

Paramètres

clr
Nouvelle couleur de texte.

Notes

Cette fonction membre implémente le comportement du message TTM_SETTIPTEXTCOLOR Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::SetTitle

Ajoute une icône standard et une chaîne de titre à une info-bulle.

BOOL SetTitle(
    UINT uIcon,
    LPCTSTR lpstrTitle);

Paramètres

uIcon
TTM_SETTITLE Consultez icon le Kit de développement logiciel (SDK) Windows.

lpstrTitle
Pointeur vers la chaîne de titre.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0.

Notes

Cette fonction membre implémente le comportement du message TTM_SETTITLE Win32, comme décrit dans le SDK Windows.

CToolTipCtrl::SetToolInfo

Définit les informations qu’une info-bulle gère pour un outil.

void SetToolInfo(LPTOOLINFO lpToolInfo);

Paramètres

lpToolInfo
Pointeur vers une TOOLINFO structure qui spécifie les informations à définir.

CToolTipCtrl::SetToolRect

Définit un nouveau rectangle englobant pour un outil.

void SetToolRect(
    CWnd* pWnd,
    UINT_PTR nIDTool,
    LPCRECT lpRect);

Paramètres

pWnd
Pointeur vers la fenêtre qui contient l’outil.

nIDTool
ID de l’outil.

lpRect
Pointeur vers une RECT structure spécifiant le nouveau rectangle englobant.

CToolTipCtrl::SetWindowTheme

Définit le style visuel de la fenêtre d’info-bulle.

HRESULT SetWindowTheme(LPCWSTR pszSubAppName);

Paramètres

pszSubAppName
Pointeur vers une chaîne Unicode qui contient le style visuel à définir.

Valeur de retour

La valeur de retour n’est pas utilisée.

Notes

Cette fonction membre émule les fonctionnalités du TTM_SETWINDOWTHEME message, comme décrit dans le Kit de développement logiciel (SDK) Windows.

CToolTipCtrl::Update

Force le redéployement de l’outil actuel.

void Update();

CToolTipCtrl::UpdateTipText

Met à jour le texte de l’info-bulle pour les outils de ce contrôle.

void UpdateTipText(
    LPCTSTR lpszText,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0);

void UpdateTipText(
    UINT nIDText,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0);

Paramètres

lpszText
Pointeur vers le texte de l’outil.

pWnd
Pointeur vers la fenêtre qui contient l’outil.

nIDTool
ID de l’outil.

nIDText
ID de la ressource de chaîne qui contient le texte de l’outil.

Voir aussi

CWnd Classe
Graphique hiérarchique
CToolBar Classe