Partilhar via


Macros de Mapa de Mensagens (MFC)

Observação

A biblioteca Microsoft Foundation Classes (MFC) continua a ser suportada. No entanto, já não estamos a adicionar funcionalidades nem a atualizar a documentação.

Para suportar mapas de mensagens, o MFC fornece as seguintes macros:

Message-Map Macros de Declaração e Demarcação

Nome Description
DECLARE_MESSAGE_MAP Declara que um mapa de mensagens será usado numa classe para mapear mensagens para funções (deve ser usado na declaração da classe).
BEGIN_MESSAGE_MAP Começa a definição de um mapa de mensagens (deve ser usado na implementação da classe).
BEGIN_TEMPLATE_MESSAGE_MAP Começa a definição de um mapa de mensagem num tipo de classe que contém um único argumento modelo.
END_MESSAGE_MAP Termina a definição de um mapa de mensagem (deve ser usado na implementação de classes).

Message-Mapping Macros

Nome Description
ON_COMMAND Indica qual a função que irá tratar uma mensagem de comando especificada.
ON_COMMAND_EX Indica qual a função que irá tratar uma mensagem de comando especificada.
ON_CONTROL Indica qual função irá tratar uma mensagem de controlo-notificação especificada.
ON_MESSAGE Indica qual a função que irá tratar uma mensagem definida pelo utilizador.
ON_OLECMD Indica qual função irá gerir um comando de menu a partir de um DocObject ou do seu contentor.
ON_REGISTERED_MESSAGE Indica qual a função que irá tratar uma mensagem definida pelo utilizador registada.
ON_REGISTERED_THREAD_MESSAGE Indica que função tratará uma mensagem definida pelo utilizador registada quando tem uma CWinThread classe.
ON_THREAD_MESSAGE Indica que função irá tratar uma mensagem definida pelo utilizador quando tem uma CWinThread classe.
ON_UPDATE_COMMAND_UI Indica qual função irá tratar uma mensagem de comando de atualização da interface de utilizador especificada.

Message-Map Macros do Intervalo

Nome Description
ON_COMMAND_RANGE Indica qual a função que irá lidar com o intervalo de IDs de comandos especificados nos dois primeiros parâmetros da macro.
ON_UPDATE_COMMAND_UI_RANGE Indica qual o handler de atualização que irá tratar do intervalo de IDs de comandos especificados nos dois primeiros parâmetros do macro.
ON_CONTROL_RANGE Indica qual função irá gerir notificações a partir do intervalo de IDs de controlo especificados no segundo e terceiro parâmetros para a macro. O primeiro parâmetro é uma mensagem de notificação de controlo, como BN_CLICKED.

Para mais informações sobre mapas de mensagens, macros de declaração e demarcação de mapas de mensagens, e macros de mapeamento de mensagens, consulte Mapas de Mensagens e Tópicos de Tratamento e Mapeamento de Mensagens. Para mais informações sobre intervalos de mapas de mensagens, consulte Handlers para Message-Map Intervalos.

BEGIN_MESSAGE_MAP

Começa a definição do seu mapa de mensagens.

Sintaxe

BEGIN_MESSAGE_MAP( theClass, baseClass )

Parâmetros

theClass
Especifica o nome da classe cujo mapa de mensagens pertence.

baseClass
Especifica o nome da classe base de theClass.

Observações

No ficheiro de implementação (.cpp) que define as funções membros da sua classe, inicie o mapa da mensagem com a BEGIN_MESSAGE_MAP macro, depois adicione entradas de macro para cada uma das suas funções do manipulador de mensagens e complete o mapa da mensagem com a END_MESSAGE_MAP macro.

Para mais informações sobre mapas de mensagens, consulte Mapas de Mensagens

Example

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

Requerimentos

Cabeçalho:afxwin.h

BEGIN_TEMPLATE_MESSAGE_MAP

Começa a definição de um mapa de mensagem num tipo de classe que contém um único argumento modelo.

Sintaxe

BEGIN_TEMPLATE_MESSAGE_MAP( theClass, type_name, baseClass )

Parâmetros

theClass
Especifica o nome da classe cujo mapa de mensagens pertence.

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

baseClass
Especifica o nome da classe base de theClass.

Observações

Esta macro é semelhante à BEGIN_MESSAGE_MAP macro; no entanto, esta macro destina-se a classes que contêm um único argumento de template.

Na secção de implementação de métodos da sua turma, inicie o mapa de mensagens com a BEGIN_TEMPLATE_MESSAGE_MAP macro; depois adicione entradas de macro para cada um dos seus métodos de manipulador de mensagens, tal como faria num mapa de mensagens padrão. Tal como na BEGIN_MESSAGE_MAP macro, complete o mapa da mensagem modelo com a END_MESSAGE_MAP macro.

Para mais informações sobre a implementação de mapas de mensagens para classes modelo, consulte Como: Criar um Mapa de Mensagem para uma Classe Modelo.

Requerimentos

Cabeçalho:afxwin.h

DECLARE_MESSAGE_MAP

Declara que a classe define um mapa de mensagem. Cada CCmdTargetclasse derivada em - no seu programa deve fornecer um mapa de mensagens para tratar as mensagens.

Sintaxe

DECLARE_MESSAGE_MAP( )

Observações

Usa a DECLARE_MESSAGE_MAP macro no final da tua declaração de aula. Depois, no ficheiro .cpp que define as funções membros da classe, usa a BEGIN_MESSAGE_MAP macro, as entradas da macro para cada uma das tuas funções do manipulador de mensagens e a END_MESSAGE_MAP macro.

Observação

Se declarar algum membro depois DECLARE_MESSAGE_MAPde , deve especificar um novo tipo de acesso (public, private, ou protected) para ele.

Para mais informações sobre mapas de mensagens e o DECLARE_MESSAGE_MAP macro, consulte Temas de Gestão e Mapeamento de Mensagens.

Example

class CMainFrame : public CMDIFrameWnd
{
   DECLARE_MESSAGE_MAP()

   // Remainder of class declaration omitted.

Requerimentos

Cabeçalho:afxwin.h

END_MESSAGE_MAP

Termina a definição do teu mapa de mensagens.

Sintaxe

END_MESSAGE_MAP( )

Observações

Para mais informações sobre mapas de mensagens e o END_MESSAGE_MAP macro, consulte Temas de Gestão e Mapeamento de Mensagens.

Requerimentos

Cabeçalho:afxwin.h

ON_COMMAND

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

Sintaxe

ON_COMMAND( commandId, memberFxn )

Parâmetros

commandId
O ID do comando.

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

Observações

Indica qual a função que irá tratar uma mensagem de comando a partir de um objeto de interface de utilizador de comando, como um item de menu ou um botão de barra de ferramentas.

Quando um objeto destino-comando recebe uma mensagem Windows WM_COMMAND com o ID especificado, ON_COMMAND chamará a função memberFxn membro para tratar a mensagem.

Use ON_COMMAND para mapear um único comando para uma função membro. Use ON_COMMAND_RANGE para mapear um intervalo de IDs de comandos para uma função membro. Apenas uma entrada no mapa de mensagens pode corresponder a um determinado ID de comando. Ou seja, não podes mapear um comando para mais do que um handler. Para mais informações e exemplos, consulte Temas de Gestão e Mapeamento de Mensagens.

Example

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

Requerimentos

Cabeçalho:afxmsg_.h

ON_COMMAND_EX

Função estendida do handler de comandos.

Sintaxe

ON_COMMAND_EX(commandId, memberFxn);

Parâmetros

commandId
O ID do comando.

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

Observações

Existe uma forma estendida de manipuladores de mensagens de comando para usos avançados. A ON_COMMAND_EX macro é usada para esses manipuladores de mensagens e fornece um superconjunto da ON_COMMAND funcionalidade. As funções membros do handler de comandos estendidas tomam um único parâmetro, a UINT contendo o ID do comando, e retornam um BOOL. O valor de retorno deve indicar TRUE que o comando foi tratado; caso contrário, o encaminhamento continuará para outros objetos-alvo de comando.

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

Requerimentos

Ficheiro de cabeçalho: afxmsg_.h

ON_CONTROL

Indica qual a função que irá lidar com uma mensagem de notificação de controlo personalizado.

Sintaxe

ON_CONTROL( wNotifyCode, commandId, memberFxn )

Parâmetros

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

commandId
O ID do comando.

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

Observações

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

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

Para mais informações e exemplos, consulte Temas de Gestão e Mapeamento de Mensagens.

Requerimentos

Cabeçalho:afxmsg_.h

ON_MESSAGE

Indica qual a função que irá tratar uma mensagem definida pelo utilizador.

Sintaxe

ON_MESSAGE( message, memberFxn )

Parâmetros

message
O ID da mensagem.

memberFxn
O nome da função handler de mensagens para a qual a mensagem está mapeada.

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

Observações

Mensagens definidas pelo utilizador são quaisquer mensagens que não sejam mensagens padrão do Windows WM_MESSAGE . Ao selecionar um ID de mensagem, 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 mensagens, consulte WM_APP.

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

Observação

Além das mensagens definidas pelo utilizador, ON_MESSAGE trata mensagens menos comuns do Windows. Para mais informações, consulte Mapas de Mensagens.

Para mais informações e exemplos, consulte Tópicos de Gestão e Mapeamento de Mensagens e Manipuladores deUser-Defined

Example

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

Requerimentos

Cabeçalho:afxmsg_.h

ON_OLECMD

Encaminha comandos através da interface IOleCommandTargetde despacho de comandos.

Sintaxe

ON_OLECMD( pguid, olecmdid, commandId )

Parâmetros

pguid
Identificador do grupo de comandos a que o comando pertence. Use NULL para o grupo padrão.

olecmdid
O identificador do comando OLE.

commandId
O ID do menu, ID da barra de ferramentas, ID do botão ou outro ID do recurso ou objeto que emite o comando.

Observações

IOleCommandTarget permite que um contentor receba comandos originários da interface de utilizador de um DocObject, e permite que o contentor envie os mesmos comandos (como Novo, Abrir, Guardar Como e Imprimir no menu Ficheiro; e Copiar, Colar, Desfazer, e assim por diante no menu Editar) para um DocObject.

IOleCommandTarget é mais simples do que a IDispatchOLE Automation . IOleCommandTarget baseia-se inteiramente num conjunto padrão de comandos que raramente têm argumentos, e não está envolvida informação de tipo (a segurança do tipo também é reduzida para argumentos de comando). Se precisares de despachar comandos com argumentos, usa COleServerDoc::OnExecOleCmd.

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

ON_OLECMD_CLEARSELECTION( )

Despacha o comando Editar Limpar. Implementado como:

ON_OLECMD(NULL, OLECMDID_CLEARSELECTION, ID_EDIT_CLEAR)

ON_OLECMD_COPY( )

Despacha o comando Editar Copiar. Implementado como:

ON_OLECMD(NULL, OLECMDID_COPY, ID_EDIT_COPY)

ON_OLECMD_CUT( )

Despacha o comando Editar Cortar. Implementado como:

ON_OLECMD(NULL, OLECMDID_CUT, ID_EDIT_CUT)

ON_OLECMD_NEW( )

Despacha o comando Ficheiro Novo. Implementado como:

ON_OLECMD(NULL, OLECMDID_NEW, ID_FILE_NEW)

ON_OLECMD_OPEN( )

Despacha o comando Abrir Ficheiro. Implementado como:

ON_OLECMD(NULL, OLECMDID_OPEN, ID_FILE_OPEN)

ON_OLECMD_PAGESETUP( )

Despacha o comando File Page Setup. Implementado como:

ON_OLECMD(NULL, OLECMDID_PAGESETUP, ID_FILE_PAGE_SETUP)

ON_OLECMD_PASTE( )

Despacha o comando Editar Colar. Implementado como:

ON_OLECMD(NULL, OLECMDID_PASTE, ID_EDIT_PASTE)

ON_OLECMD_PASTESPECIAL( )

Despacha o comando especial Editar Colar. Implementado como:

ON_OLECMD(NULL, OLECMDID_PASTESPECIAL, ID_EDIT_PASTE_SPECIAL)

ON_OLECMD_PRINT( )

Despacha o comando Impressão de Ficheiros. Implementado como:

ON_OLECMD(NULL, OLECMDID_PRINT, ID_FILE_PRINT)

ON_OLECMD_PRINTPREVIEW( )

Despacha o comando Pré-visualização de Impressão de Ficheiros. Implementado como:

ON_OLECMD(NULL, OLECMDID_PRINTPREVIEW, ID_FILE_PRINT_PREVIEW)

ON_OLECMD_REDO( )

Despacha o comando Editar Refazer. Implementado como:

ON_OLECMD(NULL, OLECMDID_REDO, ID_EDIT_REDO)

ON_OLECMD_SAVE( )

Despacha o comando de Gravar o Ficheiro. Implementado como:

ON_OLECMD(NULL, OLECMDID_SAVE, ID_FILE_SAVE)

ON_OLECMD_SAVE_AS( )

Despacha o comando Ficheiro Guardar Como. Implementado como:

ON_OLECMD(NULL, OLECMDID_SAVEAS, ID_FILE_SAVE_AS)

ON_OLECMD_SAVE_COPY_AS( )

Despacha o comando Guardar Copiar Como. Implementado como:

ON_OLECMD(NULL, OLECMDID_SAVECOPYAS, ID_FILE_SAVE_COPY_AS)

ON_OLECMD_SELECTALL( )

Despacha o comando Editar Selecionar Tudo. Implementado como:

ON_OLECMD(NULL, OLECMDID_SELECTALL, ID_EDIT_SELECT_ALL)

ON_OLECMD_UNDO( )

Despacha o comando Editar Desfazer. Implementado como:

ON_OLECMD(NULL, OLECMDID_UNDO, ID_EDIT_UNDO)

Requerimentos

Cabeçalho:afxdocob.h

ON_REGISTERED_MESSAGE

A função Windows RegisterWindowMessage é usada para definir uma nova mensagem janela que é garantidamente única em todo o sistema.

Sintaxe

ON_REGISTERED_MESSAGE( nMessageVariable, memberFxn )

Parâmetros

nMessageVariable
A variável registada do ID da mensagem da janela.

memberFxn
O nome da função handler de mensagens para a qual a mensagem está mapeada.

Observações

Esta macro indica qual a função que irá tratar da mensagem registada.

Para mais informações e exemplos, consulte Temas de Gestão e Mapeamento de Mensagens.

Example

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

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

Requerimentos

Cabeçalho:afxmsg_.h

ON_REGISTERED_THREAD_MESSAGE

Indica qual a função que irá tratar da mensagem registada pela função Windows RegisterWindowMessage .

Sintaxe

ON_REGISTERED_THREAD_MESSAGE(nMessageVariable, memberFxn )

Parâmetros

nMessageVariable
A variável registada do ID da mensagem da janela.

memberFxn
O nome da CWinThreadfunção -message-handler para a qual a mensagem está mapeada.

Observações

RegisterWindowMessage é usado para definir uma nova mensagem janela que é garantidamente única em todo o sistema. ON_REGISTERED_THREAD_MESSAGE Deve ser usado em vez de ON_REGISTERED_MESSAGE quando tens uma CWinThread aula.

Requerimentos

Cabeçalho:afxmsg_.h

ON_THREAD_MESSAGE

Indica qual a função que irá tratar uma mensagem definida pelo utilizador.

Sintaxe

ON_THREAD_MESSAGE( message, memberFxn )

Parâmetros

message
O ID da mensagem.

memberFxn
O nome da CWinThreadfunção -message-handler para a qual a mensagem está mapeada.

Observações

ON_THREAD_MESSAGE Deve ser usado em vez de ON_MESSAGE quando tens uma CWinThread aula. Mensagens definidas pelo utilizador são quaisquer mensagens que não sejam mensagens padrão do Windows WM_MESSAGE . Deve haver exatamente uma ON_THREAD_MESSAGE instrução macro no seu mapa de mensagens para cada mensagem definida pelo utilizador que deve ser mapeada para uma função de manipulador de mensagens.

Requerimentos

Cabeçalho:afxole.h

ON_UPDATE_COMMAND_UI

Esta macro indica qual a função que irá tratar uma mensagem de comando de atualização da interface do utilizador.

Sintaxe

ON_UPDATE_COMMAND_UI( messageId, memberFxn )

Parâmetros

messageId
O ID da mensagem.

memberFxn
O nome da função handler de mensagens para a qual a mensagem está mapeada.

Observações

Deve haver exatamente uma ON_UPDATE_COMMAND_UI instrução macro no seu mapa de mensagens para cada comando de atualização da interface de utilizador que deve ser mapeada para uma função de manipulador de mensagens.

Para mais informações e exemplos, consulte Temas de Gestão e Mapeamento de Mensagens.

Requerimentos

Cabeçalho:afxole.h

ON_COMMAND_RANGE

Use esta macro para mapear um intervalo contíguo de IDs de comandos para uma única função de manipulador de mensagens.

Sintaxe

ON_COMMAND_RANGE( id1, id2, memberFxn )

Parâmetros

id1
ID de comando no início de uma gama contígua de IDs de comando.

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

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

Observações

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

Use ON_COMMAND_RANGE para mapear um intervalo de IDs de comandos para uma função membro. Use ON_COMMAND para mapear um único comando para uma função membro. Apenas uma entrada no mapa de mensagens pode corresponder a um determinado ID de comando. Ou seja, não podes mapear um comando para mais do que um handler. Para mais informações sobre o mapeamento de intervalos de mensagens, consulte Handlers para Message-Map Intervalos.

Não há suporte automático para intervalos de mapas de mensagens, por isso tens de colocar a macro tu próprio.

Example

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

Requerimentos

Cabeçalho:afxmsg_.h

ON_UPDATE_COMMAND_UI_RANGE

Mapeia um intervalo contíguo de IDs de comandos para uma única função gestor de mensagens de atualização.

Sintaxe

ON_UPDATE_COMMAND_UI_RANGE( id1, id2, memberFxn )

Parâmetros

id1
ID de comando no início de uma gama contígua de IDs de comando.

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

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

Observações

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

Não há suporte automático para intervalos de mapas de mensagens, por isso tens de colocar a macro tu próprio.

Requerimentos

Cabeçalho:afxmsg_.h

ON_CONTROL_RANGE

Use esta macro para mapear um intervalo contíguo de IDs de controlo para uma única função de manipulador de mensagens para uma mensagem de notificação específica 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 teu handler está a responder.

id1
ID de comando no início de uma gama contígua de IDs de controlo.

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

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

Observações

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

Não há suporte automático para intervalos de mapas de mensagens, por isso tens de colocar a macro tu próprio.

Para mais informações sobre a implementação de funções de handler para uma variedade de IDs de controlo, consulte Handlers para Message-Map Ranges.

Requerimentos

Cabeçalho:afxmsg_.h

Consulte também

ON_COMMAND
TN006: Mapas de mensagens
COleCmdUI Classe
COleServerDoc::OnExecOleCmd
RegisterWindowMessage
User-Defined Manipuladores
CCmdUI Classe