Partager via

CCmdTarget::OnCmdMsg

  • Article

Called by the framework to route and dispatch command messages and to handle the update of command user-interface objects.

virtual BOOL OnCmdMsg(
   UINT nID,
   int nCode,
   void* pExtra,
   AFX_CMDHANDLERINFO* pHandlerInfo 
);

Parameters

  • nID
    Contains the command ID.

  • nCode
    Identifies the command notification code. See Remarks for more information about values for nCode.

  • pExtra
    Used according to the value of nCode. See Remarks for more information about pExtra.

  • pHandlerInfo
    If not NULL, OnCmdMsg fills in the pTarget and pmf members of the pHandlerInfo structure instead of dispatching the command. Typically, this parameter should be NULL.

Return Value

Nonzero if the message is handled; otherwise 0.

Remarks

This is the main implementation routine of the framework command architecture.

At run time, OnCmdMsg dispatches a command to other objects or handles the command itself by calling the root class CCmdTarget::OnCmdMsg, which does the actual message-map lookup. For a complete description of the default command routing, see Message Handling and Mapping Topics.

On rare occasions, you may want to override this member function to extend the framework's standard command routing. Refer to Technical Note 21 for advanced details of the command-routing architecture.

If you override OnCmdMsg, you must supply the appropriate value for nCode, the command notification code, and pExtra, which depends on the value of nCode. The following table lists their corresponding values:

nCode value

pExtra value

CN_COMMAND

CCmdUI*

CN_EVENT

AFX_EVENT*

CN_UPDATE_COMMAND_UI

CCmdUI*

CN_OLECOMMAND

COleCmdUI*

CN_OLE_UNREGISTER

NULL

Example

// This example illustrates extending the framework's standard command 
// route from the view to objects managed by the view.  This example
// is from an object-oriented drawing application, similar to the
// DRAWCLI sample application, which draws and edits "shapes".
BOOL CMyView::OnCmdMsg(UINT nID, int nCode, void* pExtra, AFX_CMDHANDLERINFO* pHandlerInfo)
{
   // Extend the framework's command route from the view to
   // the application-specific CMyShape that is currently selected
   // in the view. m_pActiveShape is NULL if no shape object
   // is currently selected in the view.
   if ((m_pActiveShape != NULL)
      && m_pActiveShape->OnCmdMsg(nID, nCode, pExtra, pHandlerInfo))
      return TRUE;

   // If the object(s) in the extended command route don't handle
   // the command, then let the base class OnCmdMsg handle it.
   return CView::OnCmdMsg(nID, nCode, pExtra, pHandlerInfo);
}

// The command handler for ID_SHAPE_COLOR (menu command to change
// the color of the currently selected shape) was added to the message
// map of CMyShape (note, not CMyView) using the Properties window.  
// The menu item will be automatically enabled or disabled, depending 
// on whether a CMyShape is currently selected in the view, that is, 
// depending on whether CMyView::m_pActiveView is NULL.  It is not 
// necessary to implement an ON_UPDATE_COMMAND_UI handler to enable 
// or disable the menu item.  
BEGIN_MESSAGE_MAP(CMyShape, CCmdTarget)
   ON_COMMAND(ID_SHAPE_COLOR, &CMyShape::OnShapeColor)
END_MESSAGE_MAP()

Requirements

Header: afxwin.h

See Also

Reference

CCmdTarget Class

Hierarchy Chart

CCmdUI Class

COleCmdUI Class

Other Resources

CCmdTarget Members

Change History

Date

History

Reason

June 2010

Fixed error in table heading.

Customer feedback.