Macros de table des messages (MFC)

Pour prendre en charge les mappages de messages, MFC fournit les macros suivantes :

Macros de déclaration et de démarcation de carte de message

Nom	Description
DECLARE_MESSAGE_MAP	Déclare qu’un mappage de messages sera utilisé dans une classe pour mapper les messages aux fonctions (doit être utilisé dans la déclaration de classe).
BEGIN_MESSAGE_MAP	Commence la définition d’un mappage de messages (doit être utilisée dans l’implémentation de classe).
BEGIN_TEMPLATE_MESSAGE_MAP	Commence la définition d’un mappage de messages sur un type de classe contenant un seul argument de modèle.
END_MESSAGE_MAP	Termine la définition d’un mappage de messages (doit être utilisée dans l’implémentation de classe).

Macros de mappage de messages

Nom	Description
ON_COMMAND	Indique la fonction qui gère un message de commande spécifié.
ON_COMMAND_EX	Indique la fonction qui gère un message de commande spécifié.
ON_CONTROL	Indique quelle fonction gère un message de notification de contrôle spécifié.
ON_MESSAGE	Indique la fonction qui gère un message défini par l’utilisateur.
ON_OLECMD	Indique quelle fonction gère une commande de menu à partir d’un DocObject ou de son conteneur.
ON_REGISTERED_MESSAGE	Indique quelle fonction gère un message défini par l’utilisateur inscrit.
ON_REGISTERED_THREAD_MESSAGE	Indique la fonction qui gère un message défini par l’utilisateur inscrit lorsque vous disposez d’une CWinThread classe.
ON_THREAD_MESSAGE	Indique la fonction qui gère un message défini par l’utilisateur lorsque vous disposez d’une CWinThread classe.
ON_UPDATE_COMMAND_UI	Indique quelle fonction gère un message de commande de mise à jour de l’interface utilisateur spécifié.

Macros de plage de mappages de messages

Nom	Description
ON_COMMAND_RANGE	Indique la fonction qui gère la plage d’ID de commandes spécifiée dans les deux premiers paramètres de la macro.
ON_UPDATE_COMMAND_UI_RANGE	Indique quel gestionnaire de mise à jour gère la plage d’ID de commande spécifié dans les deux premiers paramètres de la macro.
ON_CONTROL_RANGE	Indique quelle fonction gère les notifications de la plage d’ID de contrôle spécifiées dans les deuxième et troisième paramètres de la macro. Le premier paramètre est un message de notification de contrôle, tel que BN_CLICKED.

Pour plus d’informations sur les mappages de messages, les macros de déclaration et de démarcation des messages, ainsi que les macros de mappage de messages, consultez Les rubriques de gestion des Cartes messages et de gestion des messages. Pour plus d’informations sur les plages de mappage de messages, consultez Gestionnaires pour les plages de mappage de messages.

BEGIN_MESSAGE_MAP

Commence la définition de votre carte de messages.

Syntaxe

BEGIN_MESSAGE_MAP( theClass, baseClass )

Paramètres

theClass
Spécifie le nom de la classe dont le mappage de messages est celui-ci.

baseClass
Spécifie le nom de la classe de base de theClass.

Notes

Dans le fichier d’implémentation (.cpp) qui définit les fonctions membres de votre classe, démarrez le mappage de messages avec la BEGIN_MESSAGE_MAP macro, puis ajoutez des entrées de macro pour chacune de vos fonctions de gestionnaire de messages et terminez le mappage de messages avec la END_MESSAGE_MAP macro.

Pour plus d’informations sur les mappages de messages, consultez Message Cartes

Exemple

BEGIN_MESSAGE_MAP(CMainFrame, CMDIFrameWnd)
   ON_WM_CREATE()
END_MESSAGE_MAP()

Spécifications

En-têteafxwin.h:

BEGIN_TEMPLATE_MESSAGE_MAP

Commence la définition d’un mappage de messages sur un type de classe contenant un seul argument de modèle.

Syntaxe

BEGIN_TEMPLATE_MESSAGE_MAP( theClass, type_name, baseClass )

Paramètres

theClass
Spécifie le nom de la classe dont le mappage de messages est celui-ci.

type_name
Nom du paramètre de modèle spécifié pour la classe.

baseClass
Spécifie le nom de la classe de base de theClass.

Notes

Cette macro est similaire à la BEGIN_MESSAGE_MAP macro. Toutefois, cette macro est destinée aux classes contenant un seul argument de modèle.

Dans la section implémentation de méthode de votre classe, démarrez le mappage de messages avec la BEGIN_TEMPLATE_MESSAGE_MAP macro, puis ajoutez des entrées de macro pour chacune de vos méthodes de gestionnaire de messages comme vous le feriez pour une carte de messages standard. Comme avec la BEGIN_MESSAGE_MAP macro, complétez le mappage de messages de modèle avec la END_MESSAGE_MAP macro.

Pour plus d’informations sur l’implémentation de mappages de messages pour les classes de modèle, reportez-vous à How to : Create a Message Map for a Template Class.

Spécifications

En-têteafxwin.h:

DECLARE_MESSAGE_MAP

Déclare que la classe définit une carte de messages. Chaque CCmdTargetclasse dérivée de votre programme doit fournir un mappage de messages pour gérer les messages.

Syntaxe

DECLARE_MESSAGE_MAP( )

Notes

Utilisez la DECLARE_MESSAGE_MAP macro à la fin de votre déclaration de classe. Ensuite, dans le fichier .cpp qui définit les fonctions membres de la classe, utilisez la BEGIN_MESSAGE_MAP macro, les entrées de macro pour chacune de vos fonctions de gestionnaire de messages et la END_MESSAGE_MAP macro.

Remarque

Si vous déclarez un membre après DECLARE_MESSAGE_MAP, vous devez spécifier un nouveau type d’accès (public, privateou protected) pour ceux-ci.

Pour plus d’informations sur les mappages de messages et la macro, consultez Rubriques relatives à la DECLARE_MESSAGE_MAP gestion des messages et au mappage.

Exemple

class CMainFrame : public CMDIFrameWnd
{
   DECLARE_MESSAGE_MAP()

   // Remainder of class declaration omitted.

Spécifications

En-têteafxwin.h:

END_MESSAGE_MAP

Termine la définition de votre carte de messages.

Syntaxe

END_MESSAGE_MAP( )

Notes

Pour plus d’informations sur les mappages de messages et la macro, consultez Rubriques relatives à la END_MESSAGE_MAP gestion des messages et au mappage.

Spécifications

En-têteafxwin.h:

ON_COMMAND

Cette macro mappe un message de commande à une fonction membre.

Syntaxe

ON_COMMAND( commandId, memberFxn )

Paramètres

commandId
ID de la commande.

memberFxn
Nom de la fonction de gestionnaire de messages à laquelle la commande est mappée.

Notes

Elle indique quelle fonction gère un message de commande à partir d’un objet d’interface utilisateur de commande, tel qu’un élément de menu ou un bouton de barre d’outils.

Lorsqu’un objet cible de commande reçoit un message Windows WM_COMMAND avec l’ID spécifié, ON_COMMAND appelle la fonction memberFxn membre pour gérer le message.

Permet ON_COMMAND de mapper une seule commande à une fonction membre. Permet ON_COMMAND_RANGE de mapper une plage d’ID de commandes à une fonction membre. Une seule entrée de carte de messages peut correspondre à un ID de commande donné. Autrement dit, vous ne pouvez pas mapper une commande à plusieurs gestionnaires. Pour plus d’informations et d’exemples, consultez Rubriques relatives à la gestion des messages et au mappage.

Exemple

BEGIN_MESSAGE_MAP(CMFCListViewDoc, CDocument)
   ON_COMMAND(ID_MYCOMMAND, &CMFCListViewDoc::OnMycommand)
END_MESSAGE_MAP()

Spécifications

En-têteafxmsg_.h:

ON_COMMAND_EX

Fonction membre du gestionnaire de commandes étendue.

Syntaxe

ON_COMMAND_EX(commandId, memberFxn);

Paramètres

commandId
ID de la commande.

memberFxn
Nom de la fonction de gestionnaire de messages à laquelle la commande est mappée.

Notes

Une forme étendue de gestionnaires de messages de commande est disponible pour les utilisations avancées. La ON_COMMAND_EX macro est utilisée pour ces gestionnaires de messages et fournit un super-ensemble de fonctionnalités ON_COMMAND . Les fonctions membres du gestionnaire de commandes étendues prennent un paramètre unique, un UINT ID de commande contenant l’ID de commande et retournent un BOOL. La valeur de retour doit indiquer TRUE que la commande a été gérée ; sinon, le routage continuera vers d’autres objets cibles de commande.

Pour plus d’informations, consultez la note technique [TN006 : Message Cartes]tm006-message-maps.md).

Spécifications

Fichier d’en-tête : afxmsg_.h

ON_CONTROL

Indique quelle fonction gère un message de notification de contrôle personnalisé.

Syntaxe

ON_CONTROL( wNotifyCode, commandId, memberFxn )

Paramètres

wNotifyCode
Code de notification du contrôle.

commandId
ID de la commande.

memberFxn
Nom de la fonction de gestionnaire de messages à laquelle la commande est mappée.

Notes

Les messages de notification de contrôle sont ceux envoyés d’un contrôle à sa fenêtre parente.

Il doit y avoir exactement une ON_CONTROL instruction macro dans votre mappage de messages pour chaque message de notification de contrôle qui doit être mappé à une fonction de gestionnaire de messages.

Pour plus d’informations et d’exemples, consultez Rubriques relatives à la gestion des messages et au mappage.

Spécifications

En-têteafxmsg_.h:

ON_MESSAGE

Indique la fonction qui gère un message défini par l’utilisateur.

Syntaxe

ON_MESSAGE( message, memberFxn )

Paramètres

message
ID de message.

memberFxn
Nom de la fonction de gestionnaire de messages à laquelle le message est mappé.

Le type de la fonction doit être afx_msg LRESULT (CWnd::*)(WPARAM, LPARAM).

Notes

Les messages définis par l’utilisateur sont tous les messages qui ne sont pas des messages Windows WM_MESSAGE standard. Lorsque vous sélectionnez un ID de message, vous devez utiliser des valeurs dans la plage de WM_USER (0x0400) pour 0x7FFF ou WM_APP (0x8000) pour 0xBFFF. Pour plus d’informations sur les ID de message, consultez WM_APP.

Il doit y avoir exactement une ON_MESSAGE instruction macro dans votre mappage de messages pour chaque message défini par l’utilisateur qui doit être mappé à une fonction de gestionnaire de messages.

Remarque

Outre les messages définis par l’utilisateur, ON_MESSAGE gère les messages Windows moins courants. Pour plus d’informations, consultez message Cartes.

Pour plus d’informations et d’exemples, consultez rubriques de gestion et de mappage des messages et gestionnaires définis par l’utilisateur

Exemple

#define WM_MYMESSAGE (WM_USER + 100)

BEGIN_MESSAGE_MAP(CMyWnd2, CWnd)
   ON_MESSAGE(WM_MYMESSAGE, OnMyMessage)
END_MESSAGE_MAP()

// inside the class declaration
afx_msg LRESULT OnMyMessage(WPARAM wParam, LPARAM lParam);

LRESULT CMyWnd2::OnMyMessage(WPARAM wParam, LPARAM lParam)
{
   UNREFERENCED_PARAMETER(wParam);
   UNREFERENCED_PARAMETER(lParam);

   // Handle message here.

   return 0;
}

Spécifications

En-têteafxmsg_.h:

ON_OLECMD

Route les commandes via l’interface IOleCommandTargetde distribution de commandes .

Syntaxe

ON_OLECMD( pguid, olecmdid, commandId )

Paramètres

pguid
Identificateur du groupe de commandes auquel appartient la commande. Utiliser NULL pour le groupe standard.

olecmdid
Identificateur de la commande OLE.

commandId
ID de menu, ID de barre d’outils, ID de bouton ou autre ID de la ressource ou de l’objet qui émet la commande.

Notes

IOleCommandTarget permet à un conteneur de recevoir des commandes qui proviennent de l’interface utilisateur d’un DocObject et permet au conteneur d’envoyer les mêmes commandes (par exemple, New, Open, SaveAs et Print on the File menu ; and Copy, Paste, Undo, etc. dans le menu Modifier) à un DocObject.

IOleCommandTargetest plus simple que ole Automation.IDispatch IOleCommandTarget s’appuie entièrement sur un ensemble standard de commandes qui ont rarement des arguments et aucune information de type n’est impliquée (la sécurité du type est également réduite pour les arguments de commande). Si vous avez besoin de distribuer des commandes avec des arguments, utilisez COleServerDoc::OnExecOleCmd.

Les IOleCommandTarget commandes de menu standard ont été implémentées par MFC dans les macros suivantes :

ON_OLECMD_CLEARSELECTION( )

Répartit la commande Modifier l’effacement. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_CLEARSELECTION, ID_EDIT_CLEAR)

ON_OLECMD_COPY( )

Répartit la commande Modifier la copie. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_COPY, ID_EDIT_COPY)

ON_OLECMD_CUT( )

Répartit la commande Modifier la coupe. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_CUT, ID_EDIT_CUT)

ON_OLECMD_NEW( )

Répartit la commande File New. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_NEW, ID_FILE_NEW)

ON_OLECMD_OPEN( )

Répartit la commande Ouvrir le fichier. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_OPEN, ID_FILE_OPEN)

ON_OLECMD_PAGESETUP( )

Répartit la commande Configuration de la page de fichiers. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_PAGESETUP, ID_FILE_PAGE_SETUP)

ON_OLECMD_PASTE( )

Répartit la commande Modifier le collage. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_PASTE, ID_EDIT_PASTE)

ON_OLECMD_PASTESPECIAL( )

Répartit la commande Modifier le collage spécial. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_PASTESPECIAL, ID_EDIT_PASTE_SPECIAL)

ON_OLECMD_PRINT( )

Répartit la commande Imprimer des fichiers. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_PRINT, ID_FILE_PRINT)

ON_OLECMD_PRINTPREVIEW( )

Répartit la commande Aperçu avant impression de fichier. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_PRINTPREVIEW, ID_FILE_PRINT_PREVIEW)

ON_OLECMD_REDO( )

Répartit la commande Modifier le rétablissement. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_REDO, ID_EDIT_REDO)

ON_OLECMD_SAVE( )

Répartit la commande Enregistrer des fichiers. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_SAVE, ID_FILE_SAVE)

ON_OLECMD_SAVE_AS( )

Répartit la commande Enregistrer sous du fichier. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_SAVEAS, ID_FILE_SAVE_AS)

ON_OLECMD_SAVE_COPY_AS( )

Répartit la commande Enregistrer le fichier sous. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_SAVECOPYAS, ID_FILE_SAVE_COPY_AS)

ON_OLECMD_SELECTALL( )

Répartit la commande Modifier sélectionner tout. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_SELECTALL, ID_EDIT_SELECT_ALL)

ON_OLECMD_UNDO( )

Répartit la commande Modifier l’annulation. Implémenté comme suit :

ON_OLECMD(NULL, OLECMDID_UNDO, ID_EDIT_UNDO)

Spécifications

En-têteafxdocob.h:

ON_REGISTERED_MESSAGE

La fonction Windows RegisterWindowMessage est utilisée pour définir un nouveau message de fenêtre qui est garanti être unique dans tout le système.

Syntaxe

ON_REGISTERED_MESSAGE( nMessageVariable, memberFxn )

Paramètres

nMessageVariable
Variable d’ID de message de fenêtre inscrite.

memberFxn
Nom de la fonction de gestionnaire de messages à laquelle le message est mappé.

Notes

Cette macro indique la fonction qui gère le message inscrit.

Pour plus d’informations et d’exemples, consultez Rubriques relatives à la gestion des messages et au mappage.

Exemple

static UINT NEAR WM_FIND = RegisterWindowMessage(_T("COMMDLG_FIND"));

BEGIN_MESSAGE_MAP(CMyWnd3, CWnd)
   ON_REGISTERED_MESSAGE(WM_FIND, OnFind)
END_MESSAGE_MAP()

Spécifications

En-têteafxmsg_.h:

ON_REGISTERED_THREAD_MESSAGE

Indique la fonction qui gère le message inscrit par la fonction Windows RegisterWindowMessage .

Syntaxe

ON_REGISTERED_THREAD_MESSAGE(nMessageVariable, memberFxn )

Paramètres

nMessageVariable
Variable d’ID de message de fenêtre inscrite.

memberFxn
Nom de la CWinThreadfonction -message-handler à laquelle le message est mappé.

Notes

RegisterWindowMessage est utilisé pour définir un nouveau message de fenêtre qui est garanti être unique dans tout le système. ON_REGISTERED_THREAD_MESSAGE doit être utilisé au lieu de l’utilisation d’une ON_REGISTERED_MESSAGECWinThread classe.

Spécifications

En-têteafxmsg_.h:

ON_THREAD_MESSAGE

Indique la fonction qui gère un message défini par l’utilisateur.

Syntaxe

ON_THREAD_MESSAGE( message, memberFxn )

Paramètres

message
ID de message.

memberFxn
Nom de la CWinThreadfonction -message-handler à laquelle le message est mappé.

Notes

ON_THREAD_MESSAGE doit être utilisé au lieu de l’utilisation d’une ON_MESSAGECWinThread classe. Les messages définis par l’utilisateur sont tous les messages qui ne sont pas des messages Windows WM_MESSAGE standard. Il doit y avoir exactement une ON_THREAD_MESSAGE instruction macro dans votre mappage de messages pour chaque message défini par l’utilisateur qui doit être mappé à une fonction de gestionnaire de messages.

Spécifications

En-têteafxole.h:

ON_UPDATE_COMMAND_UI

Cette macro indique la fonction qui gère un message de commande de mise à jour de l’interface utilisateur.

Syntaxe

ON_UPDATE_COMMAND_UI( messageId, memberFxn )

Paramètres

messageId
ID de message.

memberFxn
Nom de la fonction de gestionnaire de messages à laquelle le message est mappé.

Notes

Il doit y avoir exactement une ON_UPDATE_COMMAND_UI instruction macro dans votre mappage de messages pour chaque commande de mise à jour de l’interface utilisateur qui doit être mappée à une fonction de gestionnaire de messages.

Pour plus d’informations et d’exemples, consultez Rubriques relatives à la gestion des messages et au mappage.

Spécifications

En-têteafxole.h:

ON_COMMAND_RANGE

Utilisez cette macro pour mapper une plage contiguë d’ID de commandes à une fonction de gestionnaire de messages unique.

Syntaxe

ON_COMMAND_RANGE( id1, id2, memberFxn )

Paramètres

id1
ID de commande au début d’une plage contiguë d’ID de commandes.

id2
ID de commande à la fin d’une plage contiguë d’ID de commandes.

memberFxn
Nom de la fonction de gestionnaire de messages à laquelle les commandes sont mappées.

Notes

La plage d’ID commence par id1 et se termine par id2.

Permet ON_COMMAND_RANGE de mapper une plage d’ID de commandes à une fonction membre. Permet ON_COMMAND de mapper une seule commande à une fonction membre. Une seule entrée de carte de messages peut correspondre à un ID de commande donné. Autrement dit, vous ne pouvez pas mapper une commande à plusieurs gestionnaires. Pour plus d’informations sur le mappage des plages de messages, consultez Gestionnaires pour les plages de mappage de messages.

Il n’existe aucune prise en charge automatique des plages de mappage de messages. Vous devez donc placer la macro vous-même.

Exemple

// The code fragment below shows how to use ON_COMMAND_RANGE macro
// to map a contiguous range of command IDs to a single message
// handler function (i.e. OnRangeCmds() in the sample below). In
// addition, it also shows how to use CheckMenuRadioItem() to check a
// selected menu item and makes it a radio item.

BEGIN_MESSAGE_MAP(CChildFrame, CMDIChildWnd)
   ON_COMMAND_RANGE(ID_COMMAND_RANGECMD1, ID_COMMAND_RANGECMD3, &CChildFrame::OnRangeCmds)
END_MESSAGE_MAP()

void CChildFrame::OnRangeCmds(UINT nID)
{
   CMenu* mmenu = AfxGetMainWnd()->GetMenu();
   CMenu* submenu = mmenu->GetSubMenu(5);
   submenu->CheckMenuRadioItem(ID_COMMAND_RANGECMD1, ID_COMMAND_RANGECMD3,
      nID, MF_BYCOMMAND);
}

Spécifications

En-têteafxmsg_.h:

ON_UPDATE_COMMAND_UI_RANGE

Cartes une plage contiguë d’ID de commandes à une fonction de gestionnaire de messages de mise à jour unique.

Syntaxe

ON_UPDATE_COMMAND_UI_RANGE( id1, id2, memberFxn )

Paramètres

id1
ID de commande au début d’une plage contiguë d’ID de commandes.

id2
ID de commande à la fin d’une plage contiguë d’ID de commandes.

memberFxn
Nom de la fonction de gestionnaire de messages de mise à jour à laquelle les commandes sont mappées.

Notes

Les gestionnaires de messages de mise à jour mettent à jour l’état des éléments de menu et des boutons de barre d’outils associés à la commande. La plage d’ID commence par id1 et se termine par id2.

Il n’existe aucune prise en charge automatique des plages de mappage de messages. Vous devez donc placer la macro vous-même.

Spécifications

En-têteafxmsg_.h:

ON_CONTROL_RANGE

Utilisez cette macro pour mapper une plage contiguë d’ID de contrôle à une fonction de gestionnaire de messages unique pour un message de notification Windows spécifié, tel que BN_CLICKED.

Syntaxe

ON_CONTROL_RANGE( wNotifyCode, id1, id2, memberFxn )

Paramètres

wNotifyCode
Code de notification auquel votre gestionnaire répond.

id1
ID de commande au début d’une plage contiguë d’ID de contrôle.

id2
ID de commande à la fin d’une plage contiguë d’ID de contrôle.

memberFxn
Nom de la fonction de gestionnaire de messages à laquelle les contrôles sont mappés.

Notes

La plage d’ID commence par id1 et se termine par id2. Le gestionnaire est appelé pour la notification spécifiée provenant de l’un des contrôles mappés.

Il n’existe aucune prise en charge automatique des plages de mappage de messages. Vous devez donc placer la macro vous-même.

Pour plus d’informations sur l’implémentation de fonctions de gestionnaire pour une plage d’ID de contrôle, reportez-vous aux gestionnaires pour les plages de mappage de messages.

Spécifications

En-têteafxmsg_.h:

Voir aussi

ON_COMMAND
TN006 : tables des messages
COleCmdUI Classe
COleServerDoc::OnExecOleCmd
RegisterWindowMessage
Gestionnaires définis par l’utilisateur
CCmdUI Classe