How messages are routed in an Doc/View application?

We have discussed the basic workflow of a minimal doc-view application. We understood the functionalities and responsibilities of each class in doc-view. Developer should implement the responsible OnXXX() user events for each classes and MFC framework internally calls these event.

Now lets understand how MFC message framework routes messages to these classes and how event functions are called from framework.

CFrameWnd class creates the main top level window in the application. Thus all the messages will be submitted to the window procedure of this class. CFrameWnd is derived from the CCmdTarget class and all the messages will be routed to the OnCmdMsg virtual function. CFrameWnd::OnCmdMsg function processes the exection in this way-

  • Process the message in View class
  • Process the message in Frame
  • Process the message in Application class

Message Handler

// CFrameWnd command/message routing

BOOL CFrameWnd::OnCmdMsg(UINT nID, int nCode, void* pExtra,
	AFX_CMDHANDLERINFO* pHandlerInfo)
{
	CPushRoutingFrame push(this);

	// pump through current view FIRST
	CView* pView = GetActiveView();
	if (pView != NULL && pView->OnCmdMsg(nID, nCode, pExtra, pHandlerInfo))
		return TRUE;

	// then pump through frame
	if (CWnd::OnCmdMsg(nID, nCode, pExtra, pHandlerInfo))
		return TRUE;

	// last but not least, pump through app
	CWinApp* pApp = AfxGetApp();
	if (pApp != NULL && pApp->OnCmdMsg(nID, nCode, pExtra, pHandlerInfo))
		return TRUE;

	return FALSE;
}

New Document Event @ startup

New document event is called at the launch of application or when user selects new document menu/toolbar icon.

At the starting of the application this event is called directly from main entry point. This is bacause CWinnApp is still in InitInstance() call and main window frame is still not yet created. Event OnFileNew() is called from the shell command line processing function. 

void CWinApp::OnFileNew()
{
  if (m_pDocManager != NULL)
    m_pDocManager->OnFileNew();
}

Open Document callstack- 

CMySDIDoc::OnNewDocument()
CSingleDocTemplate::OpenDocumentFile()
CDocManager::OnFileNew()
CWinApp::OnFileNew()
_AfxDispatchCmdMsg()
CCmdTarget::OnCmdMsg()
CWinApp::ProcessShellCommand()
CMySDIApp::InitInstance()
AfxWinMain()
WinMain()
WinMainCRTStartup()

New Document Event @ user command

User can trigger this event by clicking on new menu item or clicking on new button in the toolbar. Then this is routed through the message handling of the main frame window. 

void CWinApp::OnFileNew()
{
  if (m_pDocManager != NULL)
    m_pDocManager->OnFileNew();
}

Open Document callstack- 

CMySDIDoc::OnNewDocument()
CSingleDocTemplate::OpenDocumentFile()
CDocManager::OnFileNew()
CWinApp::OnFileNew()
_AfxDispatchCmdMsg()
CCmdTarget::OnCmdMsg()
CFrameWnd::OnCmdMsg()
CWnd::OnCommand()
CFrameWnd::OnCommand()
CWnd::OnWndMsg()
CWnd::WindowProc()
AfxCallWndProc()
AfxWndProc()
AfxWndProcBase()

Open Document Event

An open document event is called when user clicks on open menu or open icon in toolbar. Open document event calls CDocument::Serialize() which loads file content to document. 
void CWinApp::OnFileOpen()
{
  ASSERT(m_pDocManager != NULL);
  m_pDocManager->OnFileOpen();
}

Open Document callstack- 

CMySDIDoc::Serialize()
CDocument::OnOpenDocument()
CSingleDocTemplate::OpenDocumentFile()
CDocManager::OpenDocumentFile()
CWinApp::OpenDocumentFile()
CDocManager::OnFileOpen()
CWinApp::OnFileOpen()
_AfxDispatchCmdMsg()
CCmdTarget::OnCmdMsg()
CFrameWnd::OnCmdMsg()
CWnd::OnCommand()
CFrameWnd::OnCommand()
CWnd::OnWndMsg()
CWnd::WindowProc()
AfxCallWndProc()
AfxWndProc()
AfxWndProcBase()

Save Document Event

Save document event is called when user clicks on save menu or save icon in toolbar. Save document event calls CDocument::Serialize() which finally saves file content to document.

Save Document callstack- 

CMySDIDoc::Serialize()
CDocument::OnSaveDocument()
CDocument::DoSave()
CDocument::DoFileSave()
CDocument::OnFileSave()
_AfxDispatchCmdMsg()
CCmdTarget::OnCmdMsg()
CDocument::OnCmdMsg()
CView::OnCmdMsg()
CFrameWnd::OnCmdMsg()
CWnd::OnCommand()
CFrameWnd::OnCommand()
CWnd::OnWndMsg()
CWnd::WindowProc()
AfxCallWndProc()
AfxWndProc()
AfxWndProcBase()

About our authors: Team EQA

Further readings

Where is WinMain() function in MFC application ?

MFC hides WinMain in its framework and includes source file on WinMain(). This explains how framework calls global CWinApp::Initinstance() from entry WinMain.

What is the utility of CWinApp class?

This is constructed during global C++ objects are constructed and is already available when Windows calls the WinMain function, which is supplied by the ...

Basic steps in Win32 GUI Application with source code.

Define a custom Window class structure, Register the class name, CreateWindow, Show windows and write message get and dispatch loop statements. Define the Window CallBack procedure and write the handlers.

What is a Window CallBack procedure and what is its utility?

DispatchMessage() is a API which indirectly triggers the Window CallBack procedure. Message structure members from this function are passed to the CallBack procedure. CallBack procedure should implement event handlers depending on the need of the application.

What are LPARAM and WPARAM in window proc function?

LPARAM and WPARAM are the two parameters in Window CallBack procedure. They signifies parameters of various events. They are used in handing individual events.

What are the basic steps of a typical MFC based application?

We need to write WinMain and need to follow all these in a Win32 application. However we need not to write much if we are writing an application with MFC ...

‹ # ›

Questions index C Questions C++ Questions Win32 MFC COM/DCOM DLL Questions