Добавление элементов пользовательского интерфейса в VSPackages

VSPackage может добавлять элементы пользовательского интерфейса, например меню, панели инструментов и окна инструментов, в Visual Studio с помощью VSCT-файла .

Рекомендации по проектированию элементов пользовательского интерфейса можно найти в рекомендациях по пользовательскому интерфейсу Visual Studio.

Архитектура командной таблицы Visual Studio

Как отмечалось, архитектура таблицы команд поддерживает основные принципы архитектуры. Текеты, лежащие в основе абстракций, структур данных и средств архитектуры таблицы команд, приведены следующим образом:

• Существует три основных типа элементов: меню, команды и группы. Меню можно предоставлять в пользовательском интерфейсе в виде меню, подменю, панелей инструментов или окон инструментов. Команды — это процедуры, которые пользователь может выполнять в интегрированной среде разработки, и их можно предоставлять в виде элементов меню, кнопок, списков или других элементов управления. Группы — это контейнеры для меню и команд.

• Каждый элемент определяется определением, описывающим элемент, его приоритет относительно других элементов и флаги, изменяющие его поведение.

• Каждый элемент имеет расположение, описывающее его родительский элемент. Элемент может иметь множество родителей, чтобы он отображался в нескольких местах в пользовательском интерфейсе.

Каждая команда должна иметь группу в качестве родительского элемента, даже если она является единственным дочерним элементом в этой группе. Каждое стандартное меню также должно иметь родительскую группу. Панели инструментов и окна инструментов действуют как собственные родители. Группа может иметь в качестве родителя главную строку меню Visual Studio, любое меню, панель инструментов или окно инструментов.

Определение элементов

VSCT-файл форматируется в ФОРМАТЕ XML. Он определяет элементы пользовательского интерфейса для пакета и определяет, где эти элементы отображаются в интегрированной среде разработки. Каждому меню, группе или команде в пакете сначала назначены GUID и ID в разделе Symbols. На протяжении остальной части .vsct файла каждое меню, команда и группа определяются их сочетанием GUID и идентификатора. В следующем примере показан типичный Symbols раздел, созданный шаблоном пакета Visual Studio при выборе команды меню в шаблоне.

<Symbols>
  <!-- This is the package guid. -->
  <GuidSymbol name="guidMenuTextPkg" value="{b1253bc6-d266-402b-89e7-5e3d3b22c746}" />

  <!-- This is the guid used to group the menu commands together -->
  <GuidSymbol name="guidMenuTextCmdSet" value="{a633d4e4-6c65-4436-a138-1abeba7c9a69}">
    <IDSymbol name="MyMenuGroup" value="0x1020" />
    <IDSymbol name="cmdidMyCommand" value="0x0100" />
  </GuidSymbol>

  <GuidSymbol name="guidImages" value="{53323d9a-972d-4671-bb5b-9e418480922f}">
    <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" />
  </GuidSymbol>
</Symbols>

Элемент верхнего уровня раздела — это элемент SymbolsGuidSymbol. GuidSymbol элементы связывают имена с идентификаторами GUID, которые используются интегрированной средой разработки для идентификации пакетов и их компонентов.

Первый GuidSymbol элемент — guid<PackageName>Pkgэто GUID самого пакета. Это GUID, используемый Visual Studio для загрузки пакета. Как правило, у него нет дочерних элементов.

По соглашению меню и команды группируются под вторым GuidSymbol элементом, guid<PackageName>CmdSetа растровые изображения находятся под третьим GuidSymbol элементом guidImages. Вам не нужно следовать этому соглашению, но каждое меню, группа, команда и растровое изображение должно быть дочерним элементом GuidSymbol .

Во втором GuidSymbol элементе, представляющего набор команд пакета, есть несколько IDSymbol элементов. Каждый элемент IDSymbol сопоставляет имя числовым значением и может представлять меню, группу или команду, которая входит в набор команд. Элементы IDSymbol в третьем GuidSymbol элементе представляют растровые изображения, которые могут использоваться в качестве значков для команд. Поскольку пары GUID/ID должны быть уникальными в приложении, никакие два дочерних элемента одного и того же GuidSymbol элемента не могут иметь одинаковое значение.

Меню, группы и команды

Если меню, группа или команда имеют GUID и идентификатор, его можно добавить в интегрированную среду разработки. Каждый элемент пользовательского интерфейса должен иметь следующие элементы:

• Атрибут guid , соответствующий имени элемента, в который определяется элемент пользовательского GuidSymbol интерфейса.

• Атрибут id , соответствующий имени связанного IDSymbol элемента.

Вместе и guidid атрибуты составляют сигнатуру элемента пользовательского интерфейса.

• Атрибут priority , определяющий размещение элемента пользовательского интерфейса в родительском меню или группе.

• Элемент Parent, имеющий guid и id атрибуты, указывающие подпись родительского меню или группы.

Меню

Каждое меню определяется как элемент Menu в Menus разделе. Меню должны иметь атрибуты guid, id, и priority, а также элемент Parent, и следующие дополнительные атрибуты и дочерние элементы:

• Атрибут type , указывающий, должно ли меню отображаться в интегрированной среде разработки как вид меню или в виде панели инструментов.

• Элемент Strings, содержащий элемент ButtonText, указывающий название меню в интегрированной среде разработки и элемент CommandName, указывающий имя, которое используется в окне command для доступа к меню.

• Необязательные флаги. Элемент CommandFlag может отображаться в определении меню, чтобы изменить его внешний вид или поведение в интегрированной среде разработки.

Каждый Menu элемент должен иметь группу в качестве родительского элемента, если он не является закрепленным элементом, таким как панель инструментов. Закрепляемое меню является своим родителем. Дополнительные сведения о меню и значениях атрибута type см. в документации по элементу Menu .

В следующем примере показано меню, которое отображается в строке меню Visual Studio рядом с меню "Сервис ".

<Menu guid="guidTopLevelMenuCmdSet" id="TopLevelMenu" priority="0x700" type="Menu">
  <Parent guid="guidSHLMainMenu" id="IDG_VS_MM_TOOLSADDINS" />
  <Strings>
    <ButtonText>TestMenu</ButtonText>
    <CommandName>TestMenu</CommandName>
  </Strings>
</Menu>

Groups

Группа — это элемент, определенный в Groups разделе VSCT-файла . Группы — это просто контейнеры. Они не отображаются в интегрированной среде разработки, за исключением разделительной строки в меню. Поэтому элемент Group определяется только его сигнатурой, приоритетом и родительским элементом.

Группа может иметь меню, другую группу или саму себя в качестве родителя. Однако родительский элемент обычно представляет собой меню или панель инструментов. Меню в предыдущем примере является дочерним элементом группы, и эта группа является дочерним IDG_VS_MM_TOOLSADDINS элементом строки меню Visual Studio. Группа в следующем примере является дочерним элементом меню в предыдущем примере.

<Group guid="guidTopLevelMenuCmdSet" id="MyMenuGroup" priority="0x0600">
  <Parent guid="guidTopLevelMenuCmdSet" id="TopLevelMenu"/>
</Group>

Так как это часть меню, эта группа обычно содержит команды. Однако он также может содержать другие меню. Это способ определения подменю, как показано в следующем примере.

<Menu guid="guidTopLevelMenuCmdSet" id="SubMenu" priority="0x0100" type="Menu">
  <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup"/>
  <Strings>
    <ButtonText>Sub Menu</ButtonText>
    <CommandName>Sub Menu</CommandName>
  </Strings>
</Menu>

Commands

Команда, предоставляемая интегрированной среде разработки, определяется как элемент Button или элемент Combo. Чтобы появиться в меню или панели инструментов, команда должна иметь группу в качестве родительского элемента.

Buttons

Кнопки определены в Buttons разделе. Любой элемент меню, кнопка или другой элемент, который пользователь щелкает, чтобы выполнить одну команду, считается кнопкой. Некоторые типы кнопок также могут включать функции списка. Кнопки имеют одинаковые обязательные и необязательные атрибуты, которые имеют меню, а также могут иметь элемент Icon , указывающий GUID и идентификатор растрового изображения, представляющего кнопку в интегрированной среде разработки. Дополнительные сведения о кнопках и их атрибутах см. в документации об элементе Buttons.

Кнопка в следующем примере является дочерним элементом группы в предыдущем примере и будет отображаться в интегрированной среде разработки в качестве элемента меню в родительском меню этой группы.

<Button guid="guidTopLevelMenuCmdSet" id="cmdidTestCommand" priority="0x0100" type="Button">
  <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup" />
  <Icon guid="guidImages" id="bmpPic1" />
  <Strings>
    <CommandName>cmdidTestCommand</CommandName>
    <ButtonText>Test Command</ButtonText>
  </Strings>
</Button>

Комбо

Комбо определяются в Combos разделе. Каждый Combo элемент представляет раскрывающийся список в интегрированной среде разработки. Список может быть доступен или недоступен для редактирования пользователями, в зависимости от значения атрибута type комбинированного списка. Комбо имеют те же элементы и поведение, что и кнопки, а также могут иметь следующие дополнительные атрибуты:

• Атрибут, указывающий defaultWidth ширину пикселей.

• Атрибут idCommandList , указывающий список, содержащий элементы, отображаемые в поле списка. Список команд должен быть объявлен в том же GuidSymbol узле, где содержится комбобокс.

В следующем примере определяется комбинированный элемент.

<Combos>
  <Combo guid="guidFirstToolWinCmdSet"
         id="cmdidWindowsMediaFilename"
         priority="0x0100" type="DynamicCombo"
         idCommandList="cmdidWindowsMediaFilenameGetList"
         defaultWidth="130">
    <Parent guid="guidFirstToolWinCmdSet"
            id="ToolbarGroupID" />
    <CommandFlag>IconAndText</CommandFlag>
    <CommandFlag>CommandWellOnly</CommandFlag>
    <CommandFlag>StretchHorizontally</CommandFlag>
    <Strings>
      <CommandName>Filename</CommandName>
      <ButtonText>Enter a Filename</ButtonText>
    </Strings>
  </Combo>
</Combos>

Растровые изображения

Команды, которые будут отображаться вместе со значком, должны содержать элемент Icon, ссылающийся на битмап с помощью GUID и ID. Каждое растровое изображение определяется как элемент Bitmap в Bitmaps разделе. Единственными обязательными атрибутами для Bitmap определения являются guid и href, указывающие на исходный файл. Если исходный файл является полосой ресурсов, атрибут usedList также требуется для перечисления доступных изображений в полосе. Дополнительные сведения см. в документации по элементу Bitmap .

Воспитание

Следующие правила определяют способ вызова другого элемента в качестве родительского элемента.

Меню, команда и расположение групп

Меню, группа или команда могут отображаться в нескольких расположениях в интегрированной среде разработки. Чтобы элемент отображался в нескольких местах, его необходимо добавить в раздел CommandPlacements как элемент CommandPlacement. Любое меню, группу или команду можно добавить в качестве размещения команды. Однако панели инструментов нельзя размещать таким образом, так как они не могут отображаться в нескольких расположениях с учетом контекста.

Расположения команд имеют атрибуты guid, id и priority. GUID и идентификатор должны соответствовать идентификаторам элемента, который позиционируется. Атрибут priority управляет размещением элемента относительно других элементов. Если интегрированная среда разработки объединяет два или более элементов с одинаковым приоритетом, их размещение не определено, так как интегрированная среда разработки не гарантирует, что ресурсы пакета считываются в одном порядке при каждом построении пакета.

Если меню или группа отображаются в нескольких местах, все дочерние элементы этого меню или группы будут отображаться в каждом проявлении.

Видимость команд и контекст

При установке нескольких VSPackages обилие меню, пунктов меню и панелей инструментов могут загромождать IDE. Чтобы избежать этой проблемы, можно управлять видимостью отдельных элементов пользовательского интерфейса с помощью ограничений видимости и флагов команд.

Ограничения видимости

Ограничение видимости устанавливается как элемент VisibilityItem в VisibilityConstraints разделе. Ограничение видимости определяет определенные контексты пользовательского интерфейса, в которых отображается целевой элемент. Меню или команда, включенная в этот раздел, отображается только в том случае, если один из определенных контекстов активен. Если меню или команда не ссылается в этом разделе, она всегда отображается по умолчанию. Этот раздел не применяется к группам.

VisibilityItem элементы должны иметь три атрибута: guid и id целевого элемента пользовательского интерфейса, а также context. Атрибут context указывает, когда целевой элемент будет видимым, и принимает любой допустимый контекст пользовательского интерфейса в качестве значения. Константы контекста пользовательского VSConstants интерфейса для Visual Studio являются членами класса. Каждый VisibilityItem элемент может принимать только одно значение контекста. Чтобы применить второй контекст, создайте второй VisibilityItem элемент, указывающий на тот же элемент, как показано в следующем примере.

<VisibilityConstraints>
  <VisibilityItem guid="guidSolutionToolbarCmdSet"
        id="cmdidTestCmd"
        context="UICONTEXT_SolutionHasSingleProject" />
  <VisibilityItem guid="guidSolutionToolbarCmdSet"
        id="cmdidTestCmd"
        context="UICONTEXT_SolutionHasMultipleProjects" />
</VisibilityConstraints>

Флаги команд

Следующие флаги команд могут повлиять на видимость меню и команд, к которые они применяются.

AlwaysCreate Меню создается, даже если у него нет групп или кнопок.

Допустимо для: Menu

CommandWellOnly Примените этот флаг, если команда не отображается в меню верхнего уровня, и вы хотите сделать ее доступной для дополнительной настройки оболочки, например привязывая ее к ключу. После установки VSPackage пользователь может настроить эти команды, открыв диалоговое окно "Параметры " и изменив размещение команд в категории "Среда клавиатуры ". Не влияет на размещение в контекстных меню, на панелях инструментов, на контролерах меню или в подменю.

Допустимо для: Button, Combo

DefaultDisabled По умолчанию команда отключена, если VSPackage, реализующий команду, не загружена или метод QueryStatus не был вызван.

Допустимо для: Button, Combo

DefaultInvisible По умолчанию команда невидима, если VSPackage, реализующий команду, не загружена или метод QueryStatus не был вызван.

Должен сочетаться с флагом DynamicVisibility .

Допустимо для: Button, ComboMenu

DynamicVisibility Видимость команды можно изменить с помощью метода QueryStatus или GUID контекста, который включен в секцию VisibilityConstraints.

Применяется к командам, которые отображаются в меню, а не на панелях инструментов. Элементы панели инструментов верхнего уровня можно отключить, но не скрыть, когда OLECMDF_INVISIBLE флаг возвращается из QueryStatus метода.

В меню этот флаг также указывает, что он должен быть автоматически скрыт при скрытии его элементов. Этот флаг обычно назначается подменю, так как меню верхнего уровня уже имеют такое поведение.

Должен сочетаться с флагом DefaultInvisible .

Допустимо для: Button, ComboMenu

NoShowOnMenuController Если команда с этим флагом находится в контроллере меню, команда не отображается в раскрывающемся списке.

Допустимо для: Button

Для получения дополнительных сведений о флагах команд см. документацию по элементу CommandFlag.

Общие требования

Перед отображением и включением команда должна пройти следующую серию тестов:

• Команда правильно размещена.

• Флаг DefaultInvisible не задан.

• Родительское меню или панель инструментов отображается.

• Команда не является невидимой из-за записи контекста в разделе элемента VisibilityConstraints.

• Код VSPackage, реализующий IOleCommandTarget интерфейс, отображает и включает команду. Код интерфейса не перехватил его и не обработал.

• Когда пользователь щелкает команду, она становится предметом процедуры, описанной в алгоритме маршрутизации.

Вызов предварительно определенных команд

Элемент UsedCommands позволяет VSPackages получать доступ к командам, предоставляемым другими пакетами VSPackage или интегрированной среды разработки. Для этого создайте элемент UsedCommand с GUID и ID команды для использования. Это гарантирует, что команда будет загружена Visual Studio, даже если она не входит в текущую конфигурацию Visual Studio. Дополнительные сведения см. в разделе "Элемент UsedCommand".

Внешний вид элемента интерфейса

Рекомендации по выбору и расположению элементов команд приведены следующим образом:

• Visual Studio предлагает множество элементов пользовательского интерфейса, которые отображаются по-разному в зависимости от размещения.

• Элемент пользовательского интерфейса, определенный с помощью флага DefaultInvisible, не будет отображаться в интегрированной среде разработки, если он не отображается реализацией метода VSPackage, либо не связан с определенным контекстом пользовательского интерфейса в разделе QueryStatus.

• Даже команда с успешной позицией может не отображаться. Это связано с тем, что интегрированная среда разработки автоматически скрывает или отображает некоторые команды в зависимости от интерфейсов, которые в VSPackage реализованы (или не реализованы). Например, реализация VSPackage некоторых интерфейсов сборки приводит к автоматическому отображению элементов меню, связанных со сборкой.

• CommandWellOnly Применение флага в определении элемента пользовательского интерфейса означает, что команда может быть добавлена только путем настройки.

• Команды могут быть доступны только в определенных контекстах пользовательского интерфейса, например, только если диалоговое окно отображается, когда интегрированная среда разработки находится в режиме конструктора.

• Чтобы некоторые элементы пользовательского интерфейса отображались в интегрированной среде разработки, необходимо реализовать один или несколько интерфейсов или написать код.

Связанный контент

• Расширение меню и команд