CCmdTarget 類別

Microsoft Foundation Class Library 訊息對應架構的基類。

語法

class CCmdTarget : public CObject

成員

公用建構函式

名稱	描述
CCmdTarget::CCmdTarget	建構 CCmdTarget 物件。

公用方法

名稱	描述
CCmdTarget::BeginWaitCursor	將游標顯示為沙漏游標。
CCmdTarget::DoOleVerb	導致執行 OLE 動詞指定的動作。
CCmdTarget::EnableAutomation	允許物件的 CCmdTarget OLE 自動化。
CCmdTarget::EnableConnections	啟用透過連接點引發事件。
CCmdTarget::EnableTypeLib	啟用物件的類型程式庫。
CCmdTarget::EndWaitCursor	傳回至上一個資料指標。
CCmdTarget::EnumOleVerbs	列舉物件的 OLE 動詞。
CCmdTarget::FromIDispatch	傳回與指標相關聯 IDispatch 之物件的指標 CCmdTarget 。
CCmdTarget::GetDispatchIID	取得主要分派介面識別碼。
CCmdTarget::GetIDispatch	傳回與 CCmdTarget 物件相關聯之物件的指標 IDispatch 。
CCmdTarget::GetTypeInfoCount	擷取物件提供的類型資訊介面數目。
CCmdTarget::GetTypeInfoOfGuid	擷取對應至指定 GUID 的類型描述。
CCmdTarget::GetTypeLib	取得類型程式庫的指標。
CCmdTarget::GetTypeLibCache	取得類型程式庫快取。
CCmdTarget::IsInvokeAllowed	啟用自動化方法調用。
CCmdTarget::IsResultExpected	如果自動化函式應該傳回值，則傳回非零值。
CCmdTarget::OnCmdMsg	路由和分派命令訊息。
CCmdTarget::OnFinalRelease	在發行最後一個 OLE 參考之後清除。
CCmdTarget::RestoreWaitCursor	還原沙漏游標。

備註

訊息對應會將命令或訊息路由傳送至您撰寫以處理它們的成員函式。 （命令是來自功能表項目、命令按鈕或快速鍵的訊息。

衍生自 CCmdTarget 的主要架構類別包括 CView 、、 CWinAppCDocument 、 CWnd 、 和 CFrameWnd 。 如果您想要讓新類別處理訊息，請從下列 CCmdTarget 其中一個衍生類別衍生類別衍生類別。 您很少會直接從 衍生 CCmdTarget 類別。

如需命令目標和路由的概觀，請參閱命令目標 OnCmdMsg 、 命令路由 和 對應訊息 。

CCmdTarget 包含處理沙漏游標顯示的成員函式。 當您預期命令需要有明顯的時間間隔來執行時，顯示沙漏游標。

分派對應，類似于訊息對應，可用來公開 OLE 自動化 IDispatch 功能。 藉由公開此介面，其他應用程式 （例如 Visual Basic） 可以呼叫您的應用程式。

繼承階層架構

CObject

CCmdTarget

需求

標頭：afxwin.h

CCmdTarget::BeginWaitCursor

呼叫此函式，當您預期命令需要明顯時間間隔來執行時，將游標顯示為沙漏。

void BeginWaitCursor();

備註

架構會呼叫此函式來向使用者顯示它忙碌，例如物件載入或儲存到檔案時 CDocument 。

的 BeginWaitCursor 動作不一定會在單一訊息處理常式之外生效，因為其他動作，例如 OnSetCursor 處理，可能會變更資料指標。

呼叫 EndWaitCursor 以還原先前的資料指標。

範例

// 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

建構 CCmdTarget 物件。

CCmdTarget();

CCmdTarget::DoOleVerb

導致執行 OLE 動詞指定的動作。

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

參數

iVerb
動詞的數值識別碼。

lpMsg
MSG描述叫用動詞之事件的結構指標（例如按兩下）。

hWndParent
文件視窗的控制代碼，包含物件。

lpRect
結構指標 RECT ，包含座標，以圖元為單位，以圖元為單位，定義 物件的周框 hWndParent 。

傳回值

TRUE 如果成功，則為 ，否則 FALSE 為 。

備註

這個成員函式基本上是 的實作 IOleObject::DoVerb 。 可能的動作是由 列舉 CCmdTarget::EnumOleVerbs 。

CCmdTarget::EnableAutomation

呼叫此函式以啟用 物件的 OLE 自動化。

void EnableAutomation();

備註

此函式通常是從物件的建構函式呼叫，只有在已為 類別宣告分派對應時，才應該呼叫。 如需自動化的詳細資訊，請參閱自動化用戶端和 自動化伺服器 一文 。

CCmdTarget::EnableConnections

啟用透過連接點引發事件。

void EnableConnections();

備註

若要啟用連接點，請在衍生類別的建構函式中呼叫這個成員函式。

CCmdTarget::EnableTypeLib

啟用物件的類型程式庫。

void EnableTypeLib();

備註

如果衍生物件的建構函式提供類型資訊，請在衍生物件的建構 CCmdTarget 函式中呼叫這個成員函式。

CCmdTarget::EndWaitCursor

呼叫成員函式之後 BeginWaitCursor 呼叫此函式，以從沙漏游標傳回至上一個資料指標。

void EndWaitCursor();

備註

架構也會在呼叫沙漏游標之後呼叫這個成員函式。

範例

// 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

列舉物件的 OLE 動詞。

BOOL EnumOleVerbs(LPENUMOLEVERB* ppenumOleVerb);

參數

ppenumOleVerb
介面指標的 IEnumOLEVERB 指標。

傳回值

TRUE 如果物件至少支援一個 OLE 動詞，則 *ppenumOleVerbIEnumOLEVERB 為 ，否則 FALSE 為 。

備註

這個成員函式基本上是 的實作 IOleObject::EnumVerbs 。

CCmdTarget::FromIDispatch

呼叫此函式，將從 類別的自動化成員函式接收的指標對應 IDispatch 至 CCmdTarget 實作 物件介面的物件 IDispatch 。

static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);

參數

lpDispatch
IDispatch 物件的指標。

傳回值

與 lpDispatch 相關聯之 CCmdTarget 物件的指標。 如果物件無法辨識為 Microsoft Foundation Class IDispatch 物件， IDispatch 則此函式會傳回 NULL 。

備註

此函式的結果是成員函 GetIDispatch 式 的反向呼叫。

CCmdTarget::GetDispatchIID

取得主要分派介面識別碼。

virtual BOOL GetDispatchIID(IID* pIID);

參數

pIID
介面識別碼的指標（ GUID ）。

傳回值

TRUE 如果成功，則為 ，否則 FALSE 為 。 如果成功， *pIID 則會設定為主要分派介面識別碼。

備註

衍生類別應該覆寫這個成員函式（如果未覆寫， GetDispatchIID 則傳 FALSE 回 ）。 請參閱 COleControl。

CCmdTarget::GetIDispatch

呼叫這個成員函式，從 IDispatch 傳回 IDispatch 指標或依參考取得 IDispatch 指標的自動化方法擷取指標。

LPDISPATCH GetIDispatch(BOOL bAddRef);

參數

bAddRef
指定是否要遞增 物件的參考計數。

傳回值

與 IDispatch 物件相關聯的指標。

備註

對於在其建構函式中呼叫 EnableAutomation 的物件，啟用自動化，此函式會傳回透過 介面通訊 IDispatch 之用戶端所使用的 Foundation Class 實 IDispatch 作指標。 呼叫此函式會自動新增指標的參考，因此不需要呼叫 IUnknown::AddRef 。

CCmdTarget::GetTypeInfoCount

擷取物件提供的類型資訊介面數目。

virtual UINT GetTypeInfoCount();

傳回值

類型資訊介面的數目。

備註

這個成員函式基本上會實作 IDispatch::GetTypeInfoCount 。

衍生類別應該覆寫此函式，以傳回所提供的類型資訊介面數目（0 或 1）。 如果未覆寫， GetTypeInfoCount 則傳回 0。 若要覆寫，請使用 IMPLEMENT_OLETYPELIB 宏，這個宏也會實作 GetTypeLib 和 GetTypeLibCache 。

CCmdTarget::GetTypeInfoOfGuid

擷取對應至指定 GUID 的類型描述。

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

參數

lcid
地區設定識別碼 （ LCID ）。

guid
型別描述的 GUID 。

ppTypeInfo
介面指標的 ITypeInfo 指標。

傳回值

HRESULT，表示呼叫成功或失敗。 如果成功， *ppTypeInfo 請指向類型資訊介面。

CCmdTarget::GetTypeLib

取得類型程式庫的指標。

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

參數

lcid
地區設定識別項 (LCID)。

ppTypeLib
介面指標的 ITypeLib 指標。

傳回值

HRESULT，表示呼叫成功或失敗。 如果成功， *ppTypeLib 請指向類型程式庫介面。

備註

衍生類別應該覆寫這個成員函式（如果未覆寫， GetTypeLib 則傳 TYPE_E_CANTLOADLIBRARY 回 ）。 使用 宏 IMPLEMENT_OLETYPELIB ，其也會實作 GetTypeInfoCount 和 GetTypeLibCache 。

CCmdTarget::GetTypeLibCache

取得類型程式庫快取。

virtual CTypeLibCache* GetTypeLibCache();

傳回值

CTypeLibCache 物件的指標。

備註

衍生類別應該覆寫這個成員函式（如果未覆寫， GetTypeLibCache 則傳 NULL 回 ）。 使用 宏 IMPLEMENT_OLETYPELIB ，其也會實作 GetTypeInfoCount 和 GetTypeLib 。

CCmdTarget::IsInvokeAllowed

MFC 的 實 IDispatch::Invoke 作會呼叫此函式，以判斷是否可以叫用指定的自動化方法（由 dispid 識別）。

virtual BOOL IsInvokeAllowed(DISPID dispid);

參數

dispid
分派識別碼。

傳回值

TRUE 如果可以叫用 方法，則為 ，否則 FALSE 為 。

備註

如果 IsInvokeAllowed 傳 TRUE 回 ， Invoke 則會繼續呼叫 方法，否則 Invoke 會失敗，並傳 E_UNEXPECTED 回 。

衍生類別可以覆寫此函式以傳回適當的值（如果未覆寫， IsInvokeAllowed 則傳 TRUE 回 ）。 請參閱特別是 COleControl::IsInvokeAllowed 。

CCmdTarget：：IsResultExpected

使用 IsResultExpected 來確認用戶端是否預期從對自動化函式的呼叫傳回值。

BOOL IsResultExpected();

傳回值

如果自動化函式應該傳回值，則為非零;否則為 0。

備註

OLE 介面會提供 MFC 的相關資訊，說明用戶端是使用還是忽略函式呼叫的結果，而 MFC 則會使用這項資訊來判斷 呼叫 IsResultExpected 的結果。 如果傳回值的生產時間或資源密集，您可以在計算傳回值之前呼叫此函式來提高效率。

如果您從用戶端已呼叫的自動化函式呼叫這些函式，此函式只會傳回 0 次，以便從用戶端呼叫的自動化函式取得有效的傳回值。

IsResultExpected 如果自動化函式呼叫未進行中，則會傳回非零值。

CCmdTarget::OnCmdMsg

由架構呼叫以路由和分派命令訊息，以及處理命令使用者介面物件的更新。

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

參數

nID
包含命令識別碼。

nCode
識別命令通知程式碼。 如需 值的詳細資訊 nCode ，請參閱 < 備註>。

pExtra
根據 的值 nCode 使用。 如需 的詳細資訊，請參閱 。 pExtra

pHandlerInfo
如果不是 NULL ， OnCmdMsg 則填入 pTarget 結構的 和 pmf 成員 pHandlerInfo ，而不是分派命令。 一般而言，此參數應該是 NULL 。

傳回值

如果處理訊息，則為非零;否則為 0。

備註

這是架構命令架構的主要實作常式。

在執行時間， OnCmdMsg 呼叫根類別 CCmdTarget::OnCmdMsg ，以執行實際的訊息對應查閱，將命令分派給其他物件或處理命令本身。 如需預設命令路由的完整描述，請參閱 訊息處理和對應主題 。

有時候，您可能想要覆寫此成員函式來擴充架構的標準命令路由。 如需 命令路由架構的進階詳細資料，請參閱 Technical Note 21 。

如果您覆寫 OnCmdMsg ，則必須為 提供適當的值 nCode 、命令通知程式碼和 pExtra ，視 的值 nCode 而定。 下表列出其對應的值：

nCode 值	pExtra 值
CN_COMMAND	CCmdUI*
CN_EVENT	AFX_EVENT*
CN_UPDATE_COMMAND_UI	CCmdUI*
CN_OLECOMMAND	COleCmdUI*
CN_OLE_UNREGISTER	NULL

範例

// 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

在釋放物件的最後一個 OLE 參考時，由架構呼叫。

virtual void OnFinalRelease();

備註

覆寫此函式以提供此情況的特殊處理。 預設實作會刪除 物件。

CCmdTarget::RestoreWaitCursor

呼叫此函式，以在系統游標變更之後還原適當的沙漏游標（例如，在長時間作業的中間開啟訊息方塊後再關閉）。

void RestoreWaitCursor();

範例

// 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
}

另請參閱

MFC 範例 ACDUAL
CObject 類
階層架構圖表
CCmdUI 類
CDocument 類
CDocTemplate 類
CWinApp 類
CWnd 類
CView 類
CFrameWnd 類
COleDispatchDriver 類