Cette note décrit les règles d'attribution d'aide des contextes IDs (c'est-à-dire les numéros de rubrique) et autres questions d'aide dans MFC 2.0. Aide contextuelle exige que le compilateur d'aide qui est disponible dans Visual C++ Professional.
Types d'aide pris en charge
Il existe deux types d'aide contextuelle, mis en œuvre dans les applications Windows. La première, appelée « F1 aide » consiste à lancer WinHelp avec le contexte approprié basé sur l'objet actif. Le second est le mode SHIFT + F1. Dans ce mode, le curseur de la souris change le curseur d'aide (une flèche de combinaison + point d'interrogation), et produit de l'utilisateur de cliquer sur l'objet, sur qu'ils aimeraient aider. À ce moment-là, WinHelp est lancé en accordant une aide de l'objet sur lequel l'utilisateur a cliqué.
Les classes Microsoft Foundation implémentent tous deux de ces formes d'aide. En outre, le framework prend en charge deux commandes d'aide simple, Index de l'aide et l'utilisation de l'aide.
Fichiers d'aide
Les classes Microsoft Fondation supposent un seul fichier d'aide. Que le fichier d'aide doit avoir le même nom et chemin d'accès que l'application (.EXE - >.HLP).
Il s'agit d'une variable de membre CWinApp publique nommée m_pszHelpFilePath que l'utilisateur peut modifier si vous le souhaitez.
Chaînes de contexte aide
0 x 00000000 - 0x0000FFFF : définis par l'utilisateur
0x00010000 - 0x0001FFFF : commandes (boutons de menus/commande)
; 0X00010000 + ID_
nbsp ; (note : 0x18000 - > 0x1FFFF est portée pratique puisque les ID de commande est > = 0 x 8000)
0x00020000 - 0x0002FFFF : les fenêtres et boîtes de dialogue
; 0X00020000 + IDR_
nbsp ; (note : est - > 0x27FFF est portée pratique puisque les approfondis sont < = 0x7FFF)
0x00030000 - 0x0003FFFF : messages d'erreur (fondés sur l'erreur string ID)
; 0X00030000 + IDP_
0x00040000 - 0x0004FFFF : objet spécial (zones non client)
; 0x00040000 + aire HitTest
0x00050000 - 0x0005FFFF : contrôles (ceux qui ne sont pas des commandes)
; 0X00040000 + IDW_
Ces règles sont codés en dur dans l'implémentation par défaut des classes Microsoft Foundation. Ils peuvent être substituées en fournissant des implémentations différentes de diverses fonctions liées à l'aide des membres.
Commandes simples « Aider »
Il y a deux commandes aide simples qui sont implémentées par les classes Microsoft Foundation:
Ces deux commandes simplement afficher l'index de l'aide pour l'application et afficher l'aide utilisateur à l'aide du programme de WinHelp, respectivement.
Aide contextuelle (aide F1)
Il s'agit de la première forme de l'aide contextuelle (habituellement appelée F1 aide). L'utilisateur appuie sur F1 pour obtenir de l'aide sur la tâche à accomplir (la fenêtre ou le menu élément actif). Aucun spécial « mode d'aide » n'est impliqué.
La touche F1 est généralement traduite à une commande avec un ID de ID_HELP par un accélérateur placé sur la table d'accélérateurs de la fenêtre principale. La commande ID_HELP peut également être générée par un bouton avec un ID ID_HELP sur la principale fenêtre ou boîte de dialogue. Aussi, lorsqu'un menu ou une boîte de dialogue est active et que l'utilisateur appuie sur F1, la frappe est codé en dur à traduire dans une commande ID_HELP.
Toutefois, la commande ID_HELP est générée, il est acheminé comme une commande normale jusqu'à ce qu'elle atteigne un gestionnaire de commandes (pour plus d'informations sur la Microsoft Foundation classes commande-architecture de routage, consultez Technical Note 21.) Si l'application est activée de l'aide, la commande ID_HELP sera assurée par la fonction CWinApp::OnHelp . Étant donné que le routage de commandes par défaut n'est pas suffisant pour déterminer le contexte plus précis la commande est plutôt toujours acheminée à l'objet application et subit alors un routage personnalisé à l'aide.
CWinApp::OnHelp tente de lancer WinHelp dans l'ordre suivant
À l'échelle mondiale substituer les valeurs de base ID (0x10000 pour les commandes, est pour les ressources telles que les boîtes de dialogue et ainsi de suite), l'application doit substituer CWinApp::WinHelp. Cela est fait dans la mise en œuvre des applications ClassWizard et AppWizard eux-mêmes, par exemple, étant donné que les deux partagent un seul fichier d'aide.
Pour substituer cette fonctionnalité et la façon qu'un contexte d'aide est déterminé, une application doit gérer le message WM_COMMANDHELP (voir ci-dessous). Vous pouvez fournir plus spécifiques aide routage que le cadre de l'offre, comme il seulement va plus profondes comme la fenêtre enfant MDI en cours. Ou vous pouvez fournir une aide plus spécifique pour une boîte de dialogue--peut-être basée sur l'état interne de l'objet ou le contrôle actif dans la boîte de dialogue ou une fenêtre particulière.
WM_COMMANDHELP
afx_msg LRESULT CWnd::OnCommandHelp (WPARAM, LPARAM lParam)
WM_COMMANDHELP est un message de Windows privé de MFC qui est 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 avec contexte correspondant à l'état interne de la fenêtre.
lParam
contient le contexte aide actuellement disponible. lParam est zéro si aucun contexte d'aide n'a été déterminée encore. Une implémentation de OnCommandHelp pouvez utiliser l'ID de contexte lParam pour déterminer un contexte « mieux » ou peut simplement passer à CWinApp::WinHelp.
wParam
n'est pas utilisé et sera nulle.
Si la fonction OnCommandHelp appelle CWinApp::WinHelp, il doit retourner TRUE. Retourne TRUE s'arrête l'acheminement de cette commande à d'autres classes (classes de base) et d'autres fenêtres.
Mode d'aide (aide de Shift + F1)
Il s'agit de la deuxième forme d'aide contextuelle. En général, ce mode est entré en appuyant sur SHIFT + F1 ou via le menu/barre d'outils. Il est implémenté comme une commande (ID_CONTEXT_HELP). Le crochet de filtre de message n'est pas utilisé pour traduire cette commande alors que d'une boîte de dialogue modale ou menu est actif, donc cette commande est uniquement disponible pour l'utilisateur lorsque l'application est l'exécution de la pompe de messages principale (CWinApp::Run).
Après être entré dans ce mode, le curseur de la souris aide s'affiche dans tous les domaines de l'application, même si la demande serait normalement afficher son propre curseur pour cette région (tels que la bordure de redimensionnement autour de la fenêtre). L'utilisateur est en mesure d'utiliser la souris ou le clavier pour sélectionner une commande. Au lieu de l'exécution de la commande, aide sur cette commande est affichée. Aussi l'utilisateur peut cliquer sur un objet visible à l'écran, comme un bouton sur la barre d'outils, et aide s'affichera pour cet objet. Ce mode d'aide est fourni par CWinApp::OnContextHelp.
Lors de l'exécution de cette boucle, tous les claviers d'entrée est inactif, sauf pour les touches qui accéder au menu. Aussi, la traduction de commande est toujours réalisée via PreTranslateMessage pour permettre à l'utilisateur d'appuyer sur une touche accélérateur et recevoir de l'aide sur cette commande.
S'il y a des traductions particulières ou des actions qui se déroulent dans la fonction PreTranslateMessage qui ne devrait pas avoir lieu en mode SHIFT + F1 aide, vous devez vérifier le membre m_bHelpMode de CWinApp avant d'effectuer ces opérations. La mise en œuvre de CDialog de PreTranslateMessage vérifie cela avant d'appeler IsDialogMessage, par exemple. Cela désactive les touches « navigation de la boîte de dialogue » sur les boîtes de dialogue non modales en mode SHIFT + F1. En outre, CWinApp::OnIdle est encore appelée au cours de cette boucle.
Si l'utilisateur choisit une commande dans le menu, il est géré comme aide sur cette commande (par le biais de WM_COMMANDHELP, voir ci-dessous). Si l'utilisateur clique sur une zone visible de la fenêtre des applications, une décision est prise quant à la question de savoir si c'est un clic non cliente ou un client clic. OnContextHelp gère automatiquement la cartographie des clics non cliente aux clics sur le client. Si c'est un clic du client, il envoie un WM_HELPHITTEST à la fenêtre qui a été cliquée. Si cette fenêtre retourne une valeur différente de zéro, cette valeur est utilisée dans le contexte de l'aide. Si elle retourne zéro, OnContextHelp essaie de la fenêtre parente (et sinon, son parent et ainsi de suite). Si un contexte d'aide ne peut être déterminé, la valeur par défaut est d'envoyer une commande ID_DEFAULT_HELP à la fenêtre principale, qui est ensuite (normalement) CWinApp::OnHelpIndex.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest (WPARAM, LPARAM lParam)
WM_HELPHITTEST est un message privé windows MFC, qui est reçu par la fenêtre active en un clic en mode d'aide de MAJ + F1. Lorsque la fenêtre reçoit ce message, elle retourne un ID d'aide DWORD pour utilisation par WinHelp.
LOWORD(lParam)
contient les coordonnées de périphérique axe où la souris est cliquée par rapport à la zone cliente de la fenêtre.
HIWORD(lParam)
contient les coordonnées de l'axe des ordonnées.
wParam
n'est pas utilisé et sera nulle. Si la valeur de retour est différente de zéro, WinHelp est appelée avec ce contexte. Si la valeur de retour est zéro, la fenêtre parente est interrogée à l'aide.
Dans de nombreux cas, vous pouvez utiliser le code de test, que vous devrez peut-être déjà. Voir la mise en œuvre de CToolBar::OnHelpHitTest pour obtenir un exemple de la gestion du message WM_HELPHITTEST (le code s'appuie sur le code de hit-test utilisé sur les boutons et les info-bulles de CControlBar).
Prise en charge MFC AppWizard et MAKEHM
AppWizard crée les fichiers nécessaires pour générer un fichier d'aide (fichiers .cnt et .hpj). Il comprend également un certain nombre de parties.Fichiers RTF qui sont acceptées par le compilateur d'aide de Microsoft. La plupart des sujets sont complets, mais certains peuvent doivent être modifiées pour votre application spécifique.
Création automatique d'un fichier « aider la cartographie » est pris en charge par un utilitaire appelé MAKEHM. L'utilitaire MAKEHM peut traduire ressource d'une demande.Fichier à un fichier de mappage aide H. Par exemple:
# define IDD_MY_DIALOGnbsp ; 2000
# define ID_MY_COMMA&ND 150
sera traduit en:
HIDD_MY_DIALOGnbsp ; 0x207d0
HID_MY_COMMA&ND 0X10096
Ce format est compatible avec l'installation de l'aide du compilateur, qui mappe l'ID de contexte (les nombres sur la droite) avec les noms de sujet (les symboles sur le côté gauche).
Le code source pour MAKEHM est disponible dans l'échantillon Utilties de programmation MFC MAKEHM.
Ajouter le Support de l'aide après l'exécution de AppWizard
La meilleure façon d'ajouter l'aide à votre application est Cochez l'option « Aide sensible au contexte » dans la boîte de dialogue Options de AppWizard avant de créer votre application. De cette façon AppWizard ajoute automatiquement les entrées de la carte message nécessaire à votre classe dérivée de CWinApp à l'appui d'aide.
Si vous avez déjà créé votre application sans le soutien de l'aide et souhaitez maintenant pour l'ajouter, voir le Guide du programmeur Visual C++.
Aide sur les boîtes de Message
Aide sur les boîtes de Message (parfois appelé alertes) est pris en charge par la fonction AfxMessageBox , un wrapper de l'API de Windows MessageBox.
Il existe deux versions AfxMessageBox, un pour une utilisation avec un ID de chaîne et l'autre pour une utilisation avec un pointeur de 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 y a un ID facultatif aide.
Dans le premier cas, la valeur par défaut de nIDHelp est 0, ce qui n'indique aucune aide de cette boîte de message. Si l'utilisateur appuie sur F1 pendant que comme message box est actif, l'utilisateur recevra pas aide (même si l'application prend en charge d'aide). Si ce n'est pas souhaitable, un ID d'aide doivent être fourni pour nIDHelp.
Dans le second cas, la valeur par défaut de nIDHelp est -1, qui indique l'ID d'aider est le même que nIDPrompt. Aide ne fonctionnera que si l'application est activée par l'aide, bien sûr). Vous devez fournir 0 de nIDHelp si vous souhaitez que la boîte de message n'ont aucune aide. Si vous voulez le message à l'aide activée, mais souhaitent un aide différents ID que nIDPrompt, simplement fournir une valeur positive pour nIDHelp différent de celui de nIDPrompt.
&Notes techniques par le numéro |nbsp ; Notes techniques par catégorie