CCmdTarget クラス

Microsoft Foundation クラス ライブラリのメッセージ マップ アーキテクチャの基本クラス。

構文

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	プライマリ ディスパッチ インターフェイス ID を取得します。
CCmdTarget::GetIDispatch	CCmdTarget オブジェクトに関連付けられているIDispatch オブジェクトへのポインターを返します。
CCmdTarget::GetTypeInfoCount	オブジェクトが提供する型情報インターフェイスの数を取得します。
CCmdTarget::GetTypeInfoOfGuid	指定した GUID に対応する型の説明を取得します。
CCmdTarget::GetTypeLib	タイプ ライブラリへのポインターを取得します。
CCmdTarget::GetTypeLibCache	タイプ ライブラリ キャッシュを取得します。
CCmdTarget::IsInvokeAllowed	オートメーション メソッドの呼び出しを有効にします。
CCmdTarget::IsResultExpected	オートメーション関数が値を返す必要がある場合は、0 以外の値を返します。
CCmdTarget::OnCmdMsg	コマンド メッセージをルーティングしてディスパッチします。
CCmdTarget::OnFinalRelease	最後の OLE 参照が解放された後でクリーンアップします。
CCmdTarget::RestoreWaitCursor	砂時計カーソルを復元します。

解説

メッセージ マップは、コマンドまたはメッセージを処理するために書き込むメンバー関数にルーティングします。 (コマンドは、メニュー項目、コマンド ボタン、またはアクセラレータ キーからのメッセージです)。

CCmdTargetから派生した主要なフレームワーク クラスには、CView、CWinApp、CDocument、CWnd、およびCFrameWndが含まれます。 新しいクラスでメッセージを処理する場合は、これらの CCmdTarget派生クラスの 1 つからクラスを派生させます。 CCmdTargetから直接クラスを派生することはめったにありません。

コマンド ターゲットと OnCmdMsg ルーティングの概要については、「 Command Targets、 Command Routing、および Mapping Messages」を参照してください。

CCmdTarget には、砂時計カーソルの表示を処理するメンバー関数が含まれています。 コマンドの実行に顕著な時間間隔が必要な場合は、砂時計カーソルを表示します。

ディスパッチ マップは、メッセージ マップと同様に、OLE オートメーション IDispatch 機能を公開するために使用されます。 このインターフェイスを公開することで、他のアプリケーション (Visual Basic など) がアプリケーションを呼び出すことができます。

継承階層

CObject

CCmdTarget

要件

ヘッダー: afxwin.h

CCmdTarget::BeginWaitCursor

コマンドの実行に顕著な時間間隔が必要な場合に、カーソルを砂時計として表示するには、この関数を呼び出します。

void BeginWaitCursor();

解説

フレームワークは、この関数を呼び出して、 CDocument オブジェクトが読み込まれたり、ファイルに保存されたりしたときなど、ビジーであることをユーザーに示します。

BeginWaitCursorのアクションは、1 つのメッセージ ハンドラーの外部で常に有効であるとは限りません。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
hWndParentでオブジェクトの外接する四角形を定義する座標 (ピクセル単位) を含むRECT構造体へのポインター。

戻り値

成功した場合は TRUE、それ以外の場合は FALSE。

解説

このメンバー関数は、基本的に IOleObject::DoVerbの実装です。 考えられるアクションは、 CCmdTarget::EnumOleVerbsによって列挙されます。

CCmdTarget::EnableAutomation

オブジェクトの OLE オートメーションを有効にするには、この関数を呼び出します。

void EnableAutomation();

解説

この関数は通常、オブジェクトのコンストラクターから呼び出され、クラスに対してディスパッチ マップが宣言されている場合にのみ呼び出す必要があります。 自動化の詳細については、「 Automation Clients および Automation Servers に関する記事を参照してください。

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 オブジェクトが少なくとも 1 つの OLE 動詞をサポートしている場合 (この場合 *ppenumOleVerb は IEnumOLEVERB 列挙子インターフェイスを指します)、それ以外の場合は FALSE。

解説

このメンバー関数は、基本的に IOleObject::EnumVerbsの実装です。

CCmdTarget::FromIDispatch

クラスのオートメーション メンバー関数から受け取ったIDispatch ポインターを、IDispatch オブジェクトのインターフェイスを実装するCCmdTarget オブジェクトにマップするには、この関数を呼び出します。

static CCmdTarget* PASCAL FromIDispatch(LPDISPATCH lpDispatch);

パラメーター

lpDispatch
IDispatch オブジェクトへのポインター。

戻り値

lpDispatchに関連付けられているCCmdTarget オブジェクトへのポインター。 この関数は、IDispatch オブジェクトが Microsoft Foundation Class IDispatch オブジェクトとして認識されない場合、NULLを返します。

解説

この関数の結果は、 GetIDispatchメンバー関数の呼び出しの逆です。

CCmdTarget::GetDispatchIID

プライマリ ディスパッチ インターフェイス ID を取得します。

virtual BOOL GetDispatchIID(IID* pIID);

パラメーター

pIID
インターフェイス ID ( GUID) へのポインター。

戻り値

成功した場合は TRUE、それ以外の場合は FALSE。 成功した場合、 *pIID はプライマリ ディスパッチ インターフェイス ID に設定されます。

解説

派生クラスは、このメンバー関数をオーバーライドする必要があります (オーバーライドされていない場合、 GetDispatchIID は FALSEを返します)。 以下を参照してください。COleControl

CCmdTarget::GetIDispatch

このメンバー関数を呼び出して、IDispatch ポインターを返すか、参照によってIDispatch ポインターを受け取るオートメーション メソッドからIDispatch ポインターを取得します。

LPDISPATCH GetIDispatch(BOOL bAddRef);

パラメーター

bAddRef
オブジェクトの参照カウントをインクリメントするかどうかを指定します。

戻り値

オブジェクトに関連付けられている IDispatch ポインター。

解説

コンストラクターでEnableAutomationを呼び出し、オートメーションを有効にするオブジェクトの場合、この関数は、IDispatch インターフェイス経由で通信するクライアントによって使用されるIDispatchの Foundation Class 実装へのポインターを返します。 この関数を呼び出すとポインターへの参照が自動的に追加されるため、 IUnknown::AddRefの呼び出しを行う必要はありません。

CCmdTarget::GetTypeInfoCount

オブジェクトが提供する型情報インターフェイスの数を取得します。

virtual UINT GetTypeInfoCount();

戻り値

型情報インターフェイスの数。

解説

このメンバー関数は、基本的に IDispatch::GetTypeInfoCountを実装します。

派生クラスは、指定された型情報インターフェイスの数 (0 または 1) を返すために、この関数をオーバーライドする必要があります。 オーバーライドされない場合、 GetTypeInfoCount は 0 を返します。 オーバーライドするには、GetTypeLibとGetTypeLibCacheも実装する IMPLEMENT_OLETYPELIB マクロを使用します。

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を返します)。 GetTypeInfoCountとGetTypeLibCacheも実装するIMPLEMENT_OLETYPELIB マクロを使用します。

CCmdTarget::GetTypeLibCache

タイプ ライブラリ キャッシュを取得します。

virtual CTypeLibCache* GetTypeLibCache();

戻り値

CTypeLibCache オブジェクトを指すポインターです。

解説

派生クラスは、このメンバー関数をオーバーライドする必要があります (オーバーライドされていない場合、 GetTypeLibCache は NULLを返します)。 GetTypeInfoCountとGetTypeLibも実装するIMPLEMENT_OLETYPELIB マクロを使用します。

CCmdTarget::IsInvokeAllowed

この関数は、MFC の IDispatch::Invoke の実装によって呼び出され、特定のオートメーション メソッド ( dispid で識別される) を呼び出すことができるかどうかを判断します。

virtual BOOL IsInvokeAllowed(DISPID dispid);

パラメーター

dispid
ディスパッチ ID。

戻り値

TRUE メソッドを呼び出すことができる場合は、それ以外の場合は FALSE。

解説

IsInvokeAllowedがTRUEを返した場合、Invokeはメソッドの呼び出しに進みます。それ以外の場合、Invokeは失敗し、E_UNEXPECTEDが返されます。

派生クラスは、この関数をオーバーライドして適切な値を返すことができます (オーバーライドされていない場合、 IsInvokeAllowed は TRUEを返します)。 特に COleControl::IsInvokeAllowedを参照してください。

CCmdTarget::IsResultExpected

IsResultExpectedを使用して、クライアントがオートメーション関数の呼び出しからの戻り値を期待しているかどうかを確認します。

BOOL IsResultExpected();

戻り値

オートメーション関数が値を返す必要がある場合は 0 以外。それ以外の場合は 0。

解説

OLE インターフェイスは、クライアントが関数呼び出しの結果を使用しているか無視しているかに関する情報を MFC に提供し、MFC はこの情報を使用して、 IsResultExpectedの呼び出しの結果を判断します。 戻り値の生成が時間またはリソースを大量に消費する場合は、戻り値を計算する前にこの関数を呼び出すことで効率を高めることができます。

この関数は 1 回だけ 0 を返し、クライアントが呼び出したオートメーション関数から呼び出すと、他のオートメーション関数から有効な戻り値を取得します。

IsResultExpected は、オートメーション関数の呼び出しが進行中でないときに呼び出された場合、0 以外の値を返します。

CCmdTarget::OnCmdMsg

コマンド メッセージをルーティングおよびディスパッチし、コマンド ユーザー インターフェイス オブジェクトの更新を処理するために、フレームワークによって呼び出されます。

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

パラメーター

nID
コマンド ID を格納します。

nCode
コマンド通知コードを識別します。 nCodeの値の詳細については、「Remarksを参照してください。

pExtra
nCodeの値に従って使用されます。 pExtraの詳細については、「Remarks」を参照してください。

pHandlerInfo
NULLしない場合は、OnCmdMsgコマンドをディスパッチするのではなく、pHandlerInfo構造体のpTargetとpmfメンバーを入力します。 通常、このパラメーターは NULLする必要があります。

戻り値

メッセージが処理される場合は 0 以外。それ以外の場合は 0。

解説

これは、フレームワーク コマンド アーキテクチャの主要な実装ルーチンです。

実行時に、 OnCmdMsg は他のオブジェクトにコマンドをディスパッチするか、ルート クラス CCmdTarget::OnCmdMsgを呼び出してコマンド自体を処理します。これは、実際のメッセージ マップ検索を実行します。 既定のコマンド ルーティングの詳細については、「 Message の処理とマッピングに関するトピックを参照してください。

まれに、フレームワークの標準コマンド ルーティングを拡張するために、このメンバー関数をオーバーライドすることが必要になる場合があります。 コマンド ルーティング アーキテクチャの詳細については、 テクニカル ノート 21 を参照してください。

OnCmdMsgをオーバーライドする場合は、nCodeの値に応じて、nCode、コマンド通知コード、およびpExtraに適切な値を指定する必要があります。 次の表に、対応する値を示します。

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 クラス