Макросы схемы сообщений (MFC)
Для поддержки карт сообщений MFC предоставляет следующие макросы:
Объявление и размечение макросов сопоставления сообщений
| Имя | Описание |
|---|---|
DECLARE_MESSAGE_MAP |
Объявляет, что карта сообщений будет использоваться в классе для сопоставления сообщений с функциями (необходимо использовать в объявлении класса). |
BEGIN_MESSAGE_MAP |
Начинает определение карты сообщений (необходимо использовать в реализации класса). |
BEGIN_TEMPLATE_MESSAGE_MAP |
Начинает определение карты сообщений для типа класса, содержащего один аргумент шаблона. |
END_MESSAGE_MAP |
Заканчивает определение карты сообщений (необходимо использовать в реализации класса). |
Макросы сопоставления сообщений
| Имя | Описание |
|---|---|
ON_COMMAND |
Указывает, какая функция будет обрабатывать указанное сообщение команды. |
ON_COMMAND_EX |
Указывает, какая функция будет обрабатывать указанное сообщение команды. |
ON_CONTROL |
Указывает, какая функция будет обрабатывать указанное сообщение с уведомлением элемента управления. |
ON_MESSAGE |
Указывает, какая функция будет обрабатывать определяемое пользователем сообщение. |
ON_OLECMD |
Указывает, какая функция будет обрабатывать команду меню из DocObject или его контейнера. |
ON_REGISTERED_MESSAGE |
Указывает, какая функция будет обрабатывать зарегистрированное пользовательское сообщение. |
ON_REGISTERED_THREAD_MESSAGE |
Указывает, какая функция будет обрабатывать зарегистрированное пользовательское сообщение при наличии CWinThread класса. |
ON_THREAD_MESSAGE |
Указывает, какая функция будет обрабатывать определяемое пользователем сообщение при наличии CWinThread класса. |
ON_UPDATE_COMMAND_UI |
Указывает, какая функция будет обрабатывать указанное сообщение команды обновления пользовательского интерфейса. |
Макросы диапазона сопоставления сообщений
| Имя | Описание |
|---|---|
ON_COMMAND_RANGE |
Указывает, какая функция будет обрабатывать диапазон идентификаторов команд, указанных в первых двух параметрах макроса. |
ON_UPDATE_COMMAND_UI_RANGE |
Указывает, какой обработчик обновления будет обрабатывать диапазон идентификаторов команд, указанных в первых двух параметрах макроса. |
ON_CONTROL_RANGE |
Указывает, какая функция будет обрабатывать уведомления из диапазона идентификаторов элементов управления, указанных во втором и третьем параметрах макроса. Первый параметр — это сообщение об уведомлении элемента управления, например BN_CLICKED. |
Дополнительные сведения о картах сообщений, объявлениях и размечении сообщений и макросах сопоставления сообщений см. в разделах "Сообщения" Карты и "Обработка сообщений" и "Сопоставления сообщений". Дополнительные сведения о диапазонах карты сообщений см. в разделе "Обработчики" для диапазонов карт сообщений.
BEGIN_MESSAGE_MAP
Начинает определение карты сообщений.
Синтаксис
BEGIN_MESSAGE_MAP( theClass, baseClass )
Параметры
theClass
Указывает имя класса, сопоставление сообщений которого это.
baseClass
Указывает имя базового класса theClass.
Замечания
В файле реализации (CPP), который определяет функции-члены для класса, запустите карту сообщений с BEGIN_MESSAGE_MAP макросом, а затем добавьте записи макросов для каждой функции обработчика сообщений и завершите сопоставление сообщений с END_MESSAGE_MAP помощью макроса.
Дополнительные сведения о картах сообщений см. в разделе "Сообщения Карты"
Пример
BEGIN_MESSAGE_MAP(CMainFrame, CMDIFrameWnd)
ON_WM_CREATE()
END_MESSAGE_MAP()
Требования
Заголовок.afxwin.h
BEGIN_TEMPLATE_MESSAGE_MAP
Начинает определение карты сообщений для типа класса, содержащего один аргумент шаблона.
Синтаксис
BEGIN_TEMPLATE_MESSAGE_MAP( theClass, type_name, baseClass )
Параметры
theClass
Указывает имя класса, сопоставление сообщений которого это.
type_name
Имя параметра шаблона, указанного для класса.
baseClass
Указывает имя базового класса theClass.
Замечания
Этот макрос похож на BEGIN_MESSAGE_MAP макрос. Однако этот макрос предназначен для классов, содержащих один аргумент шаблона.
В разделе реализации метода класса запустите карту сообщений с BEGIN_TEMPLATE_MESSAGE_MAP макросом, а затем добавьте записи макросов для каждого из методов обработчика сообщений, как и для стандартной карты сообщений. Как и в BEGIN_MESSAGE_MAP макросе, завершите сопоставление сообщений шаблона с END_MESSAGE_MAP помощью макроса.
Дополнительные сведения о реализации карт сообщений для классов шаблонов см. в статье "Практическое руководство. Создание карты сообщений для класса шаблона".
Требования
Заголовок.afxwin.h
DECLARE_MESSAGE_MAP
Объявляет, что класс определяет карту сообщений. Каждый CCmdTargetпроизводный класс в программе должен предоставить карту сообщений для обработки сообщений.
Синтаксис
DECLARE_MESSAGE_MAP( )
Замечания
DECLARE_MESSAGE_MAP Используйте макрос в конце объявления класса. Затем в CPP-файле, который определяет функции-члены для класса, используйте BEGIN_MESSAGE_MAP макрос, записи макросов для каждой функции обработчика сообщений и END_MESSAGE_MAP макрос.
Примечание.
Если вы объявляете любой член послеDECLARE_MESSAGE_MAP, необходимо указать новый тип доступа (privatepublicилиprotected) для них.
Дополнительные сведения о картах сообщений и макросе см. в разделах об обработке DECLARE_MESSAGE_MAP и сопоставлении сообщений.
Пример
class CMainFrame : public CMDIFrameWnd
{
DECLARE_MESSAGE_MAP()
// Remainder of class declaration omitted.
Требования
Заголовок.afxwin.h
END_MESSAGE_MAP
Заканчивает определение карты сообщений.
Синтаксис
END_MESSAGE_MAP( )
Замечания
Дополнительные сведения о картах сообщений и макросе см. в разделах об обработке END_MESSAGE_MAP и сопоставлении сообщений.
Требования
Заголовок.afxwin.h
ON_COMMAND
Этот макрос сопоставляет сообщение команды с функцией-членом.
Синтаксис
ON_COMMAND( commandId, memberFxn )
Параметры
commandId
Идентификатор команды.
memberFxn
Имя функции обработчика сообщений, с которой сопоставляется команда.
Замечания
Она указывает, какая функция будет обрабатывать сообщение команды из объекта пользовательского интерфейса команды, например элемента меню или кнопки панели инструментов.
Когда объект с целевым объектом команды получает сообщение Windows WM_COMMAND с указанным идентификатором, ON_COMMAND вызовет функцию-член memberFxn для обработки сообщения.
Используется ON_COMMAND для сопоставления одной команды с функцией-членом. Используется ON_COMMAND_RANGE для сопоставления диапазона идентификаторов команд с одной функцией-членом. Только одна запись карты сообщений может соответствовать заданному идентификатору команды. То есть вы не можете сопоставить команду с несколькими обработчиками. Дополнительные сведения и примеры см. в разделах об обработке и сопоставлении сообщений.
Пример
BEGIN_MESSAGE_MAP(CMFCListViewDoc, CDocument)
ON_COMMAND(ID_MYCOMMAND, &CMFCListViewDoc::OnMycommand)
END_MESSAGE_MAP()
Требования
Заголовок.afxmsg_.h
ON_COMMAND_EX
Расширенная функция-обработчик команд.
Синтаксис
ON_COMMAND_EX(commandId, memberFxn);
Параметры
commandId
Идентификатор команды.
memberFxn
Имя функции обработчика сообщений, с которой сопоставляется команда.
Замечания
Расширенная форма обработчиков сообщений команд доступна для расширенных использования. Макрос ON_COMMAND_EX используется для таких обработчиков сообщений и предоставляет супермножество ON_COMMAND функций. Расширенные функции-обработчика команд принимают один параметр, UINT содержащий идентификатор команды, и возвращает значение BOOL. Возвращаемое значение должно указывать TRUE на то, что команда была обработана; в противном случае маршрутизация продолжится к другим целевым объектам команды.
Дополнительные сведения см. в техническом примечание [TN006: сообщение Карты]tm006-message-maps.md).
Требования
Файл заголовка: afxmsg_.h
ON_CONTROL
Указывает, какая функция будет обрабатывать сообщение уведомления пользовательского элемента управления.
Синтаксис
ON_CONTROL( wNotifyCode, commandId, memberFxn )
Параметры
wNotifyCode
Код уведомления элемента управления.
commandId
Идентификатор команды.
memberFxn
Имя функции обработчика сообщений, с которой сопоставляется команда.
Замечания
Сообщения уведомлений управления — это сообщения, отправляемые из элемента управления в родительское окно.
В карте сообщений должно быть ровно одна ON_CONTROL инструкция макроса для каждого сообщения уведомления элемента управления, которое должно быть сопоставлено с функцией обработчика сообщений.
Дополнительные сведения и примеры см. в разделах об обработке и сопоставлении сообщений.
Требования
Заголовок.afxmsg_.h
ON_MESSAGE
Указывает, какая функция будет обрабатывать определяемое пользователем сообщение.
Синтаксис
ON_MESSAGE( message, memberFxn )
Параметры
message
Идентификатор сообщения.
memberFxn
Имя функции обработчика сообщений, с которой сопоставляется сообщение.
Тип функции должен быть afx_msg LRESULT (CWnd::*)(WPARAM, LPARAM).
Замечания
Определяемые пользователем сообщения — это сообщения, которые не являются стандартными сообщениями Windows WM_MESSAGE . При выборе идентификатора сообщения необходимо использовать значения в диапазоне WM_USER (0x0400) для 0x7FFF или WM_APP (0x8000) для 0xBFFF. Дополнительные сведения об идентификаторах сообщений см. в статье WM_APP.
В карте сообщений должно быть ровно одна ON_MESSAGE инструкция макроса для каждого определяемого пользователем сообщения, которое должно быть сопоставлено с функцией обработчика сообщений.
Примечание.
Помимо определяемых пользователем сообщений, ON_MESSAGE обрабатывает менее распространенные сообщения Windows. Дополнительные сведения см. в разделе "Сообщение Карты".
Дополнительные сведения и примеры см. в разделе "Обработка сообщений и сопоставление" и "Определяемые пользователем обработчики"
Пример
#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;
}
Требования
Заголовок.afxmsg_.h
ON_OLECMD
Маршрутизирует команды через интерфейс IOleCommandTargetдиспетчеризации команд.
Синтаксис
ON_OLECMD( pguid, olecmdid, commandId )
Параметры
pguid
Идентификатор группы команд, к которой принадлежит команда. Используется NULL для стандартной группы.
olecmdid
Идентификатор команды OLE.
commandId
Идентификатор меню, идентификатор панели инструментов, идентификатор кнопки или другой идентификатор ресурса или объекта, выдавающего команду.
Замечания
IOleCommandTarget позволяет контейнеру получать команды, возникающие в пользовательском интерфейсе DocObject, и позволяет контейнеру отправлять те же команды (например, "Создать", "Открыть", "Сохранить" и "Печать" в меню "Файл"; и "Копировать", "Вставить", "Отменить" и т. д. в меню "Изменить") в DocObject.
IOleCommandTarget проще, чем OLE Automation IDispatch. IOleCommandTarget полностью использует стандартный набор команд, которые редко имеют аргументы, и информация о типе не участвует (безопасность типов также уменьшается для аргументов команд). Если вам нужно отправить команды с аргументами, используйте COleServerDoc::OnExecOleCmd.
Стандартные IOleCommandTarget команды меню реализованы MFC в следующих макросах:
ON_OLECMD_CLEARSELECTION( )
Отправляет команду Edit Clear. Реализовано как:
ON_OLECMD(NULL, OLECMDID_CLEARSELECTION, ID_EDIT_CLEAR)
ON_OLECMD_COPY( )
Отправляет команду "Изменить копию". Реализовано как:
ON_OLECMD(NULL, OLECMDID_COPY, ID_EDIT_COPY)
ON_OLECMD_CUT( )
Отправляет команду "Изменить вырезать". Реализовано как:
ON_OLECMD(NULL, OLECMDID_CUT, ID_EDIT_CUT)
ON_OLECMD_NEW( )
Отправляет команду "Создать файл". Реализовано как:
ON_OLECMD(NULL, OLECMDID_NEW, ID_FILE_NEW)
ON_OLECMD_OPEN( )
Отправляет команду "Открыть файл". Реализовано как:
ON_OLECMD(NULL, OLECMDID_OPEN, ID_FILE_OPEN)
ON_OLECMD_PAGESETUP( )
Отправляет команду установки страницы файлов. Реализовано как:
ON_OLECMD(NULL, OLECMDID_PAGESETUP, ID_FILE_PAGE_SETUP)
ON_OLECMD_PASTE( )
Отправляет команду "Изменить вставку". Реализовано как:
ON_OLECMD(NULL, OLECMDID_PASTE, ID_EDIT_PASTE)
ON_OLECMD_PASTESPECIAL( )
Отправляет команду Edit Paste Special. Реализовано как:
ON_OLECMD(NULL, OLECMDID_PASTESPECIAL, ID_EDIT_PASTE_SPECIAL)
ON_OLECMD_PRINT( )
Отправляет команду "Печать файла". Реализовано как:
ON_OLECMD(NULL, OLECMDID_PRINT, ID_FILE_PRINT)
ON_OLECMD_PRINTPREVIEW( )
Отправляет команду "Предварительный просмотр файла". Реализовано как:
ON_OLECMD(NULL, OLECMDID_PRINTPREVIEW, ID_FILE_PRINT_PREVIEW)
ON_OLECMD_REDO( )
Отправляет команду Edit Redo. Реализовано как:
ON_OLECMD(NULL, OLECMDID_REDO, ID_EDIT_REDO)
ON_OLECMD_SAVE( )
Отправляет команду "Сохранить файл". Реализовано как:
ON_OLECMD(NULL, OLECMDID_SAVE, ID_FILE_SAVE)
ON_OLECMD_SAVE_AS( )
Отправляет команду "Сохранить файл как". Реализовано как:
ON_OLECMD(NULL, OLECMDID_SAVEAS, ID_FILE_SAVE_AS)
ON_OLECMD_SAVE_COPY_AS( )
Отправляет команду "Сохранить файл от имени". Реализовано как:
ON_OLECMD(NULL, OLECMDID_SAVECOPYAS, ID_FILE_SAVE_COPY_AS)
ON_OLECMD_SELECTALL( )
Отправляет команду "Изменить все". Реализовано как:
ON_OLECMD(NULL, OLECMDID_SELECTALL, ID_EDIT_SELECT_ALL)
ON_OLECMD_UNDO( )
Отправляет команду "Изменить отмену". Реализовано как:
ON_OLECMD(NULL, OLECMDID_UNDO, ID_EDIT_UNDO)
Требования
Заголовок.afxdocob.h
ON_REGISTERED_MESSAGE
Функция Windows RegisterWindowMessage используется для определения нового сообщения окна, которое гарантированно будет уникальным во всей системе.
Синтаксис
ON_REGISTERED_MESSAGE( nMessageVariable, memberFxn )
Параметры
nMessageVariable
Зарегистрированная переменная идентификатора сообщения окна.
memberFxn
Имя функции обработчика сообщений, с которой сопоставляется сообщение.
Замечания
Этот макрос указывает, какая функция будет обрабатывать зарегистрированное сообщение.
Дополнительные сведения и примеры см. в разделах об обработке и сопоставлении сообщений.
Пример
static UINT NEAR WM_FIND = RegisterWindowMessage(_T("COMMDLG_FIND"));
BEGIN_MESSAGE_MAP(CMyWnd3, CWnd)
ON_REGISTERED_MESSAGE(WM_FIND, OnFind)
END_MESSAGE_MAP()
Требования
Заголовок.afxmsg_.h
ON_REGISTERED_THREAD_MESSAGE
Указывает, какая функция будет обрабатывать сообщение, зарегистрированное функцией Windows RegisterWindowMessage .
Синтаксис
ON_REGISTERED_THREAD_MESSAGE(nMessageVariable, memberFxn )
Параметры
nMessageVariable
Зарегистрированная переменная идентификатора сообщения окна.
memberFxn
Имя CWinThreadфункции -message-handler, с которой сопоставляется сообщение.
Замечания
RegisterWindowMessage используется для определения нового сообщения окна, которое гарантированно будет уникальным во всей системе. ON_REGISTERED_THREAD_MESSAGE следует использовать вместо того, ON_REGISTERED_MESSAGE когда у вас есть CWinThread класс.
Требования
Заголовок.afxmsg_.h
ON_THREAD_MESSAGE
Указывает, какая функция будет обрабатывать определяемое пользователем сообщение.
Синтаксис
ON_THREAD_MESSAGE( message, memberFxn )
Параметры
message
Идентификатор сообщения.
memberFxn
Имя CWinThreadфункции -message-handler, с которой сопоставляется сообщение.
Замечания
ON_THREAD_MESSAGE следует использовать вместо того, ON_MESSAGE когда у вас есть CWinThread класс. Определяемые пользователем сообщения — это сообщения, которые не являются стандартными сообщениями Windows WM_MESSAGE . В карте сообщений должно быть ровно одна ON_THREAD_MESSAGE инструкция макроса для каждого определяемого пользователем сообщения, которое должно быть сопоставлено с функцией обработчика сообщений.
Требования
Заголовок.afxole.h
ON_UPDATE_COMMAND_UI
Этот макрос указывает, какая функция будет обрабатывать сообщение команды обновления пользовательского интерфейса.
Синтаксис
ON_UPDATE_COMMAND_UI( messageId, memberFxn )
Параметры
messageId
Идентификатор сообщения.
memberFxn
Имя функции обработчика сообщений, с которой сопоставляется сообщение.
Замечания
В карте сообщений должно быть ровно одна ON_UPDATE_COMMAND_UI инструкция макроса для каждой команды обновления пользовательского интерфейса, которая должна быть сопоставлена с функцией обработчика сообщений.
Дополнительные сведения и примеры см. в разделах об обработке и сопоставлении сообщений.
Требования
Заголовок.afxole.h
ON_COMMAND_RANGE
Используйте этот макрос для сопоставления непрерывного диапазона идентификаторов команд с одной функцией обработчика сообщений.
Синтаксис
ON_COMMAND_RANGE( id1, id2, memberFxn )
Параметры
id1
Идентификатор команды в начале непрерывного диапазона идентификаторов команд.
id2
Идентификатор команды в конце непрерывного диапазона идентификаторов команд.
memberFxn
Имя функции обработчика сообщений, с которой сопоставляются команды.
Замечания
Диапазон идентификаторов начинается id1 с и заканчивается id2.
Используется ON_COMMAND_RANGE для сопоставления диапазона идентификаторов команд с одной функцией-членом. Используется ON_COMMAND для сопоставления одной команды с функцией-членом. Только одна запись карты сообщений может соответствовать заданному идентификатору команды. То есть вы не можете сопоставить команду с несколькими обработчиками. Дополнительные сведения о сопоставлениях диапазонов сообщений см. в разделе "Обработчики" для диапазонов карт сообщений.
Нет автоматической поддержки диапазонов карт сообщений, поэтому необходимо разместить макрос самостоятельно.
Пример
// 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);
}
Требования
Заголовок.afxmsg_.h
ON_UPDATE_COMMAND_UI_RANGE
Карты непрерывный диапазон идентификаторов команд в одну функцию обработчика сообщений обновления.
Синтаксис
ON_UPDATE_COMMAND_UI_RANGE( id1, id2, memberFxn )
Параметры
id1
Идентификатор команды в начале непрерывного диапазона идентификаторов команд.
id2
Идентификатор команды в конце непрерывного диапазона идентификаторов команд.
memberFxn
Имя функции обработчика сообщений обновления, с которой сопоставляются команды.
Замечания
Обновите обработчики сообщений состояние элементов меню и кнопок панели инструментов, связанных с командой. Диапазон идентификаторов начинается id1 с и заканчивается id2.
Нет автоматической поддержки диапазонов карт сообщений, поэтому необходимо разместить макрос самостоятельно.
Требования
Заголовок.afxmsg_.h
ON_CONTROL_RANGE
Используйте этот макрос для сопоставления непрерывного диапазона идентификаторов элементов управления с одной функцией обработчика сообщений для указанного сообщения уведомления Windows, например BN_CLICKED.
Синтаксис
ON_CONTROL_RANGE( wNotifyCode, id1, id2, memberFxn )
Параметры
wNotifyCode
Код уведомления, на который отвечает обработчик.
id1
Идентификатор команды в начале непрерывного диапазона идентификаторов элементов управления.
id2
Идентификатор команды в конце непрерывного диапазона идентификаторов элементов управления.
memberFxn
Имя функции обработчика сообщений, с которой сопоставляются элементы управления.
Замечания
Диапазон идентификаторов начинается id1 с и заканчивается id2. Обработчик вызывается для указанного уведомления, исходящего из любого сопоставленного элемента управления.
Нет автоматической поддержки диапазонов карт сообщений, поэтому необходимо разместить макрос самостоятельно.
Дополнительные сведения о реализации функций обработчика для диапазона идентификаторов элементов управления см. в разделе "Обработчики" для диапазонов карт сообщений.
Требования
Заголовок.afxmsg_.h
См. также
ON_COMMAND
TN006. Схемы сообщений
COleCmdUI Класса
COleServerDoc::OnExecOleCmd
RegisterWindowMessage
Пользовательские обработчики
CCmdUI Класса
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по