Compartilhar via

Macros de mapa de mensagem (MFC)

  • Artigo

Para dar suporte a mapas de mensagens, o MFC fornece as seguintes macros:

Macros de declaração e demarcação de mapa de mensagens

Nome Descrição
DECLARE_MESSAGE_MAP Declara que um mapa de mensagem será usado em uma classe para mapear mensagens para funções (deve ser usado na declaração de classe).
BEGIN_MESSAGE_MAP Inicia a definição de um mapa de mensagem (deve ser usado na implementação da classe).
BEGIN_TEMPLATE_MESSAGE_MAP Inicia a definição de um mapa de mensagem em um tipo de classe que contém um só argumento de modelo.
END_MESSAGE_MAP Termina a definição de um mapa de mensagem (deve ser usado na implementação de classe).

Macros de mapeamento de mensagem

Nome Descrição
ON_COMMAND Indica qual função manipulará uma mensagem de comando especificada.
ON_COMMAND_EX Indica qual função manipulará uma mensagem de comando especificada.
ON_CONTROL Indica qual função lidará com uma mensagem de notificação de controle especificada.
ON_MESSAGE Indica qual função lidará com uma mensagem definida pelo usuário.
ON_OLECMD Indica qual função manipulará um comando de menu de um DocObject ou seu contêiner.
ON_REGISTERED_MESSAGE Indica qual função lidará com uma mensagem definida pelo usuário registrado.
ON_REGISTERED_THREAD_MESSAGE Indica qual função lidará com uma mensagem definida pelo usuário registrado quando você tem uma classe CWinThread.
ON_THREAD_MESSAGE Indica qual função lidará com uma mensagem definida pelo usuário quando você tem uma classe CWinThread.
ON_UPDATE_COMMAND_UI Indica qual função lidará com uma mensagem de comando de atualização da interface do usuário especificada.

Macros de intervalo de mapa de mensagens

Nome Descrição
ON_COMMAND_RANGE Indica qual função manipulará o intervalo de IDs de comando especificado nos dois primeiros parâmetros para a macro.
ON_UPDATE_COMMAND_UI_RANGE Indica qual manipulador de atualização manipulará o intervalo de IDs de comando especificado nos dois primeiros parâmetros para a macro.
ON_CONTROL_RANGE Indica qual função lidará com notificações do intervalo de IDs de controle especificado no segundo e no terceiro parâmetros para a macro. O primeiro parâmetro é uma mensagem de notificação de controle, como BN_CLICKED.

Para mais informações sobre mapas de mensagens, macros de declaração e demarcação do mapa de mensagens e macros de mapeamento de mensagens, confira Mapas de Mensagens e Tópicos de Tratamento e Mapeamento de Mensagens. Para mais informações sobre intervalos de mapa de mensagens, confira Manipuladores para intervalos de mapa de mensagens.

BEGIN_MESSAGE_MAP

Inicia a definição do mapa de mensagens.

Sintaxe

BEGIN_MESSAGE_MAP( theClass, baseClass )

Parâmetros

theClass
Especifica o nome da classe cujo mapa de mensagem é este.

baseClass
Especifica o nome da classe base de theClass.

Comentários

No arquivo de implementação (.cpp) que define as funções de membro para sua classe, inicie o mapa de mensagens com a macro BEGIN_MESSAGE_MAP, adicione entradas de macro para cada uma das funções do manipulador de mensagens e conclua o mapa de mensagens com a macro END_MESSAGE_MAP.

Para mais informações sobre mapas de mensagem, confira Mapas de mensagem

Exemplo

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

Requisitos

Cabeçalhoafxwin.h:

BEGIN_TEMPLATE_MESSAGE_MAP

Inicia a definição de um mapa de mensagem em um tipo de classe que contém um só argumento de modelo.

Sintaxe

BEGIN_TEMPLATE_MESSAGE_MAP( theClass, type_name, baseClass )

Parâmetros

theClass
Especifica o nome da classe cujo mapa de mensagem é este.

type_name
O nome do parâmetro de modelo especificado para a classe.

baseClass
Especifica o nome da classe base de theClass.

Comentários

Essa macro é semelhante à macro BEGIN_MESSAGE_MAP; no entanto, essa macro se destina a classes que contêm um só argumento de modelo.

Na seção de implementação do método de sua classe, inicie o mapa de mensagens com a macro BEGIN_TEMPLATE_MESSAGE_MAP; então adicione entradas de macro para cada um dos seus métodos de manipulador de mensagens como faria para um mapa de mensagem padrão. Assim como acontece com a macro BEGIN_MESSAGE_MAP, conclua o mapa da mensagem de modelo com a macro END_MESSAGE_MAP.

Para mais informações sobre como implementar mapas de mensagens para classes de modelo, confira Como criar um mapa de mensagens para uma classe de modelo.

Requisitos

Cabeçalhoafxwin.h:

DECLARE_MESSAGE_MAP

Declara que a classe define um mapa de mensagens. Cada classe derivada de CCmdTarget em seu programa deve fornecer um mapa de mensagens para lidar com mensagens.

Sintaxe

DECLARE_MESSAGE_MAP( )

Comentários

Use a macro DECLARE_MESSAGE_MAP no final da declaração de classe. Em seguida, no arquivo .cpp que define as funções de membro para a classe, use a macro BEGIN_MESSAGE_MAP, as entradas de macro para cada uma das funções do manipulador de mensagens e a macro END_MESSAGE_MAP.

Observação

Se você declarar qualquer membro depois de DECLARE_MESSAGE_MAP, deverá especificar um novo tipo de acesso (public, private ou protected) para ele.

Para mais informações sobre mapas de mensagens e a macro DECLARE_MESSAGE_MAP, confira Tópicos de tratamento e mapeamento de mensagens.

Exemplo

class CMainFrame : public CMDIFrameWnd
{
   DECLARE_MESSAGE_MAP()

   // Remainder of class declaration omitted.

Requisitos

Cabeçalhoafxwin.h:

END_MESSAGE_MAP

Termina a definição do mapa da mensagem.

Sintaxe

END_MESSAGE_MAP( )

Comentários

Para mais informações sobre mapas de mensagens e a macro END_MESSAGE_MAP, confira Tópicos de tratamento e mapeamento de mensagens.

Requisitos

Cabeçalhoafxwin.h:

ON_COMMAND

Essa macro mapeia uma mensagem de comando para uma função de membro.

Sintaxe

ON_COMMAND( commandId, memberFxn )

Parâmetros

commandId
A ID do comando.

memberFxn
O nome da função de manipulador de mensagens para a qual o comando é mapeado.

Comentários

Ela indica qual função manipulará uma mensagem de comando de um objeto de interface do usuário de comando, como um item de menu ou botão de barra de ferramentas.

Quando um objeto de destino de comando receber uma mensagem WM_COMMAND do Windows com a ID especificada, ON_COMMAND chamará a função de membro memberFxn para manipular a mensagem.

Use ON_COMMAND para mapear um só comando para uma função de membro. Use ON_COMMAND_RANGE para mapear um intervalo de IDs de comando para uma função de membro. Somente uma entrada de mapa de mensagem pode corresponder a uma determinada ID de comando. Ou seja, você não pode mapear um comando para mais de um manipulador. Para mais informações e exemplos, confira Tópicos de tratamento e mapeamento de mensagens.

Exemplo

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

Requisitos

Cabeçalhoafxmsg_.h:

ON_COMMAND_EX

Função de membro do manipulador de comando estendido.

Sintaxe

ON_COMMAND_EX(commandId, memberFxn);

Parâmetros

commandId
A ID do comando.

memberFxn
O nome da função de manipulador de mensagens para a qual o comando é mapeado.

Comentários

Uma forma estendida de manipuladores de mensagens de comando está disponível para usos avançados. A macro ON_COMMAND_EX é usada para esses manipuladores de mensagens e fornece um superconjunto da funcionalidade ON_COMMAND. As funções de membro do manipulador de comando estendido pegam um só parâmetro, um UINT que contém a ID de comando e retornam um BOOL. O valor retornado deve ser TRUE para indicar que o comando foi tratado; caso contrário, o roteamento continuará para outros objetos de destino de comando.

Para mais informações, confira Nota Técnica [TN006: Mapas de Mensagem]tm006-message-maps.md).

Requisitos

Arquivo de cabeçalho: afxmsg_.h

ON_CONTROL

Indica qual função manipulará uma mensagem de notificação de controle personalizado.

Sintaxe

ON_CONTROL( wNotifyCode, commandId, memberFxn )

Parâmetros

wNotifyCode
O código de notificação do controle.

commandId
A ID do comando.

memberFxn
O nome da função de manipulador de mensagens para a qual o comando é mapeado.

Comentários

As mensagens de notificação de controle são aquelas enviadas de um controle para a janela pai.

Deve haver exatamente uma instrução de macro ON_CONTROL em seu mapa de mensagens para cada mensagem de notificação de controle que deve ser mapeada para uma função de manipulador de mensagens.

Para mais informações e exemplos, confira Tópicos de tratamento e mapeamento de mensagens.

Requisitos

Cabeçalhoafxmsg_.h:

ON_MESSAGE

Indica qual função lidará com uma mensagem definida pelo usuário.

Sintaxe

ON_MESSAGE( message, memberFxn )

Parâmetros

message
A ID da mensagem.

memberFxn
O nome da função de manipulador de mensagens para a qual a mensagem é mapeada.

O tipo da função deve ser afx_msg LRESULT (CWnd::*)(WPARAM, LPARAM).

Comentários

Mensagens definidas pelo usuário são mensagens que não são mensagens padrão do Windows WM_MESSAGE. Ao selecionar uma ID de mensagem, você deve usar valores dentro do intervalo de WM_USER (0x0400) para 0x7FFF ou WM_APP (0x8000) para 0xBFFF. Para mais informações sobre IDs de mensagem, confira WM_APP.

Deve haver exatamente uma instrução de macro ON_MESSAGE em seu mapa de mensagens para cada mensagem definida pelo usuário que deve ser mapeada para uma função de manipulador de mensagens.

Observação

Além das mensagens definidas pelo usuário, ON_MESSAGE lida com mensagens menos comuns do Windows. Para mais informações, confira Mapas de Mensagens.

Para mais informações e exemplos, confira Tópicos de tratamento e mapeamento de mensagens e Manipuladores definidos pelo usuário

Exemplo

#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

Cabeçalhoafxmsg_.h:

ON_OLECMD

Roteia comandos por meio da interface de expedição de comando IOleCommandTarget.

Sintaxe

ON_OLECMD( pguid, olecmdid, commandId )

Parâmetros

pguid
Identificador do grupo de comandos ao qual o comando pertence. Use NULL para o grupo padrão.

olecmdid
O identificador do comando OLE.

commandId
A ID do menu, a ID da barra de ferramentas, a ID do botão ou outra ID do recurso ou objeto que emite o comando.

Comentários

IOleCommandTarget permite que um contêiner receba comandos que se originam na interface do usuário de um DocObject e permite que o contêiner envie os mesmos comandos (como Novo, Abrir, Salvar Como e Imprimir no menu Arquivo; e Copiar, Colar, Desfazer etc. no menu Editar) para um DocObject.

IOleCommandTarget é mais simples do que IDispatch da Automação OLE. IOleCommandTarget depende por completo de um conjunto padrão de comandos que raramente têm argumentos e nenhuma informação de tipo está envolvida (a segurança do tipo também é diminuída para argumentos de comando). Se você precisar expedir comandos com argumentos, use COleServerDoc::OnExecOleCmd.

Os comandos IOleCommandTarget de menu padrão foram implementados pelo MFC nas seguintes macros:

ON_OLECMD_CLEARSELECTION( )

Expede o comando Edit Clear. Implementado como:

ON_OLECMD(NULL, OLECMDID_CLEARSELECTION, ID_EDIT_CLEAR)

ON_OLECMD_COPY( )

Expede o comando Edit Copy. Implementado como:

ON_OLECMD(NULL, OLECMDID_COPY, ID_EDIT_COPY)

ON_OLECMD_CUT( )

Expede o comando Edit Cut. Implementado como:

ON_OLECMD(NULL, OLECMDID_CUT, ID_EDIT_CUT)

ON_OLECMD_NEW( )

Expede o comando File New. Implementado como:

ON_OLECMD(NULL, OLECMDID_NEW, ID_FILE_NEW)

ON_OLECMD_OPEN( )

Expede o comando Open File. Implementado como:

ON_OLECMD(NULL, OLECMDID_OPEN, ID_FILE_OPEN)

ON_OLECMD_PAGESETUP( )

Expede o comando File Page Setup. Implementado como:

ON_OLECMD(NULL, OLECMDID_PAGESETUP, ID_FILE_PAGE_SETUP)

ON_OLECMD_PASTE( )

Expede o comando Edit Paste. Implementado como:

ON_OLECMD(NULL, OLECMDID_PASTE, ID_EDIT_PASTE)

ON_OLECMD_PASTESPECIAL( )

Expede o comando Edit Paste Special. Implementado como:

ON_OLECMD(NULL, OLECMDID_PASTESPECIAL, ID_EDIT_PASTE_SPECIAL)

ON_OLECMD_PRINT( )

Expede o comando File Print. Implementado como:

ON_OLECMD(NULL, OLECMDID_PRINT, ID_FILE_PRINT)

ON_OLECMD_PRINTPREVIEW( )

Expede o comando File Print Preview. Implementado como:

ON_OLECMD(NULL, OLECMDID_PRINTPREVIEW, ID_FILE_PRINT_PREVIEW)

ON_OLECMD_REDO( )

Expede o comando Edit Redo. Implementado como:

ON_OLECMD(NULL, OLECMDID_REDO, ID_EDIT_REDO)

ON_OLECMD_SAVE( )

Expede o comando File Save. Implementado como:

ON_OLECMD(NULL, OLECMDID_SAVE, ID_FILE_SAVE)

ON_OLECMD_SAVE_AS( )

Expede o comando File Save As. Implementado como:

ON_OLECMD(NULL, OLECMDID_SAVEAS, ID_FILE_SAVE_AS)

ON_OLECMD_SAVE_COPY_AS( )

Expede o comando File Save Copy As. Implementado como:

ON_OLECMD(NULL, OLECMDID_SAVECOPYAS, ID_FILE_SAVE_COPY_AS)

ON_OLECMD_SELECTALL( )

Expede o comando Edit Select All. Implementado como:

ON_OLECMD(NULL, OLECMDID_SELECTALL, ID_EDIT_SELECT_ALL)

ON_OLECMD_UNDO( )

Expede o comando Edit Undo. Implementado como:

ON_OLECMD(NULL, OLECMDID_UNDO, ID_EDIT_UNDO)

Requisitos

Cabeçalhoafxdocob.h:

ON_REGISTERED_MESSAGE

A função Windows RegisterWindowMessage é usada para definir uma nova mensagem de janela que com certeza será exclusiva em todo o sistema.

Sintaxe

ON_REGISTERED_MESSAGE( nMessageVariable, memberFxn )

Parâmetros

nMessageVariable
A variável de ID de mensagem de janela registrada.

memberFxn
O nome da função de manipulador de mensagens para a qual a mensagem é mapeada.

Comentários

Essa macro indica qual função lidará com a mensagem registrada.

Para mais informações e exemplos, confira Tópicos de tratamento e mapeamento de mensagens.

Exemplo

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

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

Requisitos

Cabeçalhoafxmsg_.h:

ON_REGISTERED_THREAD_MESSAGE

Indica qual função manipulará a mensagem registrada pela função do Windows RegisterWindowMessage.

Sintaxe

ON_REGISTERED_THREAD_MESSAGE(nMessageVariable, memberFxn )

Parâmetros

nMessageVariable
A variável de ID de mensagem de janela registrada.

memberFxn
O nome da função do manipulador de mensagem CWinThread para a qual a mensagem é mapeada.

Comentários

RegisterWindowMessage é usado para definir uma nova mensagem de janela que com certeza será exclusiva em todo o sistema. ON_REGISTERED_THREAD_MESSAGE deve ser usado em vez de ON_REGISTERED_MESSAGE quando você tem uma classe CWinThread.

Requisitos

Cabeçalhoafxmsg_.h:

ON_THREAD_MESSAGE

Indica qual função lidará com uma mensagem definida pelo usuário.

Sintaxe

ON_THREAD_MESSAGE( message, memberFxn )

Parâmetros

message
A ID da mensagem.

memberFxn
O nome da função do manipulador de mensagem CWinThread para a qual a mensagem é mapeada.

Comentários

ON_THREAD_MESSAGE deve ser usado em vez de ON_MESSAGE quando você tem uma classe CWinThread. Mensagens definidas pelo usuário são mensagens que não são mensagens padrão do Windows WM_MESSAGE. Deve haver exatamente uma instrução de macro ON_THREAD_MESSAGE em seu mapa de mensagens para cada mensagem definida pelo usuário que deve ser mapeada para uma função de manipulador de mensagens.

Requisitos

Cabeçalhoafxole.h:

ON_UPDATE_COMMAND_UI

Essa macro indica qual função lidará com uma mensagem de comando de atualização da interface do usuário.

Sintaxe

ON_UPDATE_COMMAND_UI( messageId, memberFxn )

Parâmetros

messageId
A ID da mensagem.

memberFxn
O nome da função de manipulador de mensagens para a qual a mensagem é mapeada.

Comentários

Deve haver exatamente uma instrução de macro ON_UPDATE_COMMAND_UI em seu mapa de mensagens para cada comando de atualização da interface do usuário que deve ser mapeado para uma função de manipulador de mensagens.

Para mais informações e exemplos, confira Tópicos de tratamento e mapeamento de mensagens.

Requisitos

Cabeçalhoafxole.h:

ON_COMMAND_RANGE

Use essa macro para mapear um intervalo contíguo de IDs de comando para uma só função de manipulador de mensagens.

Sintaxe

ON_COMMAND_RANGE( id1, id2, memberFxn )

Parâmetros

id1
ID de comando no início de um intervalo contíguo de IDs de comando.

id2
ID de comando no fim de um intervalo contíguo de IDs de comando.

memberFxn
O nome da função de manipulador de mensagens para a qual os comandos são mapeados.

Comentários

O intervalo de IDs começa com id1 e termina com id2.

Use ON_COMMAND_RANGE para mapear um intervalo de IDs de comando para uma função de membro. Use ON_COMMAND para mapear um só comando para uma função de membro. Somente uma entrada de mapa de mensagem pode corresponder a uma determinada ID de comando. Ou seja, você não pode mapear um comando para mais de um manipulador. Para mais informações sobre o mapeamento de intervalos de mensagens, confira Manipuladores para intervalos de Message-Map.

Não há suporte automático para intervalos de mapa de mensagens, portanto, você mesmo deve posicionar a macro.

Exemplo

// 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

Cabeçalhoafxmsg_.h:

ON_UPDATE_COMMAND_UI_RANGE

Mapeia um intervalo contíguo de IDs de comando para uma só função de manipulador de mensagens de atualização.

Sintaxe

ON_UPDATE_COMMAND_UI_RANGE( id1, id2, memberFxn )

Parâmetros

id1
ID de comando no início de um intervalo contíguo de IDs de comando.

id2
ID de comando no fim de um intervalo contíguo de IDs de comando.

memberFxn
O nome da função de manipulador de mensagens de atualização para a qual os comandos são mapeados.

Comentários

Os manipuladores de mensagens de atualização atualizam o estado dos itens de menu e dos botões da barra de ferramentas associados ao comando. O intervalo de IDs começa com id1 e termina com id2.

Não há suporte automático para intervalos de mapa de mensagens, portanto, você mesmo deve posicionar a macro.

Requisitos

Cabeçalhoafxmsg_.h:

ON_CONTROL_RANGE

Use essa macro para mapear um intervalo contíguo de IDs de controle para uma só função de manipulador de mensagens para uma mensagem de notificação especificada do Windows, como BN_CLICKED.

Sintaxe

ON_CONTROL_RANGE( wNotifyCode, id1, id2, memberFxn )

Parâmetros

wNotifyCode
O código de notificação ao qual o manipulador está respondendo.

id1
ID de comando no início de um intervalo contíguo de IDs de controle.

id2
ID de comando no final de um intervalo contíguo de IDs de controle.

memberFxn
O nome da função de manipulador de mensagens para a qual os controles são mapeados.

Comentários

O intervalo de IDs começa com id1 e termina com id2. O manipulador é chamado para a notificação especificada proveniente de qualquer um dos controles mapeados.

Não há suporte automático para intervalos de mapa de mensagens, portanto, você mesmo deve posicionar a macro.

Para mais informações sobre como implementar funções de manipulador para um intervalo de IDs de controle, confira Manipuladores para intervalos de Message-Map.

Requisitos

Cabeçalhoafxmsg_.h:

Confira também

ON_COMMAND
TN006: mapas de mensagem
Classe COleCmdUI
COleServerDoc::OnExecOleCmd
RegisterWindowMessage
Manipuladores definidos pelo usuário
Classe CCmdUI