CCmdTarget Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

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

class CCmdTarget : public CObject  

Public Constructors

NameDescription
CCmdTarget::CCmdTargetConstructs a CCmdTarget object.

Public Methods

NameDescription
CCmdTarget::BeginWaitCursorDisplays the cursor as an hourglass cursor.
CCmdTarget::DoOleVerbCauses an action specified by an OLE verb to be performed.
CCmdTarget::EnableAutomationAllows OLE automation for the CCmdTarget object.
CCmdTarget::EnableConnectionsEnables event firing over connection points.
CCmdTarget::EnableTypeLibEnables an object's type library.
CCmdTarget::EndWaitCursorReturns to the previous cursor.
CCmdTarget::EnumOleVerbsEnumerates an object's OLE verbs.
CCmdTarget::FromIDispatchReturns a pointer to the CCmdTarget object associated with the IDispatch pointer.
CCmdTarget::GetDispatchIIDGets the primary dispatch interface ID.
CCmdTarget::GetIDispatchReturns a pointer to the IDispatch object associated with the CCmdTarget object.
CCmdTarget::GetTypeInfoCountRetrieves the number of type information interfaces that an object provides.
CCmdTarget::GetTypeInfoOfGuidRetrieves the type description that corresponds to the specified GUID.
CCmdTarget::GetTypeLibGets a pointer to a type library.
CCmdTarget::GetTypeLibCacheGets the type library cache.
CCmdTarget::IsInvokeAllowedEnables automation method invocation.
CCmdTarget::IsResultExpectedReturns nonzero if an automation function should return a value.
CCmdTarget::OnCmdMsgRoutes and dispatches command messages.
CCmdTarget::OnFinalReleaseCleans up after the last OLE reference is released.
CCmdTarget::RestoreWaitCursorRestores the hourglass cursor.

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.

CObject

CCmdTarget

Header: afxwin.h

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   
}

Constructs a CCmdTarget object.

CCmdTarget();

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.

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.

Enables event firing over connection points.

void EnableConnections();

Remarks

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

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 http://support.microsoft.com.

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   
}

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.

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.

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 http://support.microsoft.com.

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.

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.

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.

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.

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.

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.

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.

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 valuepExtra value
CN_COMMANDCCmdUI*
CN_EVENTAFX_EVENT*
CN_UPDATE_COMMAND_UICCmdUI*
CN_OLECOMMANDCOleCmdUI*
CN_OLE_UNREGISTERNULL

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

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.

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   
}

MFC Sample ACDUAL
CObject Class
Hierarchy Chart
CCmdUI Class
CDocument Class
CDocTemplate Class
CWinApp Class
CWnd Class
CView Class
CFrameWnd Class
COleDispatchDriver Class

Show: