CCmdTarget Class

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CCmdTarget Class.

The base class for the Microsoft Foundation Class Library message-map architecture.

Syntax

class CCmdTarget : public CObject

Members

Public Constructors

Name	Description
CCmdTarget::CCmdTarget	Constructs a `CCmdTarget` object.

Public Methods

Name	Description
CCmdTarget::BeginWaitCursor	Displays the cursor as an hourglass cursor.
CCmdTarget::DoOleVerb	Causes an action specified by an OLE verb to be performed.
CCmdTarget::EnableAutomation	Allows OLE automation for the `CCmdTarget` object.
CCmdTarget::EnableConnections	Enables event firing over connection points.
CCmdTarget::EnableTypeLib	Enables an object's type library.
CCmdTarget::EndWaitCursor	Returns to the previous cursor.
CCmdTarget::EnumOleVerbs	Enumerates an object's OLE verbs.
CCmdTarget::FromIDispatch	Returns a pointer to the `CCmdTarget` object associated with the `IDispatch` pointer.
CCmdTarget::GetDispatchIID	Gets the primary dispatch interface ID.
CCmdTarget::GetIDispatch	Returns a pointer to the `IDispatch` object associated with the `CCmdTarget` object.
CCmdTarget::GetTypeInfoCount	Retrieves the number of type information interfaces that an object provides.
CCmdTarget::GetTypeInfoOfGuid	Retrieves the type description that corresponds to the specified GUID.
CCmdTarget::GetTypeLib	Gets a pointer to a type library.
CCmdTarget::GetTypeLibCache	Gets the type library cache.
CCmdTarget::IsInvokeAllowed	Enables automation method invocation.
CCmdTarget::IsResultExpected	Returns nonzero if an automation function should return a value.
CCmdTarget::OnCmdMsg	Routes and dispatches command messages.
CCmdTarget::OnFinalRelease	Cleans up after the last OLE reference is released.
CCmdTarget::RestoreWaitCursor	Restores the hourglass cursor.

Remarks

A message map routes commands or messages to the member functions you write to handle them. (A command is a message from a menu item, command button, or accelerator key.)

Key framework classes derived from CCmdTarget include CView, CWinApp, CDocument, CWnd, and CFrameWnd. If you intend for a new class to handle messages, derive the class from one of these CCmdTarget-derived classes. You will rarely derive a class from CCmdTarget directly.

For an overview of command targets and OnCmdMsg routing, see Command Targets, Command Routing, and Mapping Messages.

CCmdTarget includes member functions that handle the display of an hourglass cursor. Display the hourglass cursor when you expect a command to take a noticeable time interval to execute.

Dispatch maps, similar to message maps, are used to expose OLE automation IDispatch functionality. By exposing this interface, other applications (such as Visual Basic) can call into your application.

Inheritance Hierarchy

CObject

CCmdTarget

Requirements

Header: afxwin.h

CCmdTarget::BeginWaitCursor

Call this function to display the cursor as an hourglass when you expect a command to take a noticeable time interval to execute.

void BeginWaitCursor();

Remarks

The framework calls this function to show the user that it is busy, such as when a CDocument object loads or saves itself to a file.

The actions of BeginWaitCursor are not always effective outside of a single message handler as other actions, such as OnSetCursor handling, could change the cursor.

Call EndWaitCursor to restore the previous cursor.

Example

// The following example illustrates the most common case
// of displaying the hourglass cursor during some lengthy
// processing of a command handler implemented in some
// CCmdTarget-derived class, such as a document or view.
void CMyView::OnBeginSleepEnd()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// The next example illustrates RestoreWaitCursor.
void CMyView::OnBeginDlgRestore()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   // The dialog box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the dialog box is
   // closed.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call RestoreWaitCursor here in order
   // to change the cursor back to the hourglass cursor.
   RestoreWaitCursor();
   // do some more lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// In the above example, the dialog was clearly invoked between
// the pair of calls to BeginWaitCursor and EndWaitCursor.
// Sometimes it may not be clear whether the dialog is invoked 
// in between a pair of calls to BeginWaitCursor and EndWaitCursor.
// It is permissable to call RestoreWaitCursor, even if 
// BeginWaitCursor was not previously called.  This case is 
// illustrated below, where CMyView::AnotherFunction does not
// need to know whether it was called in the context of an
// hourglass cursor.
void CMyView::OnDlgRestore()
{
   // some processing ...
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   RestoreWaitCursor();

   // some more processing ...
}

// If the dialog is invoked from a member function of
// some non-CCmdTarget, then you can call CWinApp::DoWaitCursor
// with a 0 parameter value to restore the hourglass cursor.
void CMyObject::OnDlgDoWait()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   AfxGetApp()->DoWaitCursor(0); // same as CCmdTarget::RestoreWaitCursor   
}

CCmdTarget::CCmdTarget

Constructs a CCmdTarget object.

CCmdTarget();

CCmdTarget::DoOleVerb

Causes an action specified by an OLE verb to be performed.

BOOL DoOleVerb(
    LONG iVerb,  
    LPMSG lpMsg,  
    HWND hWndParent,  
    LPCRECT lpRect);

Parameters

iVerb
Numerical identifier of the verb.

lpMsg
Pointer to the MSG structure describing the event (such as a double-click) that invoked the verb.

hWndParent
Handle of the document window containing the object.

lpRect
Pointer to the RECT structure containing the coordinates, in pixels, that define an object's bounding rectangle in hwndParent.

Return Value

TRUE if successful, otherwise FALSE.

Remarks

This member function is basically an implementation of IOleObject::DoVerb. The possible actions are enumerated by CCmdTarget::EnumOleVerbs.

CCmdTarget::EnableAutomation

Call this function to enable OLE automation for an object.

void EnableAutomation();

Remarks

This function is typically called from the constructor of your object and should only be called if a dispatch map has been declared for the class. For more information on automation see the articles Automation Clients and Automation Servers.

CCmdTarget::EnableConnections

Enables event firing over connection points.

void EnableConnections();

Remarks

To enable connection points, call this member function in the constructor of your derived class.

CCmdTarget::EnableTypeLib

Enables an object's type library.

void EnableTypeLib();

Remarks

Call this member function in the constructor of your CCmdTarget-derived object if it provides type information. For more information, see Knowledge Base article Q185720, "HOWTO: Provide Type Information From an MFC Automation Server." Knowledge Base articles are available in the MSDN Library Visual Studio documentation or at https://support.microsoft.com.

CCmdTarget::EndWaitCursor

Call this function after you have called the BeginWaitCursor member function to return from the hourglass cursor to the previous cursor.

void EndWaitCursor();

Remarks

The framework also calls this member function after it has called the hourglass cursor.

Example

// The following example illustrates the most common case
// of displaying the hourglass cursor during some lengthy
// processing of a command handler implemented in some
// CCmdTarget-derived class, such as a document or view.
void CMyView::OnBeginSleepEnd()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// The next example illustrates RestoreWaitCursor.
void CMyView::OnBeginDlgRestore()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   // The dialog box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the dialog box is
   // closed.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call RestoreWaitCursor here in order
   // to change the cursor back to the hourglass cursor.
   RestoreWaitCursor();
   // do some more lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// In the above example, the dialog was clearly invoked between
// the pair of calls to BeginWaitCursor and EndWaitCursor.
// Sometimes it may not be clear whether the dialog is invoked 
// in between a pair of calls to BeginWaitCursor and EndWaitCursor.
// It is permissable to call RestoreWaitCursor, even if 
// BeginWaitCursor was not previously called.  This case is 
// illustrated below, where CMyView::AnotherFunction does not
// need to know whether it was called in the context of an
// hourglass cursor.
void CMyView::OnDlgRestore()
{
   // some processing ...
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   RestoreWaitCursor();

   // some more processing ...
}

// If the dialog is invoked from a member function of
// some non-CCmdTarget, then you can call CWinApp::DoWaitCursor
// with a 0 parameter value to restore the hourglass cursor.
void CMyObject::OnDlgDoWait()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   AfxGetApp()->DoWaitCursor(0); // same as CCmdTarget::RestoreWaitCursor   
}

CCmdTarget::EnumOleVerbs

Enumerates an object's OLE verbs.

BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb);

Parameters

ppenumOleVerb
A pointer to a pointer to an IEnumOLEVERB interface.

Return Value

TRUE if the object supports at least one OLE verb (in which case * ppenumOleVerb points to an IEnumOLEVERB enumerator interface), otherwise FALSE.

Remarks

This member function is basically an implementation of IOleObject::EnumVerbs.

CCmdTarget::FromIDispatch

Call this function to map an IDispatch pointer, received from automation member functions of a class, into the CCmdTarget object that implements the interfaces of the IDispatch object.

static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);

Parameters

lpDispatch
A pointer to an IDispatch object.

Return Value

A pointer to the CCmdTarget object associated with lpDispatch. This function returns NULL if the IDispatch object is not recognized as a Microsoft Foundation Class IDispatch object.

Remarks

The result of this function is the inverse of a call to the member function GetIDispatch.

CCmdTarget::GetDispatchIID

Gets the primary dispatch interface ID.

virtual BOOL GetDispatchIID(IID* pIID);

Parameters

pIID
A pointer to an interface ID (a GUID).

Return Value

TRUE if successful, otherwise FALSE. If successful, * pIID is set to the primary dispatch interface ID.

Remarks

Derived classes should override this member function (if not overridden, GetDispatchIID returns FALSE). See COleControl.

For more information, see Knowledge Base article Q185720, "HOWTO: Provide Type Information From an MFC Automation Server." Knowledge Base articles are available in the MSDN Library Visual Studio documentation or at https://support.microsoft.com.

CCmdTarget::GetIDispatch

Call this member function to retrieve the IDispatch pointer from an automation method that either returns an IDispatch pointer or takes an IDispatch pointer by reference.

LPDISPATCH GetIDispatch(BOOL bAddRef);

Parameters

bAddRef
Specifies whether to increment the reference count for the object.

Return Value

The IDispatch pointer associated with the object.

Remarks

For objects that call EnableAutomation in their constructors, making them automation enabled, this function returns a pointer to the Foundation Class implementation of IDispatch that is used by clients who communicate via the IDispatch interface. Calling this function automatically adds a reference to the pointer, so it is not necessary to make a call to IUnknown::AddRef.

CCmdTarget::GetTypeInfoCount

Retrieves the number of type information interfaces that an object provides.

virtual UINT GetTypeInfoCount();

Return Value

The number of type information interfaces.

Remarks

This member function basically implements IDispatch::GetTypeInfoCount.

Derived classes should override this function to return the number of type information interfaces provided (either 0 or 1). If not overridden, GetTypeInfoCount returns 0. To override, use the IMPLEMENT_OLETYPELIB macro, which also implements GetTypeLib and GetTypeLibCache.

CCmdTarget::GetTypeInfoOfGuid

Retrieves the type description that corresponds to the specified GUID.

HRESULT GetTypeInfoOfGuid(
    LCID lcid,  
    const GUID& guid,  
    LPTYPEINFO* ppTypeInfo);

Parameters

lcid
A locale identifier ( LCID).

guid
The GUID of the type description.

ppTypeInfo
Pointer to a pointer to the ITypeInfo interface.

Return Value

An HRESULT indicating the success or failure of the call. If successful, * ppTypeInfo points to the type information interface.

CCmdTarget::GetTypeLib

Gets a pointer to a type library.

virtual HRESULT GetTypeLib(
    LCID lcid,  
    LPTYPELIB* ppTypeLib);

Parameters

lcid
A locale identifier ( LCID).

ppTypeLib
A pointer to a pointer to the ITypeLib interface.

Return Value

An HRESULT indicating the success or failure of the call. If successful, * ppTypeLib points to the type library interface.

Remarks

Derived classes should override this member function (if not overridden, GetTypeLib returns TYPE_E_CANTLOADLIBRARY). Use the IMPLEMENT_OLETYPELIB macro, which also implements GetTypeInfoCount and GetTypeLibCache.

CCmdTarget::GetTypeLibCache

Gets the type library cache.

virtual CTypeLibCache* GetTypeLibCache();

Return Value

A pointer to a CTypeLibCache object.

Remarks

Derived classes should override this member function (if not overridden, GetTypeLibCache returns NULL). Use the IMPLEMENT_OLETYPELIB macro, which also implements GetTypeInfoCount and GetTypeLib.

CCmdTarget::IsInvokeAllowed

This function is called by MFC's implementation of IDispatch::Invoke to determine if a given automation method (identified by dispid) can be invoked.

virtual BOOL IsInvokeAllowed(DISPID dispid);

Parameters

dispid
A dispatch ID.

Return Value

TRUE if the method can be invoked, otherwise FALSE.

Remarks

If IsInvokeAllowed returns TRUE, Invoke proceeds to call the method; otherwise, Invoke will fail, returning E_UNEXPECTED.

Derived classes can override this function to return appropriate values (if not overridden, IsInvokeAllowed returns TRUE). See in particular COleControl::IsInvokeAllowed.

CCmdTarget::IsResultExpected

Use IsResultExpected to ascertain whether a client expects a return value from its call to an automation function.

BOOL IsResultExpected();

Return Value

Nonzero if an automation function should return a value; otherwise 0.

Remarks

The OLE interface supplies information to MFC about whether the client is using or ignoring the result of a function call, and MFC in turn uses this information to determine the result of a call to IsResultExpected. If production of a return value is time- or resource-intensive, you can increase efficiency by calling this function before computing the return value.

This function returns 0 only once so that you will get valid return values from other automation functions if you call them from the automation function that the client has called.

IsResultExpected returns a nonzero value if called when an automation function call is not in progress.

CCmdTarget::OnCmdMsg

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()

CCmdTarget::OnFinalRelease

Called by the framework when the last OLE reference to or from the object is released.

virtual void OnFinalRelease();

Remarks

Override this function to provide special handling for this situation. The default implementation deletes the object.

CCmdTarget::RestoreWaitCursor

Call this function to restore the appropriate hourglass cursor after the system cursor has changed (for example, after a message box has opened and then closed while in the middle of a lengthy operation).

void RestoreWaitCursor();

Example

// The following example illustrates the most common case
// of displaying the hourglass cursor during some lengthy
// processing of a command handler implemented in some
// CCmdTarget-derived class, such as a document or view.
void CMyView::OnBeginSleepEnd()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// The next example illustrates RestoreWaitCursor.
void CMyView::OnBeginDlgRestore()
{
   BeginWaitCursor(); // display the hourglass cursor
   // do some lengthy processing
   // The dialog box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the dialog box is
   // closed.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call RestoreWaitCursor here in order
   // to change the cursor back to the hourglass cursor.
   RestoreWaitCursor();
   // do some more lengthy processing
   Sleep(3000);
   EndWaitCursor(); // remove the hourglass cursor
}

// In the above example, the dialog was clearly invoked between
// the pair of calls to BeginWaitCursor and EndWaitCursor.
// Sometimes it may not be clear whether the dialog is invoked 
// in between a pair of calls to BeginWaitCursor and EndWaitCursor.
// It is permissable to call RestoreWaitCursor, even if 
// BeginWaitCursor was not previously called.  This case is 
// illustrated below, where CMyView::AnotherFunction does not
// need to know whether it was called in the context of an
// hourglass cursor.
void CMyView::OnDlgRestore()
{
   // some processing ...
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   RestoreWaitCursor();

   // some more processing ...
}

// If the dialog is invoked from a member function of
// some non-CCmdTarget, then you can call CWinApp::DoWaitCursor
// with a 0 parameter value to restore the hourglass cursor.
void CMyObject::OnDlgDoWait()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();
   AfxGetApp()->DoWaitCursor(0); // same as CCmdTarget::RestoreWaitCursor   
}

Share via

CCmdTarget Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CCmdTarget::BeginWaitCursor

Remarks

Example

CCmdTarget::CCmdTarget

CCmdTarget::DoOleVerb

Parameters

Return Value

Remarks

CCmdTarget::EnableAutomation

Remarks

CCmdTarget::EnableConnections

Remarks

CCmdTarget::EnableTypeLib

Remarks

CCmdTarget::EndWaitCursor

Remarks

Example

CCmdTarget::EnumOleVerbs

Parameters

Return Value

Remarks

CCmdTarget::FromIDispatch

Parameters

Return Value

Remarks

CCmdTarget::GetDispatchIID

Parameters

Return Value

Remarks

CCmdTarget::GetIDispatch

Parameters

Return Value

Remarks

CCmdTarget::GetTypeInfoCount

Return Value

Remarks

CCmdTarget::GetTypeInfoOfGuid

Parameters

Return Value

CCmdTarget::GetTypeLib

Parameters

Return Value

Remarks

CCmdTarget::GetTypeLibCache

Return Value

Remarks

CCmdTarget::IsInvokeAllowed

Parameters

Return Value

Remarks

CCmdTarget::IsResultExpected

Return Value

Remarks

CCmdTarget::OnCmdMsg

Parameters

Return Value

Remarks

Example

CCmdTarget::OnFinalRelease

Remarks

CCmdTarget::RestoreWaitCursor

Example

See Also

Additional resources