| description | title | ms.date | f1_keywords | helpviewer_keywords | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CCmdTarget Class |
CCmdTarget Class |
11/04/2016 |
|
|
The base class for the Microsoft Foundation Class Library message-map architecture.
class CCmdTarget : public CObject
| Name | Description |
|---|---|
CCmdTarget::CCmdTarget |
Constructs a CCmdTarget object. |
| 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. |
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.
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();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.
[!code-cppNVC_MFCDocView#43]
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);
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.
TRUE if successful, otherwise FALSE.
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();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();To enable connection points, call this member function in the constructor of your derived class.
Enables an object's type library.
void EnableTypeLib();Call this member function in the constructor of your CCmdTarget-derived object if it provides type information.
Call this function after you've called the BeginWaitCursor member function to return from the hourglass cursor to the previous cursor.
void EndWaitCursor();The framework also calls this member function after it has called the hourglass cursor.
[!code-cppNVC_MFCDocView#43]
Enumerates an object's OLE verbs.
BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb);
ppenumOleVerb
A pointer to a pointer to an IEnumOLEVERB interface.
TRUE if the object supports at least one OLE verb (in which case *ppenumOleVerb points to an IEnumOLEVERB enumerator interface), otherwise FALSE.
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);
lpDispatch
A pointer to an IDispatch object.
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.
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);
pIID
A pointer to an interface ID (a GUID).
TRUE if successful, otherwise FALSE. If successful, *pIID is set to the primary dispatch interface ID.
Derived classes should override this member function (if not overridden, GetDispatchIID returns FALSE). See COleControl.
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);
bAddRef
Specifies whether to increment the reference count for the object.
The IDispatch pointer associated with the object.
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.
Retrieves the number of type information interfaces that an object provides.
virtual UINT GetTypeInfoCount();
The number of type information interfaces.
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);
lcid
A locale identifier ( LCID).
guid
The GUID of the type description.
ppTypeInfo
Pointer to a pointer to the ITypeInfo interface.
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);
lcid
A locale identifier (LCID).
ppTypeLib
A pointer to a pointer to the ITypeLib interface.
An HRESULT indicating the success or failure of the call. If successful, *ppTypeLib points to the type library interface.
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();
A pointer to a CTypeLibCache object.
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);
dispid
A dispatch ID.
TRUE if the method can be invoked, otherwise FALSE.
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();
Nonzero if an automation function should return a value; otherwise 0.
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.
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);
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.
Nonzero if the message is handled; otherwise 0.
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 |
[!code-cppNVC_MFCDocView#44] [!code-cppNVC_MFCDocView#45]
Called by the framework when the last OLE reference to or from the object is released.
virtual void OnFinalRelease();
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();[!code-cppNVC_MFCDocView#43]
MFC Sample ACDUAL
CObject Class
Hierarchy Chart
CCmdUI Class
CDocument Class
CDocTemplate Class
CWinApp Class
CWnd Class
CView Class
CFrameWnd Class
COleDispatchDriver Class