TN028 : support technique Context-Sensitive

Cette note décrit les règles d’affectation des ID de contextes d’aide et d’autres problèmes d’aide dans MFC. La prise en charge de l’aide contextuelle nécessite le compilateur d’aide disponible dans Visual C++.

Types d’aide pris en charge

Il existe deux types d’aide contextuelle implémentées dans les applications Windows. La première, appelée « Aide F1 » implique de lancer WinHelp avec le contexte approprié en fonction de l’objet actuellement actif. Le deuxième est le mode « Maj+ F1 ». Dans ce mode, le curseur de la souris passe au curseur d’aide et l’utilisateur continue à cliquer sur un objet. À ce stade, WinHelp est lancé pour donner de l’aide à l’objet sur lequel l’utilisateur a cliqué.

Les classes Microsoft Foundation implémentent ces deux formes d’aide. En outre, l’infrastructure prend en charge deux commandes d’aide simples, Help Index et Using Help.

Fichiers d’aide

Les classes Microsoft Foundation supposent un seul fichier d’aide. Ce fichier d’aide doit avoir le même nom et le même chemin que l’application. Par exemple, si l’exécutable est C:\MyApplication\MyHelp.exe le fichier d’aide doit être C :\MyApplication\MyHelp.hlp. Vous définissez le chemin d’accès via la variable membre m_pszHelpFilePath de la classe CWinApp.

Plages de contexte d’aide

L’implémentation par défaut de MFC nécessite qu’un programme suive certaines règles relatives à l’attribution d’ID de contexte d’aide. Ces règles sont une plage d’ID alloués à des contrôles spécifiques. Vous pouvez remplacer ces règles en fournissant différentes implémentations des différentes fonctions membres associées à l’aide.

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 « Aide » simples

Il existe deux commandes d’aide simples implémentées par les classes Microsoft Foundation :

• ID_HELP_INDEX implémenté par CWinApp ::OnHelpIndex

• ID_HELP_USING implémenté par CWinApp ::OnHelpUsing

La première commande affiche l’index d’aide de l’application. La deuxième montre l’aide de l’utilisateur sur l’utilisation du programme WinHelp.

aide Context-Sensitive (aide F1)

La touche F1 est généralement traduite en commande avec un ID de ID_HELP par un accélérateur placé dans la table d’accélérateur de la fenêtre principale. La commande ID_HELP peut également être générée par un bouton avec un ID de ID_HELP sur la fenêtre principale ou la boîte de dialogue.

Quelle que soit la façon dont la commande ID_HELP est générée, elle est routée en tant que commande normale jusqu’à ce qu’elle atteigne un gestionnaire de commandes. Pour plus d’informations sur l’architecture de routage des commandes MFC, consultez la note technique 21. Si l’application a activé l’aide, la commande ID_HELP sera gérée par CWinApp ::OnHelp. L’objet d’application reçoit le message d’aide, puis route la commande de manière appropriée. Cela est nécessaire, car le routage des commandes par défaut n’est pas adéquat pour déterminer le contexte le plus spécifique.

CWinApp::OnHelp tente de lancer WinHelp dans l’ordre suivant :

1. Recherche un appel actif AfxMessageBox avec un ID d’aide. Si une boîte de message est actuellement active, WinHelp est lancé avec le contexte approprié à cette boîte de message.

2. Envoie un message 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 soit traité ou que la fenêtre active soit une fenêtre de niveau supérieur.

3. Envoie une commande ID_DEFAULT_HELP à la fenêtre principale. Cela appelle l’aide par défaut. Cette commande est généralement mappée à CWinApp::OnHelpIndex.

Pour remplacer globalement les valeurs de base d’ID par défaut (par exemple, 0x10000 pour les commandes et les 0x20000 pour les ressources telles que les boîtes de dialogue), l’application doit remplacer CWinApp ::WinHelp.

Pour remplacer cette fonctionnalité et la façon dont un contexte d’aide est déterminé, vous devez gérer le message WM_COMMANDHELP. Vous souhaiterez peut-être fournir un routage d’aide plus spécifique que celui fourni par l’infrastructure, car il est aussi profond que la fenêtre enfant MDI actuelle. Vous pouvez également fournir une aide plus spécifique pour une fenêtre ou une boîte de dialogue particulière, peut-être en fonction de l’état interne actuel de cet objet ou du 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 Windows MFC privé reçu par la fenêtre active lorsque l’aide est demandée. Lorsque la fenêtre reçoit ce message, elle peut appeler CWinApp::WinHelp avec un contexte qui correspond à l’état interne de la fenêtre.

lParam
Contient le contexte d’aide actuellement disponible. lParam est égal à zéro si aucun contexte d’aide n’a été déterminé. Une implémentation de OnCommandHelp peut utiliser l’ID de contexte dans lParam pour déterminer un contexte différent ou peut simplement le transmettre à CWinApp::WinHelp.

wParam
N’est pas utilisé et sera égal à zéro.

Si la OnCommandHelp fonction appelle CWinApp::WinHelp, elle doit retourner TRUE. Le renvoi de TRUE arrête le routage de cette commande vers d’autres classes et vers d’autres fenêtres.

Mode d’aide (Aide Maj+F1)

Il s’agit de la deuxième forme d’aide contextuelle. En règle générale, ce mode est entré en appuyant sur Maj+F1 ou via le menu/barre d’outils. Il est implémenté en tant que commande (ID_CONTEXT_HELP). Le hook de filtre de message n’est pas utilisé pour traduire cette commande alors qu’une boîte de dialogue modale ou un menu est actif. Par conséquent, cette commande est disponible uniquement pour l’utilisateur lorsque l’application exécute la pompe de messages principale (CWinApp::Run).

Après avoir entré ce mode, le curseur de la souris d’aide s’affiche sur toutes les zones de l’application, même si l’application affiche normalement son propre curseur pour cette zone (par exemple, la bordure de dimensionnement autour de la fenêtre). L’utilisateur peut utiliser la souris ou le 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 à l’écran, tel qu’un bouton de la barre d’outils, et l’aide s’affiche pour cet objet. Ce mode d’aide est fourni par CWinApp::OnContextHelp.

Pendant l’exécution de cette boucle, toutes les entrées de clavier sont inactives, à l’exception des touches qui accèdent au menu. En outre, la traduction de commandes est toujours effectuée via PreTranslateMessage pour permettre à l’utilisateur d’appuyer sur une touche d’accélérateur et de recevoir de l’aide sur cette commande.

S’il existe des traductions ou des actions particulières qui se produisent dans la fonction qui ne doivent pas avoir lieu pendant le PreTranslateMessage mode d’aide MAJ+F1, vous devez vérifier le membre m_bHelpMode avant d’effectuer CWinApp ces opérations. Implémentation CDialog de PreTranslateMessage vérifications avant d’appeler IsDialogMessage, par exemple. Cela désactive les touches de « navigation de boîte de dialogue » sur les dialogues sans mode pendant le mode Maj+F1. En outre, CWinApp::OnIdle est toujours appelé pendant cette boucle.

Si l’utilisateur choisit une commande dans le menu, elle est gérée comme aide sur cette commande (via WM_COMMANDHELP, voir ci-dessous). Si l’utilisateur clique sur une zone visible de la fenêtre des applications, une détermination est faite quant à savoir s’il s’agit d’un clic non client ou d’un clic client. OnContextHelp gère automatiquement le mappage des clics non clients aux clics clients. S’il s’agit d’un clic client, il envoie une 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 comme contexte d’aide. S’il retourne zéro, OnContextHelp tente la fenêtre parente (et échoue, son parent, etc.). Si un contexte d’aide ne peut pas être déterminé, la valeur par défaut consiste à envoyer une commande ID_DEFAULT_HELP à la fenêtre principale, qui est ensuite (généralement) mappée à CWinApp::OnHelpIndex.

WM_HELPHITTEST

afx_msg LRESULT CWnd::OnHelpHitTest(
WPARAM, LPARAM lParam)

WM_HELPHITTEST est un message de fenêtre privée MFC reçu par la fenêtre active sur laquelle la fenêtre active a cliqué pendant le mode d’aide Maj+F1. Lorsque la fenêtre reçoit ce message, elle retourne un ID d’aide DWORD à utiliser par WinHelp.

LOWORD(lParam) contient la coordonnée d’appareil de l’axe X où la souris a été cliquée par rapport à la zone cliente de la fenêtre.

HIWORD(lParam) contient la coordonnée de l’axe Y.

wParam
n’est pas utilisé et sera égal à zéro. Si la valeur de retour n’est pas nulle, WinHelp est appelé avec ce contexte. Si la valeur de retour est égale à zéro, la fenêtre parente est interrogée pour obtenir de l’aide.

Dans de nombreux cas, vous pouvez tirer parti du code de test de positionnement que vous avez peut-être déjà. Consultez l’implémentation d’un CToolBar::OnHelpHitTest exemple de gestion du message WM_HELPHITTEST (le code tire parti du code de test de positionnement utilisé sur les boutons et les 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 .cnt et .hpj). Il inclut également un certain nombre de fichiers .rtf prédéfinis acceptés par le compilateur d’aide Microsoft. La plupart des rubriques sont complètes, mais certaines peuvent avoir besoin d’être modifiées 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 traduire la ressource d’une application. Fichier H 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 l’installation du compilateur d’aide, qui mappe les ID de contexte (les nombres du côté droit) avec les noms de rubriques (les symboles sur le côté gauche).

Le code source de MAKEHM est disponible dans l’exemple MAKEHM des utilitaires de programmation MFC.

Ajout de la prise en charge de l’aide après l’exécution de l’Assistant Application MFC

La meilleure façon d’ajouter de l’aide à votre application consiste à vérifier l’option « Aide contextuelle » dans la page Fonctionnalités avancées de l’Assistant Application MFC avant de créer votre application. De cette façon, l’Assistant Application MFC ajoute automatiquement les entrées de mappage de messages nécessaires à votre CWinAppclasse dérivée pour prendre en charge l’aide.

Aide sur les boîtes de message

L’aide sur les boîtes de message (parfois appelées alertes) est prise en charge par le biais de la AfxMessageBox fonction, wrapper pour l’API MessageBox Windows.

Il existe deux versions , une pour une utilisation avec un ID de AfxMessageBoxchaîne et une autre pour une utilisation avec un pointeur vers 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 d’aide facultatif.

Dans le premier cas, la valeur par défaut de nIDHelp est 0, ce qui indique aucune aide pour cette zone de message. Si l’utilisateur appuie sur F1 pendant que la boîte de message est active, l’utilisateur ne reçoit pas d’aide (même si l’application prend en charge l’aide). Si ce n’est pas souhaitable, un ID d’aide doit être fourni pour nIDHelp.

Dans le deuxième cas, la valeur par défaut de nIDHelp est -1, ce qui indique que l’ID d’aide est identique à nIDPrompt. L’aide fonctionne uniquement si l’application est activée pour l’aide, bien sûr). Vous devez fournir 0 pour nIDHelp si vous souhaitez que la boîte de message ne dispose d’aucun support technique. Si vous souhaitez que le message soit activé, mais souhaitez un ID d’aide différent de nIDPrompt, fournissez simplement une valeur positive pour nIDHelp différent de celui de nIDPrompt.

Voir aussi

Notes techniques par numéro
Notes techniques par catégorie