Macros de mapa de mensajes (MFC)

Artículo
06/16/2023

Para admitir mapas de mensajes, MFC proporciona las macros siguientes:

Macros de declaración y demarcación de mapas de mensajes

Nombre	Descripción
`DECLARE_MESSAGE_MAP`	Declara que se usará un mapa de mensajes en una clase para asignar mensajes a funciones (se debe usar en la declaración de clase).
`BEGIN_MESSAGE_MAP`	Comienza la definición de un mapa de mensajes (debe usarse en la implementación de la clase).
`BEGIN_TEMPLATE_MESSAGE_MAP`	Comienza la definición de un mapa de mensajes en un tipo de clase que contiene un único argumento de plantilla.
`END_MESSAGE_MAP`	Finaliza la definición de un mapa de mensajes (debe usarse en la implementación de la clase).

Macros de asignación de mensajes

Nombre	Descripción
`ON_COMMAND`	Indica qué función controlará un mensaje de comando especificado.
`ON_COMMAND_EX`	Indica qué función controlará un mensaje de comando especificado.
`ON_CONTROL`	Indica qué función controlará un mensaje de notificación de control especificado.
`ON_MESSAGE`	Indica qué función controlará un mensaje definido por el usuario.
`ON_OLECMD`	Indica qué función controlará un comando de menú desde un elemento DocObject o su contenedor.
`ON_REGISTERED_MESSAGE`	Indica qué función controlará un mensaje definido por el usuario registrado.
`ON_REGISTERED_THREAD_MESSAGE`	Indica qué función controlará un mensaje definido por el usuario registrado cuando se tiene una clase `CWinThread`.
`ON_THREAD_MESSAGE`	Indica qué función controlará un mensaje definido por el usuario cuando se tiene una clase `CWinThread`.
`ON_UPDATE_COMMAND_UI`	Indica qué función controlará un mensaje de comando de actualización de interfaz de usuario especificado.

Macros de intervalo de mapa de mensajes

Nombre	Descripción
`ON_COMMAND_RANGE`	Indica qué función controlará el intervalo de id. de comandos especificados en los dos primeros parámetros de la macro.
`ON_UPDATE_COMMAND_UI_RANGE`	Indica qué controlador de actualización controlará el intervalo de id. de comandos especificados en los dos primeros parámetros de la macro.
`ON_CONTROL_RANGE`	Indica qué función controlará las notificaciones del intervalo de id. de controles especificados en los parámetros segundo y tercero de la macro. El primer parámetro es un mensaje de notificación de control, como `BN_CLICKED`.

Para más información sobre los mapas de mensajes, las macros de declaración y demarcación de mapa de mensajes, y las macros de asignación de mensajes, vea Mapas de mensajes y Temas de control y asignación de mensajes. Para más información sobre los intervalos de mapa de mensajes, consulte Controladores para intervalos de mapas de mensajes.

`BEGIN_MESSAGE_MAP`

Comienza la definición del mapa de mensajes.

Sintaxis

BEGIN_MESSAGE_MAP( theClass, baseClass )

Parámetros

theClass
Especifica el nombre de la clase cuyo mapa de mensajes es este.

baseClass
Especifica el nombre de clase base de theClass.

Comentarios

En el archivo de implementación (.cpp) que define las funciones miembro de la clase, inicie el mapa de mensajes con la macro BEGIN_MESSAGE_MAP, agregue entradas de macro para cada una de las funciones del controlador de mensajes y complete el mapa de mensajes con la macro END_MESSAGE_MAP.

Para más información sobre los mapas de mensajes, vea Mapas de mensajes.

Ejemplo

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

Requisitos

Encabezadoafxwin.h:

`BEGIN_TEMPLATE_MESSAGE_MAP`

Comienza la definición de un mapa de mensajes en un tipo de clase que contiene un único argumento de plantilla.

Sintaxis

BEGIN_TEMPLATE_MESSAGE_MAP( theClass, type_name, baseClass )

Parámetros

theClass
Especifica el nombre de la clase cuyo mapa de mensajes es este.

type_name
Nombre del parámetro de plantilla especificado para la clase.

baseClass
Especifica el nombre de clase base de theClass.

Comentarios

Esta macro es similar a la macro BEGIN_MESSAGE_MAP; sin embargo, esta macro está pensada para clases que contienen un único argumento de plantilla.

En la sección de implementación de métodos de la clase, inicie el mapa de mensajes con la macro BEGIN_TEMPLATE_MESSAGE_MAP; a continuación, agregue entradas de macro para cada uno de los métodos del controlador de mensajes como lo haría para un mapa de mensajes estándar. Al igual que con la macro BEGIN_MESSAGE_MAP, complete el mapa de mensajes de plantilla con la macro END_MESSAGE_MAP.

Para más información sobre cómo implementar mapas de mensajes para clases de plantilla, consulte Procedimiento: creación de un mapa de mensajes para una clase de plantilla.

Requisitos

Encabezadoafxwin.h:

`DECLARE_MESSAGE_MAP`

Declara que la clase define un mapa de mensajes. Cada clase derivada de CCmdTarget del programa debe proporcionar un mapa de mensajes para controlar los mensajes.

Sintaxis

DECLARE_MESSAGE_MAP( )

Comentarios

Use la macro DECLARE_MESSAGE_MAP al final de la declaración de clase. A continuación, en el archivo .cpp que define las funciones miembro de la clase, use la macro BEGIN_MESSAGE_MAP, las entradas de macro para cada una de las funciones del controlador de mensajes y la macro END_MESSAGE_MAP.

Nota:

Si declara miembros después de DECLARE_MESSAGE_MAP, debe especificar un nuevo tipo de acceso (public, private o protected) para ellos.

Para más información sobre los mapas de mensajes y la macro DECLARE_MESSAGE_MAP, vea Temas de control y asignación de mensajes.

Ejemplo

class CMainFrame : public CMDIFrameWnd
{
   DECLARE_MESSAGE_MAP()

   // Remainder of class declaration omitted.

Requisitos

Encabezadoafxwin.h:

`END_MESSAGE_MAP`

Finaliza la definición del mapa de mensajes.

Sintaxis

END_MESSAGE_MAP( )

Comentarios

Para más información sobre los mapas de mensajes y la macro END_MESSAGE_MAP, vea Temas de control y asignación de mensajes.

Requisitos

Encabezadoafxwin.h:

`ON_COMMAND`

Esta macro asigna un mensaje de comando a una función miembro.

Sintaxis

ON_COMMAND( commandId, memberFxn )

Parámetros

commandId
Identificador del comando.

memberFxn
Nombre de la función de controlador de mensajes a la que se asigna el comando.

Comentarios

Indica qué función controlará un mensaje de comando de un objeto de interfaz de usuario de comandos, como un elemento de menú o como un botón de barra de herramientas.

Cuando un objeto de destino de comandos recibe un mensaje WM_COMMAND de Windows con el id. especificado, ON_COMMAND llamará a la función miembro memberFxn para controlar el mensaje.

Use ON_COMMAND para asignar un único comando a una función miembro. Use ON_COMMAND_RANGE para asignar un intervalo de id. de comandos a una función miembro. Solo una entrada de mapa de mensajes puede coincidir con un id. de comando determinado. Es decir, no se puede asignar un comando a más de un controlador. Para más información y ejemplos, vea Temas de control y asignación de mensajes.

Ejemplo

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

Requisitos

Encabezadoafxmsg_.h:

`ON_COMMAND_EX`

Función miembro del controlador de comandos extendido.

Sintaxis

ON_COMMAND_EX(commandId, memberFxn);

Parámetros

commandId
Identificador del comando.

memberFxn
Nombre de la función de controlador de mensajes a la que se asigna el comando.

Comentarios

Hay disponible una forma extendida de controladores de mensajes de comando para usos avanzados. La macro ON_COMMAND_EX se usa para estos controladores de mensajes y proporciona un superconjunto de la funcionalidad ON_COMMAND. Las funciones miembro del controlador de comandos extendido toman un único parámetro, un elemento UINT que contiene el id. de comando, y devuelven un BOOL. El valor devuelto debe ser TRUE para indicar que se ha controlado el comando; de lo contrario, el enrutamiento continuará a otros objetos de destino de comando.

Para más información, vea Nota técnica [TN006: Mapas de mensajes]tm006-message-maps.md).

Requisitos

Archivo de encabezado: afxmsg_.h

`ON_CONTROL`

Indica qué función controlará un mensaje de notificación de control personalizado.

Sintaxis

ON_CONTROL( wNotifyCode, commandId, memberFxn )

Parámetros

wNotifyCode
Código de notificación del control.

commandId
Identificador del comando.

memberFxn
Nombre de la función de controlador de mensajes a la que se asigna el comando.

Comentarios

Los mensajes de notificación de control son los enviados desde un control a su ventana primaria.

Debe haber exactamente una instrucción de macro ON_CONTROL en el mapa de mensajes para cada mensaje de notificación de control que se debe asignar a una función de controlador de mensajes.

Para más información y ejemplos, vea Temas de control y asignación de mensajes.

Requisitos

Encabezadoafxmsg_.h:

`ON_MESSAGE`

Indica qué función controlará un mensaje definido por el usuario.

Sintaxis

ON_MESSAGE( message, memberFxn )

Parámetros

message
El id. del mensaje.

memberFxn
Nombre de la función de controlador de mensajes a la que se asigna el mensaje.

El tipo de la función debe ser afx_msg LRESULT (CWnd::*)(WPARAM, LPARAM).

Comentarios

Los mensajes definidos por el usuario son mensajes que no son estándar de Windows WM_MESSAGE. Al seleccionar un id. de mensaje, debe usar valores dentro del intervalo de WM_USER (0x0400) para 0x7FFF o WM_APP (0x8000) para 0xBFFF. Para más información sobre los id. de mensajes, consulte WM_APP.

Debe haber exactamente una instrucción de macro ON_MESSAGE en el mapa de mensajes para cada mensaje definido por el usuario que se debe asignar a una función de controlador de mensajes.

Nota:

Además de los mensajes definidos por el usuario, ON_MESSAGE controla los mensajes de Windows menos comunes. Para más información, consulte Mapas de mensajes.

Para más información y ejemplos, vea Temas de control y asignación de mensajes y Controladores definidos por el usuario.

Ejemplo

#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;
}

Requisitos

Encabezadoafxmsg_.h:

`ON_OLECMD`

Enruta los comandos a través de la interfaz IOleCommandTarget de envío de comandos.

Sintaxis

ON_OLECMD( pguid, olecmdid, commandId )

Parámetros

pguid
Identificador del grupo de comandos al que el comando pertenece. Use NULL para el grupo estándar.

olecmdid
Identificador del comando OLE.

commandId
Id. de menú, id. de barra de herramientas, id. de botón u otro id. del recurso u objeto que emite el comando.

Comentarios

IOleCommandTarget permite a un contenedor recibir comandos que se originan en la interfaz de usuario de DocObject y permite que el contenedor envíe los mismos comandos (como Nuevo, Abrir, Guardar como e Imprimir del menú Archivo; y Copiar, Pegar, Deshacer, etc. del menú Editar) a DocObject.

IOleCommandTarget es más sencillo que IDispatch de la automatización OLE. IOleCommandTarget se basa completamente en un conjunto estándar de comandos que rara vez tienen argumentos y no hay ninguna información de tipo implicada (la seguridad de tipos también se reduce para los argumentos de comando). Si necesita enviar comandos con argumentos, use COleServerDoc::OnExecOleCmd.

MFC ha implementado los comandos de menú estándar de IOleCommandTarget en las macros siguientes:

ON_OLECMD_CLEARSELECTION( )

Envía el comando Editar/Borrar. Implementado como:

ON_OLECMD(NULL, OLECMDID_CLEARSELECTION, ID_EDIT_CLEAR)

ON_OLECMD_COPY( )

Envía el comando Editar/Copiar. Implementado como:

ON_OLECMD(NULL, OLECMDID_COPY, ID_EDIT_COPY)

ON_OLECMD_CUT( )

Envía el comando Editar/Cortar. Implementado como:

ON_OLECMD(NULL, OLECMDID_CUT, ID_EDIT_CUT)

ON_OLECMD_NEW( )

Envía el comando Archivo/Nuevo. Implementado como:

ON_OLECMD(NULL, OLECMDID_NEW, ID_FILE_NEW)

ON_OLECMD_OPEN( )

Envía el comando Archivo/Abrir. Implementado como:

ON_OLECMD(NULL, OLECMDID_OPEN, ID_FILE_OPEN)

ON_OLECMD_PAGESETUP( )

Envía el comando Archivo/Configurar página. Implementado como:

ON_OLECMD(NULL, OLECMDID_PAGESETUP, ID_FILE_PAGE_SETUP)

ON_OLECMD_PASTE( )

Envía el comando Editar/Pegar. Implementado como:

ON_OLECMD(NULL, OLECMDID_PASTE, ID_EDIT_PASTE)

ON_OLECMD_PASTESPECIAL( )

Envía el comando Editar/Pegado especial. Implementado como:

ON_OLECMD(NULL, OLECMDID_PASTESPECIAL, ID_EDIT_PASTE_SPECIAL)

ON_OLECMD_PRINT( )

Envía el comando Archivo/Imprimir. Implementado como:

ON_OLECMD(NULL, OLECMDID_PRINT, ID_FILE_PRINT)

ON_OLECMD_PRINTPREVIEW( )

Envía el comando Archivo/Imprimir/Vista previa. Implementado como:

ON_OLECMD(NULL, OLECMDID_PRINTPREVIEW, ID_FILE_PRINT_PREVIEW)

ON_OLECMD_REDO( )

Envía el comando Editar/Rehacer. Implementado como:

ON_OLECMD(NULL, OLECMDID_REDO, ID_EDIT_REDO)

ON_OLECMD_SAVE( )

Envía el comando Archivo/Guardar. Implementado como:

ON_OLECMD(NULL, OLECMDID_SAVE, ID_FILE_SAVE)

ON_OLECMD_SAVE_AS( )

Envía el comando Archivo/Guardar como. Implementado como:

ON_OLECMD(NULL, OLECMDID_SAVEAS, ID_FILE_SAVE_AS)

ON_OLECMD_SAVE_COPY_AS( )

Envía el comando Archivo/Guardar copia como. Implementado como:

ON_OLECMD(NULL, OLECMDID_SAVECOPYAS, ID_FILE_SAVE_COPY_AS)

ON_OLECMD_SELECTALL( )

Envía el comando Editar/Seleccionar todo. Implementado como:

ON_OLECMD(NULL, OLECMDID_SELECTALL, ID_EDIT_SELECT_ALL)

ON_OLECMD_UNDO( )

Envía el comando Editar/Deshacer. Implementado como:

ON_OLECMD(NULL, OLECMDID_UNDO, ID_EDIT_UNDO)

Requisitos

Encabezadoafxdocob.h:

`ON_REGISTERED_MESSAGE`

La función RegisterWindowMessage de Windows se usa para definir un nuevo mensaje de ventana que se garantiza como único en todo el sistema.

Sintaxis

ON_REGISTERED_MESSAGE( nMessageVariable, memberFxn )

Parámetros

nMessageVariable
Variable de id. de mensaje de ventana registrado.

memberFxn
Nombre de la función de controlador de mensajes a la que se asigna el mensaje.

Comentarios

Esta macro indica qué función controlará el mensaje registrado.

Para más información y ejemplos, vea Temas de control y asignación de mensajes.

Ejemplo

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

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

Requisitos

Encabezadoafxmsg_.h:

`ON_REGISTERED_THREAD_MESSAGE`

Indica qué función controlará el mensaje registrado por la función RegisterWindowMessage de Windows.

Sintaxis

ON_REGISTERED_THREAD_MESSAGE(nMessageVariable, memberFxn )

Parámetros

nMessageVariable
Variable de id. de mensaje de ventana registrado.

memberFxn
Nombre de la función de controlador de mensajes de CWinThread a la que se asigna el mensaje.

Comentarios

RegisterWindowMessage se usa para definir un nuevo mensaje de ventana que se garantiza como único en todo el sistema. ON_REGISTERED_THREAD_MESSAGE debe usarse en lugar de ON_REGISTERED_MESSAGE cuando se tiene una clase CWinThread.

Requisitos

Encabezadoafxmsg_.h:

`ON_THREAD_MESSAGE`

Indica qué función controlará un mensaje definido por el usuario.

Sintaxis

ON_THREAD_MESSAGE( message, memberFxn )

Parámetros

message
El id. del mensaje.

memberFxn
Nombre de la función de controlador de mensajes de CWinThread a la que se asigna el mensaje.

Comentarios

ON_THREAD_MESSAGE debe usarse en lugar de ON_MESSAGE cuando se tiene una clase CWinThread. Los mensajes definidos por el usuario son mensajes que no son estándar de Windows WM_MESSAGE. Debe haber exactamente una instrucción de macro ON_THREAD_MESSAGE en el mapa de mensajes para cada mensaje definido por el usuario que se debe asignar a una función de controlador de mensajes.

Requisitos

Encabezadoafxole.h:

`ON_UPDATE_COMMAND_UI`

Esta macro indica qué función controlará un mensaje de comando de actualización de interfaz de usuario.

Sintaxis

ON_UPDATE_COMMAND_UI( messageId, memberFxn )

Parámetros

messageId
El id. del mensaje.

memberFxn
Nombre de la función de controlador de mensajes a la que se asigna el mensaje.

Comentarios

Debe haber exactamente una instrucción de macro ON_UPDATE_COMMAND_UI en el mapa de mensajes para cada comando de actualización de interfaz de usuario que se debe asignar a una función de controlador de mensajes.

Para más información y ejemplos, vea Temas de control y asignación de mensajes.

Requisitos

Encabezadoafxole.h:

`ON_COMMAND_RANGE`

Use esta macro para asignar un intervalo contiguo de id. de comandos a una sola función de controlador de mensajes.

Sintaxis

ON_COMMAND_RANGE( id1, id2, memberFxn )

Parámetros

id1
Id. de comando al principio de un intervalo contiguo de id. de comandos.

id2
Id. de comando al final de un intervalo contiguo de id. de comandos.

memberFxn
Nombre de la función de controlador de mensajes a la que se asignan los comandos.

Comentarios

El intervalo de id. comienza por id1 y termina con id2.

Use ON_COMMAND_RANGE para asignar un intervalo de id. de comandos a una función miembro. Use ON_COMMAND para asignar un único comando a una función miembro. Solo una entrada de mapa de mensajes puede coincidir con un id. de comando determinado. Es decir, no se puede asignar un comando a más de un controlador. Para más información sobre los intervalos de asignación de mensajes, consulte Controladores para intervalos de mapas de mensajes.

No hay compatibilidad automática con los intervalos de mapa de mensajes, por lo que debe colocar la macro usted mismo.

Ejemplo

// 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);
}

Requisitos

Encabezadoafxmsg_.h:

`ON_UPDATE_COMMAND_UI_RANGE`

Asigna un intervalo contiguo de id. de comandos a una sola función de controlador de mensajes de actualización.

Sintaxis

ON_UPDATE_COMMAND_UI_RANGE( id1, id2, memberFxn )

Parámetros

id1
Id. de comando al principio de un intervalo contiguo de id. de comandos.

id2
Id. de comando al final de un intervalo contiguo de id. de comandos.

memberFxn
Nombre de la función de controlador de mensajes de actualización a la que se asignan los comandos.

Comentarios

Los controladores de mensajes de actualización actualizan el estado de los elementos de menú y los botones de la barra de herramientas asociados al comando. El intervalo de id. comienza por id1 y termina con id2.

No hay compatibilidad automática con los intervalos de mapa de mensajes, por lo que debe colocar la macro usted mismo.

Requisitos

Encabezadoafxmsg_.h:

`ON_CONTROL_RANGE`

Use esta macro para asignar un intervalo contiguo de id. de controles a una única función de controlador de mensajes para un mensaje de notificación de Windows especificado, como BN_CLICKED.

Sintaxis

ON_CONTROL_RANGE( wNotifyCode, id1, id2, memberFxn )

Parámetros

wNotifyCode
Código de notificación al que responde el controlador.

id1
Id. de comando al principio de un intervalo contiguo de id. de controles.

id2
Id. de comando al final de un intervalo contiguo de id. de controles.

memberFxn
Nombre de la función de controlador de mensajes a la que se asignan los controles.

Comentarios

El intervalo de id. comienza por id1 y termina con id2. Se llama al controlador para la notificación especificada procedente de cualquiera de los controles asignados.

No hay compatibilidad automática con los intervalos de mapa de mensajes, por lo que debe colocar la macro usted mismo.

Para más información sobre cómo implementar funciones de controlador para un intervalo de id. de controles, consulte Controladores para intervalos de mapa de mensajes.

Requisitos

Encabezadoafxmsg_.h:

Consulte también

ON_COMMAND
TN006: Mapas de mensajes
COleCmdUI (clase)
COleServerDoc::OnExecOleCmd
RegisterWindowMessage
Controladores definidos por el usuario
CCmdUI (clase)