emu雑記

C#erな人が書いているブログです。最近、javaを始めました。なんかいろいろやってます。

Visual Studio 拡張機能 メニューコマンド編 その1

このシリーズは、上のカテゴリ「Visual Studio SDK」で絞り込むと、いい感じに読んでいけると思います。


さて。前回の続きです。
Visual Studio 拡張機能(Package) メニューコマンド(Menu Command)編です。

コマンドボタンのプロジェクトを作成したところで終わりました。

ソリューションはこんな感じ。
f:id:emu717171:20131112212138j:plain
この中で、普段あんまり見ないファイルがvsctファイル。
これが、拡張機能の設定ファイルになります。

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <!--  This is the file that defines the actual layout and type of the commands.
        It is divided in different sections (e.g. command definition, command
        placement, ...), with each defining a specific set of properties.
        See the comment before each section for more details about how to
        use it. -->
  <!--  The VSCT compiler (the tool that translates this file into the binary
        format that VisualStudio will consume) has the ability to run a preprocessor
        on the vsct file; this preprocessor is (usually) the C++ preprocessor, so
        it is possible to define includes and macros with the same syntax used
        in C++ files. Using this ability of the compiler here, we include some files
        defining some of the constants that we will use inside the file. -->
  <!--This is the file that defines the IDs for all the commands exposed by VisualStudio. -->
  <Extern href="stdidcmd.h"/>
  <!--This header contains the command ids for the menus provided by the shell. -->
  <Extern href="vsshlids.h"/>
  <!--The Commands section is where we the commands, menus and menu groups are defined.
      This section uses a Guid to identify the package that provides the command defined inside it. -->
  <Commands package="guidVSPackage1Pkg">
    <!-- Inside this section we have different sub-sections: one for the menus, another
    for the menu groups, one for the buttons (the actual commands), one for the combos
    and the last one for the bitmaps used. Each element is identified by a command id that
    is a unique pair of guid and numeric identifier; the guid part of the identifier is usually
    called "command set" and is used to group different command inside a logically related
    group; your package should define its own command set in order to avoid collisions
    with command ids defined by other packages. -->
    <!-- In this section you can define new menu groups. A menu group is a container for
         other menus or buttons (commands); from a visual point of view you can see the
         group as the part of a menu contained between two lines. The parent of a group
         must be a menu. -->
    <Groups>
      <Group guid="guidVSPackage1CmdSet" id="MyMenuGroup" priority="0x0600">
        <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>
      </Group>
    </Groups>
    <!--Buttons section. -->
    <!--This section defines the elements the user can interact with, like a menu command or a button
        or combo box in a toolbar. -->
    <Buttons>
      <!--To define a menu group you have to specify its ID, the parent menu and its display priority.
          The command is visible and enabled by default. If you need to change the visibility, status, etc, you can use
          the CommandFlag node.
          You can add more than one CommandFlag node e.g.:
              <CommandFlag>DefaultInvisible</CommandFlag>
              <CommandFlag>DynamicVisibility</CommandFlag>
          If you do not want an image next to your command, remove the Icon node /> -->
      <Button guid="guidVSPackage1CmdSet" id="cmdidMyCommand" priority="0x0100" type="Button">
        <Parent guid="guidVSPackage1CmdSet" id="MyMenuGroup" />
        <Icon guid="guidImages" id="bmpPic1" />
        <Strings>
          <ButtonText>My Command name</ButtonText>
        </Strings>
      </Button>
    </Buttons>
    <!--The bitmaps section is used to define the bitmaps that are used for the commands.-->
    <Bitmaps>
      <!--  The bitmap id is defined in a way that is a little bit different from the others:
            the declaration starts with a guid for the bitmap strip, then there is the resource id of the
            bitmap strip containing the bitmaps and then there are the numeric ids of the elements used
            inside a button definition. An important aspect of this declaration is that the element id
            must be the actual index (1-based) of the bitmap inside the bitmap strip. -->
      <Bitmap guid="guidImages" href="Resources\Images.png" usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
    </Bitmaps>
  </Commands>
  <Symbols>
    <!-- This is the package guid. -->
    <GuidSymbol name="guidVSPackage1Pkg" value="{d1c47ddc-f75c-434b-8811-cb2c1d6a4859}" />
    <!-- This is the guid used to group the menu commands together -->
    <GuidSymbol name="guidVSPackage1CmdSet" value="{79604d92-0315-4a6a-854c-df0d49cbdb71}">
      <IDSymbol name="MyMenuGroup" value="0x1020" />
      <IDSymbol name="cmdidMyCommand" value="0x0100" />
    </GuidSymbol>
    <GuidSymbol name="guidImages" value="{40cb3797-b4ba-47d9-8c40-32d9876cccda}" >
      <IDSymbol name="bmpPic1" value="1" />
      <IDSymbol name="bmpPic2" value="2" />
      <IDSymbol name="bmpPicSearch" value="3" />
      <IDSymbol name="bmpPicX" value="4" />
      <IDSymbol name="bmpPicArrows" value="5" />
      <IDSymbol name="bmpPicStrikethrough" value="6" />
    </GuidSymbol>
  </Symbols>
</CommandTable>

見づらい+英語が苦手なので、google先生に翻訳を依頼。

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <!-- 
  このファイルは、コマンドの実際のレイアウトおよびタイプを定義するファイルです。
  それぞれ、特性の特定のセットの定義セクションに分割されます。
  使用する詳細な方法については、各セクションの前にコメントを参照してください。
  -->
  <!--
  VSCTコンパイラー(このファイルをVisualStudioがバイナリフォーマットに翻訳するツール)は、
  vsctファイル上でプリプロセッサーを実行する能力を持っています。
  このプリプロセッサーはC++プリプロセッサーです。
  したがって、C++ファイルの中で使用される同じシンタックスを備えたマクロを定義することは可能です。
  ここのコンパイラーのこの能力を使用して、私たちは、
  ファイルの内部で使用する定数をいくつかの定義ファイルで設定します。
  -->
  <!--これは、VisualStudioによって表示される、すべてのコマンドIDを定義するファイルです。 -->
  <Extern href="stdidcmd.h"/>
  <!--このヘッダーは、シェルによって提供されるすべてのメニュー用のコマンドIDを含んでいます。 -->
  <Extern href="vsshlids.h"/>
  <!--
  コマンド・セクションは、コマンド/メニュー/メニュー・グループを定義する場所です。
  コマンドを提供するパッケージを識別するのにこのセクションの内部で設定を行います。
  -->
  <Commands package="guidVSPackage1Pkg">
    <!-- 
    このセクションの内部で、異なるサブセクションを持っています:
  ①メニューの配置
    ②メニュー・グループの配置
   ③ボタン(実際のコマンド)の配置
    ④コンボの配置
    ⑤ビットマップ用
    要素はそれぞれ、ユニークな1ペアで、数値型のコマンドIDによって識別されます。
    通常「コマンドセット」と呼ばれ、論理上関連するグループの内部の異なるコマンドを
    グループ化するために使用されます。
    パッケージは他のパッケージによって定義されたコマンドID達の衝突を回避するために、
    それ自身のコマンドセットを定義するべきです。
    -->
    <!--グループ定義セクション -->
    <!--
    このセクションでは、新しいメニュー・グループを定義することができます。
    メニュー・グループは他のメニューあるいはボタン(コマンド)用のコンテナーです。
    グループを2行のライン間で含まれていたメニューの部品と見なすことができます。
    グループの親はメニューであるに違いありません。
    -->
    <Groups>
      <Group guid="guidVSPackage1CmdSet" id="MyMenuGroup" priority="0x0600">
        <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>
      </Group>
    </Groups>
    <!--ボタン定義セクション -->
    <!--
      このセクションは、メニュー・コマンドあるいはツールバー中のボタンか、
    コンボ・ボックスのように、ユーザが対話することができる要素を定義します。
    -->
    <Buttons>
      <!--
      メニュー・グループを定義するために、そのID、親メニューおよびその表示順(priority)を指定しなければなりません。
      コマンドはデフォルトで可視設定にされてます。
      可視設定やステータスなどを変更する必要があれば、CommandFlagノードを使用します。
      1つを超えるCommandFlagノードを加えることができます。
      例)
      <CommandFlag>DefaultInvisible</CommandFlag>
      <CommandFlag>DynamicVisibility</CommandFlag>
      アイコンを設定する場合には
      <Icon Guid=guidOfficeIcon id=msotcidNoIcon">
      で設定します。Bitmapセクションで定義したGuid値を設定します。
      -->
      <Button guid="guidVSPackage1CmdSet" id="cmdidMyCommand" priority="0x0100" type="Button">
        <Parent guid="guidVSPackage1CmdSet" id="MyMenuGroup" />
        <Icon guid="guidImages" id="bmpPic1" />
        <Strings>
          <ButtonText>My Command name</ButtonText>
        </Strings>
      </Button>
    </Buttons>
    <!--Bitmapセクションは、コマンドに使用されるビットマップを定義します。-->
    <Bitmaps>
      <!--
      ビットマップidは、他のものとはわずかに異なる方法の中で定義されています。
      宣言はスタートします、で、1つの、ビットマップ一片にはGuid、その後、Bitmapのidがあります。
      この宣言のポイントは、要素IDがBitmapの内部のインデックス(1からスタート)です。
      -->
      <Bitmap guid="guidImages" href="Resources\Images.png" usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
    </Bitmaps>
  </Commands>
  <Symbols>
    <!--
    パッケージのGuidです。
    このGuidはパッケージクラスで指定したGuidと同一である必要があります。
    一つの場所で管理しやすいようにGuids.csに記載します。
    -->
    <GuidSymbol name="guidVSPackage1Pkg" value="{d1c47ddc-f75c-434b-8811-cb2c1d6a4859}" />
    <!--
    メニュー・コマンドを一まとめにするために使用されたGuidです。
    このGuidは、コマンドの定義をパッケージクラスで使用したものと同一である必要があります。
    一つの場所で管理しやすいようにGuids.csに記載します。
    -->
    <GuidSymbol name="guidVSPackage1CmdSet" value="{79604d92-0315-4a6a-854c-df0d49cbdb71}">
      <IDSymbol name="MyMenuGroup" value="0x1020" />
      <IDSymbol name="cmdidMyCommand" value="0x0100" />
    </GuidSymbol>
    <GuidSymbol name="guidImages" value="{40cb3797-b4ba-47d9-8c40-32d9876cccda}" >
      <IDSymbol name="bmpPic1" value="1" />
      <IDSymbol name="bmpPic2" value="2" />
      <IDSymbol name="bmpPicSearch" value="3" />
      <IDSymbol name="bmpPicX" value="4" />
      <IDSymbol name="bmpPicArrows" value="5" />
      <IDSymbol name="bmpPicStrikethrough" value="6" />
    </GuidSymbol>
  </Symbols>
</CommandTable>

となっています。

結局わかりやすく階層形式で書くと
guidVSPackage1Pkg(作成する拡張機能を表すGuid値)
 └guidSHLMainMenu(ツールメニュー:Visual Studioのメニューバーの【ツール】をIDM_VS_MENU_TOOLSという定数で表現)
   └MyMenuGroup(メニューグループ:ここではMyMenuGroupという名で定義)
     └cmdidMyCommand(コマンド:ここではcmdidMyCommandという名で定義)

このMyMenuGroupとcmdidMyCommandをひとくくりで管理するGuidをguidVSPackage1CmdSetという名で定義しています。


では、今回の拡張機能の主役であるコマンドボタンを細かく見ていきましょう。

<Buttons>
  <Button guid="guidVSPackage1CmdSet" id="cmdidMyCommand" priority="0x0100" type="Button">
    <Parent guid="guidVSPackage1CmdSet" id="MyMenuGroup" />
    <Icon guid="guidImages" id="bmpPic1" />
    <Strings>
      <ButtonText>My Command name</ButtonText>
    </Strings>
  </Button>
</Buttons>

どのメニューグループに属するかはParent要素で表現します。上の階層表現で説明しました。
アイコンをどうするかは、Icon要素で表現し、最後で定義したアイコン用のIDで定義します。
拡張機能で使用するアイコンは、Bitmap要素でGuid属性で定義されます。
Guid属性の値は下のSymbols要素で管理をしています。

<Bitmaps>
  <!--
  ビットマップidは、他のものとはわずかに異なる方法の中で定義されています。
  宣言はスタートします、で、1つの、ビットマップ一片にはGuid、その後、Bitmapのidがあります。
  この宣言のポイントは、要素IDがBitmapの内部のインデックス(1からスタート)です。
  -->
  <Bitmap guid="guidImages" href="Resources\Images.png" usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
</Bitmaps>
<CommandTable>
  <Symbols>
    <GuidSymbol name="guidImages" value="{40cb3797-b4ba-47d9-8c40-32d9876cccda}" >
      <IDSymbol name="bmpPic1" value="1" />
      <IDSymbol name="bmpPic2" value="2" />
      <IDSymbol name="bmpPicSearch" value="3" />
      <IDSymbol name="bmpPicX" value="4" />
      <IDSymbol name="bmpPicArrows" value="5" />
      <IDSymbol name="bmpPicStrikethrough" value="6" />
    </GuidSymbol>
  <Symbols>
<CommandTable>


最後にStrings要素ですが、少し注意が必要です。

<Strings>
  <ButtonText>My Command name</ButtonText>
</Strings>

上記はコマンドのキャプションを定義しています。
Strings要素で定義されている理由は、拡張機能の多言語化対応です。
いま、デフォルトのキャプションが定義されていますが、
日本語環境だと「私のコマンドですよ!」と表示したいとします。
その場合には、以下のように定義します。

</Buttons>
  <Button guid="guidVSPackage1CmdSet" id="cmdidMyCommand" priority="0x0100" type="Button">
    <Parent guid="guidVSPackage1CmdSet" id="MyMenuGroup" />
    <Icon guid="guidImages" id="bmpPic1" />
    <Strings>
      <ButtonText>My Command name</ButtonText>
    </Strings>
    <Strings language="ja-jp">
      <ButtonText>私のコマンドですよ!</ButtonText>
    </Strings>
  </Button>
</Buttons>

のように、の要素に「language="ja-jp"」という属性を付けてあげると、
日本語環境であれば「私のコマンドですよ!」が表示され、それ以外の言語環境であれば「My Command name」が表示されます。
f:id:emu717171:20131112224555j:plain


では、最後に作成するメニューコマンドの配置方法を説明します。

メニューバーへの配置は、Groups要素で定義します。
メニューバーを変更する場合のid値は参考URLをご覧ください。

<Groups>
  <Group guid="guidVSPackage1CmdSet" id="MyMenuGroup" priority="0x0600">
    <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>
  </Group>
</Groups>

の場合、メニューバーの「ツール」に表示されます。
f:id:emu717171:20131112232307j:plain

メニューバーの「編集」に表示したい場合には、以下のように編集します。

<Groups>
  <Group guid="guidVSPackage1CmdSet" id="MyMenuGroup" priority="0x0600">
    <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_EDIT"/>
  </Group>
</Groups>

編集の直下に表示されるようになります。
f:id:emu717171:20131112232603j:plain


さて、次回はVisual Studioのコンテキストメニューにコマンドを配置する方法を説明します。

んー…この連載1年くらいかかりそうだなぁ…。


参考URL