`CCmdTarget` Class

Article
12/01/2022

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'll 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's busy, such as when a CDocument object loads or saves itself to a file.

The actions of BeginWaitCursor aren't 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 permissible 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.

`CCmdTarget::EndWaitCursor`

Call this function after you've 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 permissible 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 isn't 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.

`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 isn't 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'll 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 isn't 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 permissible 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 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

Feedback

Feedback

Additional resources

`CCmdTarget` Class

`CCmdTarget::BeginWaitCursor`

`CCmdTarget::CCmdTarget`

`CCmdTarget::DoOleVerb`

`CCmdTarget::EnableAutomation`

`CCmdTarget::EnableConnections`

`CCmdTarget::EnableTypeLib`

`CCmdTarget::EndWaitCursor`

`CCmdTarget::EnumOleVerbs`

`CCmdTarget::FromIDispatch`

`CCmdTarget::GetDispatchIID`

`CCmdTarget::GetIDispatch`

`CCmdTarget::GetTypeInfoCount`

`CCmdTarget::GetTypeInfoOfGuid`

`CCmdTarget::GetTypeLib`

`CCmdTarget::GetTypeLibCache`

`CCmdTarget::IsInvokeAllowed`

`CCmdTarget::OnCmdMsg`

`CCmdTarget::OnFinalRelease`

`CCmdTarget::RestoreWaitCursor`