IContextMenu
COM公式ドキュメント
Shell オブジェクトに関連付けられたショートカットメニューを作成またはマージするためのメソッドを公開します。
解説(Remarks)
実装するタイミング
次のような状況で IContextMenu を実装します。- シェル拡張ハンドラーは、Shell オブジェクトのショートカットメニューに項目を動的に追加するためにこのインターフェイスを実装します。
- 名前空間拡張は、そのオブジェクトのショートカットメニューを指定するためにこのインターフェイスを実装します。
使用するタイミング
アプリケーションは、オブジェクトのショートカットメニュー内の項目に関する情報を取得したり、関連付けられたコマンドを呼び出したりするために IContextMenu を使用します。オブジェクトの IContextMenu インターフェイスを取得するには、アプリケーションはそのオブジェクトの IShellFolder::GetUIObjectOf メソッドを呼び出す必要があります。このインターフェイスをエクスポートするシェル拡張ハンドラーは、IShellExtInit もエクスポートする必要があります。詳細については、シェル拡張ハンドラーの作成を参照してください。
メソッド 3
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
ショートカットメニューにコマンドを追加します。
| hmenu | HMENU | in | ショートカットメニューへのハンドル。ハンドラーはメニュー項目を追加する際にこのハンドルを指定する必要があります。 |
| indexMenu | DWORD | in | 最初の新しいメニュー項目を挿入する 0 から始まる位置。 |
| idCmdFirst | DWORD | in | ハンドラーがメニュー項目識別子に指定できる最小値。 |
| idCmdLast | DWORD | in | ハンドラーがメニュー項目識別子に指定できる最大値。 |
| uFlags | DWORD | in | ショートカットメニューをどのように変更できるかを指定するオプションのフラグ。このパラメーターには、次の値の組み合わせを設定できます。下位ワードの残りのビットはシステムによって予約されています。上位ワードはコンテキスト固有の通信に使用できます。CMF_RESERVED 値は下位ワードをマスクするために使用できます。 CMF_NORMAL (0x00000000)0x00000000。通常の操作を示します。ショートカットメニュー拡張、名前空間拡張、またはドラッグアンドドロップハンドラーは、すべてのメニュー項目を追加できます。 CMF_DEFAULTONLY (0x00000001)0x00000001。ユーザーが、通常はダブルクリックによって既定のアクションをアクティブにしています。このフラグは、ショートカットメニュー拡張がメニュー内の既定の項目を変更しない場合には何も追加しないようにするためのヒントを提供します。ショートカットメニュー拡張またはドラッグアンドドロップハンドラーは、この値が指定されている場合、メニュー項目を追加すべきではありません。名前空間拡張は、多くても既定の項目のみを追加すべきです。 CMF_VERBSONLY (0x00000002)0x00000002。ショートカットメニューがショートカットファイル(通常は .lnk ファイル)のものです。ショートカットメニューハンドラーはこの値を無視すべきです。 CMF_EXPLORE (0x00000004)0x00000004。Windows エクスプローラーのツリーウィンドウが存在します。 CMF_NOVERBS (0x00000008)0x00000008。このフラグは 送る メニューに表示される項目に対して設定されます。ショートカットメニューハンドラーはこの値を無視すべきです。 CMF_CANRENAME (0x00000010)0x00000010。呼び出し元のアプリケーションが項目の名前変更をサポートしています。ショートカットメニューまたはドラッグアンドドロップハンドラーはこのフラグを無視すべきです。名前空間拡張は、該当する場合、メニューに 名前の変更 項目を追加すべきです。 CMF_NODEFAULT (0x00000020)0x00000020。メニュー内のどの項目も既定として設定されていません。ドラッグアンドドロップハンドラーはこのフラグを無視すべきです。名前空間拡張は、どのメニュー項目も既定として設定すべきではありません。 CMF_INCLUDESTATIC (0x00000040)この値は使用できません。 Windows Server 2003 および Windows XP: 0x00000040。静的メニューが構築されています。ブラウザーのみがこのフラグを使用すべきであり、その他のすべてのショートカットメニュー拡張は無視すべきです。 CMF_ITEMMENU (0x00000080)0x00000080。呼び出し元のアプリケーションが、(ビューの背景ではなく)ビュー内の項目に対してショートカットメニューを呼び出しています。 Windows Server 2003 および Windows XP: この値は使用できません。 CMF_EXTENDEDVERBS (0x00000100)0x00000100。呼び出し元のアプリケーションが拡張バーブを要求しています。通常のバーブは、ユーザーがオブジェクトを右クリックしたときに表示されます。拡張バーブを表示するには、ユーザーは Shift キーを押しながら右クリックする必要があります。 CMF_DISABLEDVERBS (0x00000200)0x00000200。呼び出し元のアプリケーションが、レガシメニューなど、無効化されたバーブを呼び出すことを意図しています。 Windows Server 2003 および Windows XP: この値は使用できません。 CMF_ASYNCVERBSTATE (0x00000400)0x00000400。バーブの状態を非同期に評価できます。 Windows Server 2008、Windows Vista、Windows Server 2003 および Windows XP: この値は使用できません。 CMF_OPTIMIZEFORINVOKE (0x00000800)0x00000800。正規のバーブ名を通じたバーブの呼び出しをサポートしないコンテキストメニューハンドラーに対して、その実装内で IContextMenu::QueryContextMenu をバイパスするよう通知します。 Windows Server 2008、Windows Vista、Windows Server 2003 および Windows XP: この値は使用できません。 CMF_SYNCCASCADEMENU (0x00001000)0x00001000。サブメニューを同期的に生成します。 Windows Server 2008、Windows Vista、Windows Server 2003 および Windows XP: この値は使用できません。 CMF_DONOTPICKDEFAULT (0x00002000)0x00002000。バーブが明示的に指定されていない場合に、その代わりに既定のバーブを使用しません。 Windows Server 2008、Windows Vista、Windows Server 2003 および Windows XP: この値は使用できません。 CMF_RESERVED (0xffff0000)0xffff0000。このフラグは、使用すべきでないすべてのビットを指定するビットマスクです。これはマスクとしてのみ使用します。パラメーター値として渡さないでください。 |
戻り値
型: HRESULT
成功した場合、重大度値が SEVERITY_SUCCESS に設定され、コード値が割り当てられた最大のコマンド識別子のオフセットに 1 を加えた値に設定された HRESULT 値を返します。たとえば、idCmdFirst が 5 に設定されており、コマンド識別子 5、7、8 の 3 つの項目をメニューに追加した場合、戻り値は MAKE_HRESULT(SEVERITY_SUCCESS, 0, 8 - 5 + 1) となります。それ以外の場合は、COM エラー値を返します。
解説(Remarks)
このメソッドは、hmenu で指定されたメニューにメニュー項目を挿入するために、InsertMenu または InsertMenuItem のいずれかを呼び出す必要があります。indexMenu パラメーターは、最初のメニュー項目に使用するインデックスを保持します。各メニュー項目の識別子は、idCmdFirst と idCmdLast によって定義される範囲内に収まる必要があります。
一般的な方法は、最初のコマンド識別子を idCmdFirst(オフセット 0)に設定し、追加のコマンドごとにオフセットを 1 ずつ増やすことです。この方法により、idCmdLast を超えないことが保証され、他のハンドラーが使用できる識別子の範囲が維持されます。オフセットは後続の IContextMenu::GetCommandString および IContextMenu::InvokeCommand の呼び出しでコマンドを識別するために使用できるため、参照用に保存してください。
シェルが後で別のショートカットメニューハンドラーを呼び出す場合、そのハンドラーの QueryContextMenu メソッドを呼び出す際に idCmdFirst を設定するために、返された HRESULT のコード値を使用します。
コンテキストメニューハンドラーがポップアップメニュー項目を追加する場合、WM_INITMENUPOPUP メッセージが転送されるようにするために、IContextMenu::QueryContextMenu を使用してそのメニューに少なくとも 1 つの項目を追加する必要があります。
ショートカットメニュー項目に関連付けられたコマンドを実行します。
| pici | CMINVOKECOMMANDINFO* | in | コマンドに関する詳細を含む CMINVOKECOMMANDINFO または CMINVOKECOMMANDINFOEX 構造体へのポインター。 |
戻り値
型: HRESULT
このメソッドが成功した場合、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。
解説(Remarks)
IContextMenu インターフェイスは、いくつかのシェル拡張ハンドラーおよび名前空間拡張によってエクスポートされます。これは、ショートカットメニューにコマンドを追加するために使用されます。ハンドラーまたは名前空間拡張がショートカットメニューに追加したコマンドの 1 つをユーザーが選択すると、シェルはそのコマンドの InvokeCommand メソッドを呼び出します。コマンドは、IContextMenu::QueryContextMenu が呼び出されたときに定義されたメニュー識別子オフセット、または関連付けられたバーブによって指定できます。アプリケーションは、オブジェクトの IContextMenu インターフェイスへのポインターを取得することで、このメソッドを直接呼び出すことができます。また、アプリケーションは、ShellExecute または ShellExecuteEx を呼び出し、名前空間拡張またはハンドラーがサポートするバーブを指定することで、このメソッドを間接的に呼び出すこともできます。
ユーザーへの注意
pici パラメーターは Shlobj.h で CMINVOKECOMMANDINFO 構造体として宣言されていますが、CMINVOKECOMMANDINFO または CMINVOKECOMMANDINFOEX のいずれかを使用できます。どちらも ANSI 文字列に対して機能しますが、Unicode 文字列には CMINVOKECOMMANDINFOEX 構造体を使用する必要があります。実装者への注意
pici の cbSize メンバーを確認して、どちらの構造体(CMINVOKECOMMANDINFO または CMINVOKECOMMANDINFOEX)が渡されたかを判断してください。それが CMINVOKECOMMANDINFOEX 構造体であり、fMask メンバーに CMIC_MASK_UNICODE フラグが設定されている場合、構造体の最後の 5 つのメンバーに含まれる Unicode 情報を使用するために、pici を CMINVOKECOMMANDINFOEX にキャストする必要があります。正規のバーブ名またはコマンド ID のいずれかで指定されたバーブがコンテキストメニューハンドラーによって認識されない場合、そのバーブをそれを実装している可能性のある他のコンテキストメニューハンドラーに渡せるように、失敗(E_FAIL)を返す必要があります。
Windows Vista 以降では、CMINVOKECOMMANDINFO または CMINVOKECOMMANDINFOEX 構造体の fMask メンバーに CMIC_MASK_ASYNCOK フラグを設定するだけでは、コマンドを非同期に呼び出すには不十分です。スレッド参照の管理で説明されているように、呼び出し元のスレッドにスレッド参照を設定する必要もあります。
ヘルプ文字列や、言語に依存しないコマンド名(正規名)を含む、ショートカットメニューコマンドに関する情報を取得します。
| idCmd | UINT_PTR | in | メニューコマンド識別子のオフセット。 |
| uType | DWORD | in | 返す情報を指定するフラグ。このパラメーターには、次のいずれかの値を指定できます。 GCS_HELPTEXTApszName に、コマンドのヘルプテキストを含む ANSI 文字列を設定します。 GCS_HELPTEXTWpszName に、コマンドのヘルプテキストを含む Unicode 文字列を設定します。 GCS_VALIDATEAメニュー項目が存在する場合は S_OK を、それ以外の場合は S_FALSE を返します。 GCS_VALIDATEWメニュー項目が存在する場合は S_OK を、それ以外の場合は S_FALSE を返します。 GCS_VERBApszName に、メニュー項目の言語に依存しないコマンド名を含む ANSI 文字列を設定します。 GCS_VERBWpszName に、メニュー項目の言語に依存しないコマンド名を含む Unicode 文字列を設定します。 |
| pReserved | DWORD* | optional | 予約済み。アプリケーションはこのメソッドを呼び出す際に NULL を指定する必要があり、ハンドラーは呼び出されたときにこのパラメーターを無視する必要があります。 |
| pszName | LPSTR | out | 取得される null 終端文字列を受け取るバッファーのアドレス。 |
| cchMax | DWORD | in | null 終端文字列を受け取るバッファーのサイズ(文字数)。 |
戻り値
型: HRESULT
このメソッドが成功した場合、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。
解説(Remarks)
言語に依存しないコマンド名、すなわちバーブは、アプリケーションによってコマンドをアクティブにするために IContextMenu::InvokeCommand メソッドに渡すことができる名前です。ヘルプテキストは、Windows エクスプローラーがステータスバーに表示するコマンドの説明です。適度に短くする必要があります(40 文字未満)。
いくつかの一般的なバーブは、その正規名によって識別できます。たとえば、open、print、delete、rename などです。クライアントは、pszName が指す文字列をこれらの正規名と比較して、ショートカットメニューにそれらが存在するかどうかを確認できます。
pszName は LPSTR として宣言されていますが、uFlags が GCS_HELPTEXTW または GCS_VERBW のいずれかに設定されている場合は、UINT_PTR にキャストして Unicode 文字列を返す必要があります。GCS_UNICODE は、uFlags に含まれるフラグの 'W' 版および 'A' 版をテストするためのビットマスクとして使用できます。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IContextMenu "{000214E4-0000-0000-C000-000000000046}" #usecom global IContextMenu IID_IContextMenu "{}" #comfunc global IContextMenu_QueryContextMenu 3 sptr,int,int,int,int #comfunc global IContextMenu_InvokeCommand 4 var #comfunc global IContextMenu_GetCommandString 5 sptr,int,var,var,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IContextMenu "{000214E4-0000-0000-C000-000000000046}" #usecom global IContextMenu IID_IContextMenu "{}" #comfunc global IContextMenu_QueryContextMenu 3 sptr,int,int,int,int #comfunc global IContextMenu_InvokeCommand 4 sptr #comfunc global IContextMenu_GetCommandString 5 sptr,int,sptr,sptr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。