共用方式為


CCmdTarget 類別

Microsoft基礎類別庫訊息對應架構的基類。

語法

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、、CWndCFrameWnd。 如果您想要讓新類別處理訊息,請從下列 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

呼叫此函式,將從 類別的自動化成員函式接收的指針對應 IDispatchCCmdTarget 實作 物件介面的物件 IDispatch

static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);

參數

lpDispatch
IDispatch 物件的指標。

傳回值

lpDispatch相關聯之 CCmdTarget 物件的指標。 如果IDispatch物件無法辨識為 Microsoft Foundation Class 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 巨集,它也會實作 GetTypeLibGetTypeLibCache

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使用 巨集,其也會實作 GetTypeInfoCountGetTypeLibCache

CCmdTarget::GetTypeLibCache

取得類型連結庫快取。

virtual CTypeLibCache* GetTypeLibCache();

傳回值

CTypeLibCache 物件的指標。

備註

衍生類別應該覆寫這個成員函式(如果未覆寫, GetTypeLibCache 則傳 NULL回 )。 IMPLEMENT_OLETYPELIB使用 巨集,其也會實作 GetTypeInfoCountGetTypeLib

CCmdTarget::IsInvokeAllowed

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

virtual BOOL IsInvokeAllowed(DISPID dispid);

參數

dispid
分派標識碼。

傳回值

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

備註

如果 IsInvokeAllowedTRUE回 , 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
如果不是 NULLOnCmdMsg 則填入 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