TN028 : Prise en charge d'aide contextuelle
Cette remarque décrit les règles pour assigner des identificateurs d'aide de contextes et d'autres problèmes d'aide dans MFC.La prise en charge d'aide contextuelle requiert le compilateur d'aide qui est disponible dans Visual C++.
[!REMARQUE]
En plus de l'implémentation l'aide contextuelle à l'aide de WinHelp, prend en charge MFC également utiliser l'aide HTML.Pour plus d'informations sur cette prise en charge et la programmation avec HTML help, consultez l' aide HTML : aide contextuelle pour vos programmes.
Types d'aide pris en charge
Il existe deux types d'aide contextuelle implémentés dans les applications Windows.Le premier, sous le nom de « F1 aide » implique lancer WinHelp au contexte approprié en fonction actuellement - l'objet actif.Le deuxième est mode « Shift+ F1 ».Dans ce mode, le curseur de la souris est remplacé par le curseur d'aide, et l'utilisateur continue à cliquer sur un objet.À ce stade, WinHelp est lancé pour donner à l'aide de l'objet que l'utilisateur a cliqué sur.
Microsoft Foundation Classes implémentent les deux formulaires d'aide.De plus, l'infrastructure prend en charge deux commandes d'aide simples, index de l'aide et guide d'utilisation.
Fichiers d'aide
Les classes MFC (Microsoft Foundation supposent qu'il existe un fichier d'aide unique.Ce fichier d'aide doit avoir le même nom et chemin d'accès que l'application.Par exemple, si le fichier exécutable est C : \MyApplication\MyHelp.exe the help file must be C:\MyApplication\MyHelp .hlp.Définissez le chemin d'accès par le biais de la variable membre d' m_pszHelpFilePath de CWinApp, classe.
Chaînes de contexte d'aide
L'implémentation par défaut de MFC requiert un programme pour suivre des règles sur l'assignation des identificateurs de contexte d'aide.Ces règles sont une plage des identificateurs alloués aux contrôles spécifiques.Vous pouvez substituer ces règles en fournissant des implémentations des différentes fonctions membres Aide-mises en relation.
0x00000000 - 0x0000FFFF : user defined
0x00010000 - 0x0001FFFF : commands (menus/command buttons)
0x00010000 + ID_
(note: 0x18000-> 0x1FFFF is the practical range since command IDs are >=0x8000)
0x00020000 - 0x0002FFFF : windows and dialogs
0x00020000 + IDR_
(note: 0x20000-> 0x27FFF is the practical range since IDRs are <= 0x7FFF)
0x00030000 - 0x0003FFFF : error messages (based on error string ID)
0x00030000 + IDP_
0x00040000 - 0x0004FFFF : special purpose (non-client areas)
0x00040000 + HitTest area
0x00050000 - 0x0005FFFF : controls (those that are not commands)
0x00040000 + IDW_
Commandes « d'aide » simples
Il existe deux commandes d'aide simples qui sont implémentées par Microsoft Foundation Classes :
ID_HELP_INDEX implémentée par CWinApp::OnHelpIndex
ID_HELP_USING implémentée par CWinApp::OnHelpUsing
La première commande indique l'index de l'aide pour l'application.La seconde illustre l'utilisation d'utilisateur sur l'utilisation du programme de WinHelp.
Aide contextuelle (F1 aide)
La touche F1 est généralement traduite en une commande avec un ID d' ID_HELP par un accélérateur placé dans la table d'accélérateurs de la fenêtre principale.L'ordre d' ID_HELP peut également être générée par un bouton avec un ID d' ID_HELP dans la fenêtre principale ou la boîte de dialogue.
Quelle que soit la façon dont l'ordre d' ID_HELP est générée, il est routé comme commande normale jusqu'à ce qu'il atteigne un gestionnaire de commandes.Pour plus d'informations sur l'architecture de routage de commandes MFC, reportez -vous à note technique 21.Si l'application a l'aide activée, la commande d' ID_HELP sera gérée par CWinApp::OnHelp.L'objet application reçoit le message d'aide puis route la commande appropriée.Ceci est nécessaire parce que le routage des commandes par défaut ne convient pas à déterminer le contexte le plus spécifique.
Tente d'CWinApp::OnHelp de lancer WinHelp dans l'ordre suivant :
Contrôles pour un appel actif d' AfxMessageBox avec un ID d'aideSi un message est actuellement active, WinHelp est lancé au contexte approprié à ce message.
Envoie un message de WM_COMMANDHELP à la fenêtre active.Si cette fenêtre ne répond pas en lançant WinHelp, le même message est ensuite envoyé aux ancêtres de cette fenêtre jusqu'à ce que le message doit être traité ou la fenêtre active est une fenêtre de niveau supérieur.
Envoie une commande d'ID_DEFAULT_HELP à la fenêtre principale.Il appelle l'utilisation par défaut.Cette commande est généralement mappée à CWinApp::OnHelpIndex.
Pour substituer globalement l'ID par défaut basez les valeurs (par exemple.0x10000 pour les commandes et 0x20000 pour les ressources telles que les boîtes de dialogue), l'application doivent substituer CWinApp::WinHelp.
Pour substituer cette fonctionnalité et la façon dont un contexte d'aide est déterminé, vous devez traiter le message de WM_COMMANDHELP.Vous pouvez fournir plus de routage d'aide spécifique que l'infrastructure la fournit, car elle seulement plus profondément que la fenêtre enfant MDI actuelle.Vous pouvez également fournir plus d'aide spécifique pour une fenêtre ou de dialogue particulière, peut-être en fonction de l'état interne en cours de l'objet ou le contrôle actif dans la boîte de dialogue.
WM_COMMANDHELP
afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)
WM_COMMANDHELP est un message privé de MFC windows reçu par la fenêtre active lorsque l'aide est demandée.Lorsque la fenêtre reçoit ce message, il peut appeler CWinApp::WinHelp au contexte qui correspond à l'état interne de la fenêtre.
lParam
Contient le contexte d'aide disponible.lParam est zéro si aucun contexte d'aide n'a été déterminée.Une implémentation d' OnCommandHelp peut utiliser l'ID de contexte dans lParam pour déterminer un contexte différent ou peut simplement le passer à CWinApp::WinHelp.wParam
n'est pas utilisé et sera zéro.
Si les appels de fonction d' OnCommandHelpCWinApp::WinHelp, il retournent TRUE.Retourner TRUE arrête le routage de cette commande à d'autres classes et à d'autres fenêtres.
Mode d'aide (aide Shift+F1)
Il s'agit du deuxième formulaire de l'aide contextuelle.En général, ce mode est déplacé en appuyant sur MAJ+F1 ou via le menu/barre d'outils.Il est implémenté en tant que commande (ID_CONTEXT_HELP).Le raccordement de filtre de messages n'est pas utilisé pour convertir cette commande pendant qu'une boîte de dialogue modales ou un menu est active, par conséquent cette commande est uniquement disponible pour l'utilisateur lorsque l'application exécute la pompe de messages principale (CWinApp::Run).
Après passage imminent ce mode, le curseur de la souris d'aide est affiché sur tous les domaines d'application, même si l'application afficherait normalement son propre curseur pour cette zone (telle que la bordure de redimensionnement autour de la fenêtre).L'utilisateur peut utiliser la souris ou du clavier pour sélectionner une commande.Au lieu d'exécuter la commande, l'aide sur cette commande s'affiche.En outre, l'utilisateur peut cliquer sur un objet visible sur l'écran, tel qu'un bouton dans la barre d'outils, puis l'aide est affichée pour cet objet.Ce mode d'aide est fourni par CWinApp::OnContextHelp.
Pendant l'exécution de cette boucle, toutes les entrées au clavier est inactive, à l'exception de les clés qui accèdent au menu.En outre, la traduction de commande est encore exécutée via PreTranslateMessage pour permettre à l'utilisateur d'appuyer sur une touche accélérateur et de recevoir l'aide sur cette commande.
S'il existe des interprétations particulières ou des actions ayant lieu dans PreTranslateMessage fonction qui ne doit pas avoir lieu pendant le mode d'aide MAJ+F1, vous devez activer le membre d' m_bHelpMode d' CWinApp avant d'effectuer ces opérations.L'implémentation d' CDialog d' PreTranslateMessage active cette avant d'appeler IsDialogMessage, par exemple.Cela désactive les touches de navigation « dialogue » sur des boîtes de dialogue non modale en mode MAJ+F1.En outre, CWinApp::OnIdle est encore appelé pendant cette boucle.
Si l'utilisateur choisit une commande de menu, il est géré comme aide sur cette commande (par WM_COMMANDHELP, voir ci-dessous).Si l'utilisateur clique sur une zone visible de la fenêtre d'applications, une détermination est faite si c'est un clic non cliente ou un clic client.Mapper de handles d'OnContextHelp les clics non clients aux clics clients automatiquement.S'il s'agit d'un clic client, il envoie ensuite WM_HELPHITTEST à la fenêtre qui a cliqué.Si cette fenêtre retourne une valeur différente de zéro, cette valeur est utilisée comme contexte pour demander une assistance.S'il retourne zéro, OnContextHelp essaie la fenêtre parente (et manquer place, son parent, et ainsi de suite).Si un contexte d'aide ne peut pas être déterminé, la valeur par défaut consiste à envoyer une commande d' ID_DEFAULT_HELP à la fenêtre principale, qui ensuite (généralement) est mappée à CWinApp::OnHelpIndex.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest(WPARAM, LPARAM lParam)
WM_HELPHITTEST est un message privé de fenêtres MFC reçu par la fenêtre active sélectionnée en mode d'aide MAJ+F1.Lorsque la fenêtre reçoit ce message, elle retourne un ID d'aide DWORD en vue de WinHelp.
LOWORD (lParam)
contient les coordonnées de périphérique d'axe des abscisses où la souris a été effectué par rapport à la zone cliente de la fenêtre.HIWORD (lParam)
contient la coordonnée d'axe Y.wParam
n'est pas utilisé et sera zéro.Si la valeur de retour est différente de zéro, WinHelp est appelé avec ce contexte.Si la valeur de retour est zéro, la fenêtre parente est interrogée pour demander une assistance.
Dans de nombreux cas, vous pouvez exploiter code de test d'atteinte que vous disposiez déjà d'.Consultez l'implémentation de CToolBar::OnHelpHitTest pour obtenir un exemple de gérer le message de WM_HELPHITTEST (code tire parti du code de test de positionnement utilisé sur les boutons et des info-bulles dans CControlBar).
Prise en charge de l'Assistant Application MFC et MAKEHM
L'Assistant Application MFC crée les fichiers nécessaires pour générer un fichier d'aide (fichiers de .cnt et de .hpj).Il inclut également un certain nombre de fichiers .rtf pré-conçus qui sont reçus par le compilateur d'aide Microsoft.Plusieurs des rubriques sont terminés, mais certains peuvent devoir être modifiés pour votre application spécifique.
La création automatique d'un fichier « de mappage d'aide » est prise en charge par un utilitaire appelé MAKEHM.L'utilitaire MAKEHM peut convertir le fichier du RESOURCE.H d'une application dans un fichier de mappage d'aide.Par exemple :
#define IDD_MY_DIALOG 2000
#define ID_MY_COMMAND 150
sera traduit en :
HIDD_MY_DIALOG 0x207d0
HID_MY_COMMAND 0x10096
Ce format est compatible avec les fonctionnalités d'aide du compilateur, qui mappe les identificateurs de contexte (nombres à droite) avec les noms d'élément (les symboles sur le côté gauche).
Le code source pour MAKEHM est disponible dans la programmation MFC l'exemple MAKEHMd'Utilitaires.
Utilisation d'ajout après avoir exécuté l'Assistant Application MFC
Le meilleur moyen d'ajouter l'aide à votre application consiste à activer l'option « aide contextuelle » dans la page de fonctionnalité avancée de l'Assistant Application MFC avant de créer votre application.De cette façon Assistant Application MFC ajoute automatiquement les entrées de la table des messages nécessaires à votre CWinAppclasse dérivée à l'aide de support.
Aide sur des messages
L'aide sur les messages (parfois appelés des alertes) est prise en charge par le biais de la fonction d' AfxMessageBox , wrapper pour l'API Windows d' MessageBox .
Il existe deux versions d' AfxMessageBox, d'un à utiliser avec un ID de chaîne et un autre pour une utilisation avec un pointeur vers la chaîne (LPCSTR) :
int AFXAPI AfxMessageBox(LPCSTR lpszText, UINT nType, UINT nIDHelp);
int AFXAPI AfxMessageBox(UINT nIDPrompt, UINT nType, UINT nIDHelp);
Dans les deux cas, il existe un ID facultative d'aide
Dans la première cas, la valeur par défaut pour le nIDHelp est 0, qui n'indique pas d'aide pour ce message.Si l'utilisateur appuie sur F1 pendant que tels que le message est actif, l'utilisateur ne reçoit pas l'aide (même si l'aide de l'application prend en charge).Si ce n'est pas souhaitable, un ID d'assistance doit être fourni pour le nIDHelp.
Dans la deuxième cas, la valeur par défaut pour le nIDHelp est -1, qui indique l'ID d'aide est identique au nIDPrompt.L'aide fonctionne uniquement si l'application Aide-est activée, naturellement).Vous devez fournir 0 pour le nIDHelp si vous souhaitez que le message n'ont pas d'aide.Si vous souhaitez que le message pour être aide activée, mais souhaitez un ID d'aide différent du nIDPrompt, indiquez simplement une valeur positive du nIDHelp différent de celui du nIDPrompt.