.vsct ファイルを記述する
このドキュメントでは、メニュー項目、ツール バー、その他のユーザー インターフェイス (UI) 要素を Visual Studio 統合開発環境 (IDE) に追加するために、.vsct ファイルを記述する方法について説明します。 これらの手順は、まだ .vsct ファイルがない Visual Studio パッケージ (VSPackage) に UI 要素を追加する場合に使用します。
新しいプロジェクトの場合は、Visual Studio パッケージ テンプレートを使用することをお勧めします。このテンプレートでは、選択内容に応じて、メニュー コマンド、ツール ウィンドウ、またはカスタム エディターに必要な要素を既に持つ .vsct ファイルが生成されるためです。 この .vsct ファイルを変更して、VSPackage の要件を満たすことができます。 .vsct ファイルを変更する方法の詳細については、「メニューとコマンドを拡張する」の例を参照してください。
ファイルを記述する
.vsct ファイルを記述するためのフェーズは次のとおりです。ファイルとリソースの構造を作成し、UI 要素を宣言して、UI 要素を IDE に配置し、特殊な動作を追加します。
ファイル構造
.vsct ファイルの基本構造は CommandTable ルート要素であり、Commands 要素と Symbols 要素が含まれています。
ファイル構造を作成するには
「方法: vsct ファイルを作成する」の手順に従って、.vsct ファイルをプロジェクトに追加します。
次の例に示すように、必要な名前空間を
CommandTable要素に追加します。<CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable" xmlns:xs="http://www.w3.org/2001/XMLSchema">CommandTable要素に、すべてのカスタム メニュー、ツール バー、コマンド グループ、コマンドをホストするCommands要素を追加します。 カスタム UI 要素を読み込むことができるようにするには、Commands要素のPackage属性にパッケージの名前が設定されている必要があります。Commands要素の後にSymbols要素を追加して、パッケージの GUID、および UI 要素の名前とコマンド ID を定義します。
Visual Studio リソースを含める
Visual Studio のコマンドが定義されているファイルと、IDE に UI 要素を配置するために必要なメニューにアクセスするには、Extern 要素を使用します。 パッケージの外部で定義されているコマンドを使用する場合は、UsedCommands 要素を使用して Visual Studio に通知します。
Visual Studio リソースを含めるには
CommandTable要素の先頭に、参照する外部ファイルごとに 1 つのExtern要素を追加し、href属性をファイルの名前に設定します。 次のヘッダー ファイルを参照すると、Visual Studio リソースにアクセスできます。Stdidcmd.h: Visual Studio によって公開されるすべてのコマンドの ID を定義します。
Vsshlids. h: Visual Studio メニューのコマンド ID が含まれています。
Visual Studio または他のパッケージで定義されているコマンドをパッケージで呼び出す場合は、
Commands要素の後にUsedCommands要素を追加します。 パッケージの一部ではない、呼び出すコマンドごとに UsedCommand 要素をこの要素に設定します。UsedCommand要素のguidおよびid属性に、呼び出すコマンドの GUID と ID の値を設定します。Visual Studio コマンドの GUID と ID を検索する方法の詳細については、「Visual studio コマンドの GUID と ID」を参照してください。 他のパッケージからコマンドを呼び出すには、そのパッケージの .vsct ファイルで定義されているコマンドの GUID と ID を使用します。
UI 要素を宣言する
新しい UI 要素はすべて .vsct ファイルの Symbols セクションで宣言します。
UI 要素を宣言するには
Symbols要素に 3 つの GuidSymbol 要素を追加します。 各GuidSymbol要素には、name属性とvalue属性があります。 要素の目的が反映されるようにname属性を設定します。value属性は GUID を受け取ります。 (GUID を生成するには、[ツール] メニューで [GUID の作成] を選択し、[登録形式] を選択します。)最初の
GuidSymbol要素はパッケージを表し、通常は子を持ちません。 2 番目のGuidSymbol要素はコマンド セットを表し、メニュー、グループ、コマンドを定義するすべてのシンボルが含まれています。 3 番目のGuidSymbol要素はイメージ ストアを表し、コマンドのすべてのアイコンのシンボルが含まれています。 アイコンを使用するコマンドがない場合は、3 番目のGuidSymbol要素を省略できます。コマンド セットを表す
GuidSymbol要素に、1 つまたは複数の IDSymbol 要素を追加します。 これらは UI に追加するメニュー、ツール バー、グループ、またはコマンドをそれぞれ表します。各
IDSymbol要素で、対応するメニュー、グループ、またはコマンドを参照するために使用される名前をname属性に設定し、そのコマンド ID を表す 16 進数をvalue要素に設定します。 同じ親を持つ 2 つのIDSymbol要素を同じ値にすることはできません。UI 要素のいずれかにアイコンが必要な場合は、イメージ ストアを表す
GuidSymbol要素に各アイコンのIDSymbol要素を追加します。
UI 要素を IDE に配置する
Menus、Groups、Buttons の各要素には、パッケージで定義されているすべてのメニュー、グループ、コマンドの定義が含まれています。 これらのメニュー、グループ、コマンドを IDE に配置するには、UI 要素の定義の一部である Parent 要素を使用するか、別の場所で定義された CommandPlacement 要素を使用します。
Menu、Group、Button の各要素には、guid 属性と id 属性があります。 コマンド セットを表す GuidSymbol 要素の名前と一致するように常に guid 属性を設定し、Symbols セクション内のメニュー、グループ、またはコマンドを表す IDSymbol 要素の名前を id 属性に設定します。
UI 要素を定義するには
新しいメニュー、サブメニュー、ショートカット メニュー、またはツール バーを定義する場合は、
Commands要素にMenus要素を追加します。 次に、作成するメニューごとに、Menu 要素をMenus要素に追加します。Menu要素のguidおよびid属性を設定し、目的のメニューの種類をtype属性に設定します。 また、priority属性を設定して、親グループ内のメニューの相対位置を設定することもできます。Note
priority属性は、ツール バーとコンテキスト メニューには適用されません。Visual Studio IDE のすべてのコマンドは、メニューとツール バーの直接の子であるコマンド グループでホストされている必要があります。 新しいメニューやツール バーを IDE に追加する場合は、新しいコマンド グループが含まれている必要があります。 コマンドを視覚的にグループ化できるように、既存のメニューやツール バーにコマンド グループを追加することもできます。
新しいコマンド グループを追加する場合は、最初に
Groups要素を作成してから、各コマンド グループの Group 要素を追加する必要があります。各
Group要素のguidおよびid属性を設定してから、priority属性を設定して、親メニューのグループの相対位置を設定します。 詳細については、「再利用可能なボタンのグループを作成する」を参照してください。IDE に新しいコマンドを追加する場合は、
Commands要素にButtons要素を追加します。 次に、各コマンドについて、Buttons要素に Button 要素を追加します。各
Button要素のguidおよびid属性を設定し、目的のボタンの種類をtype属性に設定します。 また、priority属性を設定して、親グループ内のコマンドの相対位置を設定することもできます。Note
ツール バーの標準のメニュー コマンドとボタンには
type="button"使用します。Button要素に、ButtonText 要素と CommandName 要素を含む Strings 要素を追加します。ButtonText要素によって、メニュー項目のテキスト ラベル、またはツール バーのボタンのツール ヒントが提供されます。CommandName要素によって、コマンド ウェルで使用されるコマンドの名前が提供されます。コマンドにアイコンがある場合は、
Button要素に Icon 要素を作成し、そのguidおよびid属性にアイコンのBitmap要素を設定します。Note
ツール バーのボタンにはアイコンが必要です。
詳細については、「MenuCommands と OleMenuCommands の比較」を参照してください。
いずれかのコマンドでアイコンが必要な場合は、
Commands要素に Bitmaps 要素を追加します。 次に、各アイコンについて、Bitmaps要素に Bitmap 要素を追加します。 これはビットマップ リソースの場所を指定する場所です。 詳細については、「メニュー コマンドにアイコンを追加する」を参照してください。ほとんどのメニュー、グループ、コマンドは、ペアレンティング構造体に依存して正しく配置することができます。 非常に大きなコマンド セットの場合、またはメニュー、グループ、またはコマンドを複数の場所に表示する必要がある場合は、コマンドの配置を指定することをお勧めします。
ペアレンティングに依存して IDE に UI 要素を配置するには
一般的なペアレンティングの場合は、パッケージで定義されている
Menu、Group、Commandの各要素にParent要素を作成します。Parent要素のターゲットは、メニュー、グループ、またはコマンドを含むメニューまたはグループです。コマンド セットを定義する
GuidSymbol要素の名前をguid属性に設定します。 ターゲット要素がパッケージに含まれていない場合は、対応する .vsct ファイルで定義されているそのコマンド セットの GUID を使用します。ターゲットのメニューまたはグループの
id属性と一致するようにid属性を設定します。 Visual Studio によって公開されているメニューとグループの一覧については、「Visual Studio メニューの GUID と ID」または「Visual Studio ツール バーの GUID と ID」を参照してください。
IDE に配置する UI 要素が多数ある場合、または複数の場所に表示される要素がある場合は、次の手順に示すように、それらの配置を CommandPlacements 要素に定義します。
コマンドの配置を使用して IDE に UI 要素を配置するには
Commands要素の後に、CommandPlacements要素を追加します。CommandPlacements要素に、配置するメニュー、グループ、またはコマンドごとにCommandPlacement要素を追加します。各
CommandPlacement要素またはParent要素では、1 つの IDE の場所に 1 つのメニュー、グループ、またはコマンドが配置されます。 UI 要素で持つことができる親は 1 つのみですが、複数のコマンドの配置を持つことができます。 UI 要素を複数の場所に配置するには、場所ごとにCommandPlacement要素を追加します。Parent要素の場合と同様に、各CommandPlacement要素のguidおよびid属性に、ホストするメニューまたはグループを設定します。 また、priority属性を設定して、UI 要素の相対位置を設定することもできます。ペアレンティングによる配置とコマンドの配置は組み合わせることができます。 ただし、非常に大きなコマンド セットの場合は、コマンドの配置のみを使用することをお勧めします。
特殊な動作を追加する
メニューやコマンドの動作を変更する (外観や表示の変更など) には、CommandFlag 要素を使用します。 また、VisibilityConstraints 要素を使用してコマンドがどのようなときに表示されるかに影響を与えたり、KeyBindings 要素を使用してキーボード ショートカットを追加したりすることもできます。 特定の種類のメニューとコマンドには、既に特殊な動作が組み込まれています。
特殊な動作を追加するには
特定の UI コンテキスト (ソリューションが読み込まれたときなど) でのみ UI 要素が表示されるようにするには、可視性の制約を使用します。
Commands要素の後に、VisibilityConstraints要素を追加します。制約する各 UI 項目に、VisibilityItem 要素を追加します。
各
VisibilityItem要素で、メニュー、グループ、またはコマンドにguidおよびid属性を設定し、UIContextGuids80 クラスで定義されているように、目的の UI コンテキストをcontext属性に設定します。
コード内の UI 項目の可視性または可用性を設定するには、次のコマンド フラグのいずれか (または複数のフラグ) を使用します。
DefaultDisabledDefaultInvisibleDynamicItemStartDynamicVisibilityNoShowOnMenuControllerNotInTBList
詳細については、「CommandFlag 要素」を参照してください。
要素の表示方法を変更したり、要素の外観を動的に変更したりするには、次のコマンド フラグのいずれか (または複数のフラグ) を使用します。
AlwaysCreateCommandWellOnlyDefaultDockedDontCacheDynamicItemStartFixMenuControllerIconAndTextPictStretchHorizontallyTextMenuUseButtonTextChangesTextOnly
詳細については、「CommandFlag 要素」を参照してください。
コマンドを受け取ったときの要素の反応を変更するには、次のコマンド フラグのいずれか (または複数のフラグ) を使用します。
AllowParamsCaseSensitiveCommandWellOnlyFilterKeysNoAutoCompleteNoButtonCustomizeNoKeyCustomizeNoToolbarClosePostExecRouteToDocsTextIsAnchorCommand
詳細については、「CommandFlag 要素」を参照してください。
メニュー依存のキーボード ショートカットをメニューまたはメニュー項目にアタッチするには、メニューまたはメニュー項目の
ButtonText要素にアンパサンド文字 (&) を追加します。 アンパサンドの後に続く文字は、親メニューが開いているときにアクティブなキーボード ショートカットです。メニューに依存しないキーボード ショートカットをコマンドにアタッチするには、KeyBindings 要素を使用します。 詳細については、「KeyBinding 要素」を参照してください。
メニュー テキストをローカライズするには、
LocCanonicalName要素を使用します。 詳細については、「Strings 要素」を参照してください。いくつかのメニューとボタンの種類には、特殊な動作が含まれています。 次の一覧では、いくつかの特殊なメニューとボタンの種類について説明しています。 その他の種類については、Menu、Button、Combo 要素の
types属性の説明を参照してください。コンボ ボックス: コンボ ボックスは、ツール バーで使用できるドロップダウン リストです。 コンボ ボックスを UI に追加するには、
Commands要素に Combos 要素を作成します。 次に、追加する各コンボ ボックスのCombo要素をCombos要素に追加します。Combo要素には、Button要素と同じ属性と子があり、DefaultWidthおよびidCommandList属性もあります。DefaultWidth属性にはピクセル単位で幅を設定し、idCommandList属性ではコンボ ボックスの事前設定に使用されるコマンド ID を指します。メニュー コントローラー: メニュー コントローラーは、その横に矢印があるボタンです。 矢印をクリックすると、一覧が表示されます。 メニュー コントローラーを UI に追加するには、必要な動作に応じて、
Menu要素を作成し、そのtype属性にMenuControllerまたはMenuControllerLatchedを設定します。 メニュー コントローラーを事前設定するには、Group要素の親として設定します。 メニュー コントローラーでは、そのグループのすべての子がドロップダウン リストに表示されます。