Freigeben über

So fügen VSPackages Benutzeroberflächenelemente hinzu

  • Artikel

Ein VSPackage kann Benutzeroberflächenelemente, z. B. Menüs, Symbolleisten und Toolfenster, zu Visual Studio mithilfe der VSCT-Datei hinzufügen.

Designrichtlinien für UI-Elemente finden Sie in den Visual Studio-Richtlinien für die Benutzeroberfläche.

Die Visual Studio-Befehlstabellenarchitektur

Wie bereits erwähnt, unterstützt die Befehlstabellenarchitektur die vorstehenden Architekturprinzipien. Die Sätze hinter den Abstraktionen, Datenstrukturen und Tools der Befehlstabellenarchitektur sind wie folgt:

  • Es gibt drei grundlegende Arten von Elementen: Menüs, Befehle und Gruppen. Menüs können auf der Benutzeroberfläche als Menüs, Untermenüs, Symbolleisten oder Toolfenster verfügbar gemacht werden. Befehle sind Prozeduren, die der Benutzer in der IDE ausführen kann, und sie können als Menüelemente, Schaltflächen, Listenfelder oder andere Steuerelemente verfügbar gemacht werden. Gruppen sind Container für Menüs und Befehle.

  • Jedes Element wird durch eine Definition angegeben, die das Element, seine Priorität relativ zu anderen Elementen und die Flags beschreibt, die sein Verhalten ändern.

  • Jedes Element verfügt über eine Platzierung, die das übergeordnete Element des Elements beschreibt. Ein Element kann über mehrere übergeordnete Elemente verfügen, sodass es an mehreren Stellen auf der Benutzeroberfläche angezeigt werden kann.

Jeder Befehl muss eine Gruppe als übergeordnetes Element haben, auch wenn er das einzige untergeordnete Element in dieser Gruppe ist. Jedes Standardmenü muss auch über eine übergeordnete Gruppe verfügen. Symbolleisten und Toolfenster fungieren als eigene Eltern. Eine Gruppe kann als übergeordnetes Element die Standard Visual Studio-Menüleiste oder ein beliebiges Menü-, Symbolleisten- oder Toolfenster aufweisen.

Wie Elemente definiert werden

Eine VSCT-Datei ist in XML formatiert. Sie definiert die UI-Elemente für ein Paket und bestimmt, wo diese Elemente in der IDE angezeigt werden. Jedem Menü, jeder Gruppe oder jedem Befehl im Paket wird zunächst eine GUID und ID im Symbols Abschnitt zugewiesen. Im restlichen Teil der VSCT-Datei wird jedes Menü, jeder Befehl und jede Gruppe durch die GUID- und ID-Kombination identifiziert. Das folgende Beispiel zeigt einen typischen Symbols Abschnitt, der von der Visual Studio-Paketvorlage generiert wird, wenn in der Vorlage ein Menübefehl ausgewählt wird.

<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>

Das Element der obersten Ebene des Symbols Abschnitts ist das GuidSymbol-Element. GuidSymbol Elemente ordnen Namen guiDs zu, die von der IDE verwendet werden, um Pakete und deren Komponententeile zu identifizieren.

Hinweis

GUIDs werden automatisch von der Visual Studio-Paketvorlage generiert. Sie können auch eine eindeutige GUID erstellen, indem Sie im Menü "Extras" auf "GUID erstellen" klicken.

Das erste GuidSymbol Element ist guid<PackageName>Pkgdie GUID des Pakets selbst. Dies ist die GUID, die von Visual Studio zum Laden des Pakets verwendet wird. In der Regel sind keine untergeordneten Elemente vorhanden.

Standardmäßig werden Menüs und Befehle unter einem zweiten GuidSymbol Element gruppiert, guid<PackageName>CmdSetund Bitmaps befinden sich unter einem dritten GuidSymbol Element. guidImages Sie müssen dieser Konvention nicht folgen, aber jedes Menü, jede Gruppe, jeder Befehl und jede Bitmap muss ein untergeordnetes Element sein GuidSymbol .

Im zweiten GuidSymbol Element, das den Paketbefehlssatz darstellt, handelt es sich um mehrere IDSymbol Elemente. Jedes IDSymbol-Element ordnet einen Namen einem numerischen Wert zu und kann ein Menü, eine Gruppe oder einen Befehl darstellen, der Teil des Befehlssatzes ist. Die IDSymbol Elemente im dritten GuidSymbol Element stellen Bitmaps dar, die als Symbole für Befehle verwendet werden können. Da GUID/ID-Paare in einer Anwendung eindeutig sein müssen, haben keine zwei untergeordneten Elemente desselben GuidSymbol Elements möglicherweise denselben Wert.

Wenn ein Menü, eine Gruppe oder ein Befehl über eine GUID und ID verfügt, kann es der IDE hinzugefügt werden. Jedes UI-Element muss folgende Elemente aufweisen:

  • Ein guid Attribut, das dem Namen des GuidSymbol Elements entspricht, unter dem das UI-Element definiert ist.

  • Ein id Attribut, das dem Namen des zugeordneten IDSymbol Elements entspricht.

Zusammen verfassen die guid Attribute id die Signatur des UI-Elements.

  • Ein priority Attribut, das die Platzierung des UI-Elements im übergeordneten Menü oder in der übergeordneten Gruppe bestimmt.

  • Ein übergeordnetes Element mit Attributen, id die guid die Signatur des übergeordneten Menüs oder der übergeordneten Gruppe angeben.

Jedes Menü wird als Menüelement im Menus Abschnitt definiert. Menüs müssen über , idund priority Attribute und ein Parent Element sowie die folgenden zusätzlichen Attribute und untergeordneten Elemente verfügenguid:

  • Ein type Attribut, das angibt, ob das Menü in der IDE als Eine Art Menü oder als Symbolleiste angezeigt werden soll.

  • Ein Strings-Element, das ein ButtonText-Element enthält, das den Titel des Menüs in der IDE angibt, und ein CommandName-Element, das den Namen angibt, der im Befehlsfenster verwendet wird, um auf das Menü zuzugreifen.

  • Optionale Kennzeichnungen. Ein CommandFlag-Element kann in einer Menüdefinition angezeigt werden, um die Darstellung oder das Verhalten in der IDE zu ändern.

Jedes Menu Element muss eine Gruppe als übergeordnetes Element aufweisen, es sei denn, es handelt sich um ein andockbares Element wie eine Symbolleiste. Ein andockbares Menü ist ein eigenes übergeordnetes Element. Weitere Informationen zu Menüs und Werten für das type Attribut finden Sie in der Dokumentation zum Menu-Element .

Das folgende Beispiel zeigt ein Menü, das auf der Menüleiste von Visual Studio neben dem Menü "Extras " angezeigt wird.

<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>

Gruppen

Eine Gruppe ist ein Element, das im Groups Abschnitt der VSCT-Datei definiert ist. Gruppen sind nur Container. Sie werden nicht in der IDE angezeigt, außer als Trennlinie in einem Menü. Daher wird ein Group-Element nur durch seine Signatur, Priorität und das übergeordnete Element definiert.

Eine Gruppe kann über ein Menü, eine andere Gruppe oder selbst als übergeordnete Gruppe verfügen. Das übergeordnete Element ist jedoch in der Regel ein Menü oder eine Symbolleiste. Das Menü im vorherigen Beispiel ist ein untergeordnetes Element der IDG_VS_MM_TOOLSADDINS Gruppe, und diese Gruppe ist ein untergeordnetes Element der Visual Studio-Menüleiste. Die Gruppe im folgenden Beispiel ist ein untergeordnetes Element des Menüs im vorherigen Beispiel.

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

Da sie Teil eines Menüs ist, enthält diese Gruppe in der Regel Befehle. Es könnte jedoch auch andere Menüs enthalten. Dies ist die Definition von Untermenüs, wie im folgenden Beispiel gezeigt.

<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>

Befehle

Ein Befehl, der der IDE bereitgestellt wird, wird entweder als Button-Element oder als Combo-Element definiert. Damit er in einem Menü oder einer Symbolleiste angezeigt wird, muss der Befehl eine Gruppe als übergeordnetes Element aufweisen.

Schaltflächen

Schaltflächen werden im Buttons Abschnitt definiert. Jedes Menüelement, eine Schaltfläche oder ein anderes Element, auf das ein Benutzer klickt, um einen einzelnen Befehl auszuführen, wird als Schaltfläche betrachtet. Einige Schaltflächentypen können auch Listenfunktionen enthalten. Schaltflächen weisen dieselben erforderlichen und optionalen Attribute auf, die Menüs aufweisen, und können auch ein Icon-Element aufweisen, das die GUID und ID der Bitmap angibt, die die Schaltfläche in der IDE darstellt. Weitere Informationen zu Schaltflächen und ihren Attributen finden Sie in der Dokumentation zum Buttons-Element .

Die Schaltfläche im folgenden Beispiel ist ein untergeordnetes Element der Gruppe im vorherigen Beispiel und wird in der IDE als Menüelement im übergeordneten Menü dieser Gruppe angezeigt.

<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

Kombinationen werden im Combos Abschnitt definiert. Jedes Combo Element stellt ein Dropdown-Listenfeld in der IDE dar. Das Listenfeld kann von Benutzern beschreibbar sein, abhängig vom Wert des type Attributs der Kombination. Kombinationen weisen die gleichen Elemente und dasselbe Verhalten auf, über die Schaltflächen verfügen, und können auch die folgenden zusätzlichen Attribute aufweisen:

  • Ein defaultWidth Attribut, das die Pixelbreite angibt.

  • Ein idCommandList Attribut, das eine Liste angibt, die die im Listenfeld angezeigten Elemente enthält. Die Befehlsliste muss im selben GuidSymbol Knoten deklariert werden, der die Kombination enthält.

Im folgenden Beispiel wird ein Kombinationselement definiert.

<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>
Bitmaps

Befehle, die zusammen mit einem Symbol angezeigt werden, müssen ein Icon Element enthalten, das auf eine Bitmap verweist, indem die GUID und DIE ID verwendet werden. Jede Bitmap wird als Bitmapelement im Bitmaps Abschnitt definiert. Die einzigen erforderlichen Attribute für eine Bitmap Definition sind guid und href, die auf die Quelldatei zeigen. Wenn es sich bei der Quelldatei um einen Ressourcenstreifen handelt, ist auch ein usedList-Attribut erforderlich, um die verfügbaren Bilder im Strip auflisten zu können. Weitere Informationen finden Sie in der Dokumentation zu Bitmap-Elementen .

Überordnung

Die folgenden Regeln regeln, wie ein Element ein anderes Element als übergeordnetes Element aufrufen kann.

Element In diesem Abschnitt der Befehlstabelle definiert Kann enthalten sein (als übergeordnetes Element oder durch Platzierung im CommandPlacements Abschnitt oder beides) Kann enthalten (als übergeordnetes Element bezeichnet)
Group Groups-Element, die IDE, andere VSPackages Ein Menü, eine Gruppe, das Element selbst Menüs, Gruppen und Befehle
Menü Menus-Element, die IDE, andere VSPackages 1 bis n Gruppen 0 bis n Gruppen
Symbolleiste Menus-Element, die IDE, andere VSPackages Das Element selbst 0 bis n Gruppen
Menübefehl Buttons-Element, die IDE, andere VSPackages 1 bis n Gruppen, das Element selbst -0 bis n-Gruppen
Schaltfläche Buttons-Element, die IDE, andere VSPackages 1 bis n Gruppen, das Element selbst
Kombinationsdiagramm Combos-Element, die IDE, andere VSPackages 1 bis n Gruppen, das Element selbst

Ein Menü, eine Gruppe oder ein Befehl kann an mehreren Speicherorten in der IDE angezeigt werden. Damit ein Element an mehreren Speicherorten angezeigt wird, muss es dem CommandPlacements Abschnitt als CommandPlacement-Element hinzugefügt werden. Jedes Menü, jede Gruppe oder jeder Befehl kann als Befehlsplatzierung hinzugefügt werden. Symbolleisten können jedoch nicht auf diese Weise positioniert werden, da sie nicht an mehreren kontextabhängigen Speicherorten angezeigt werden können.

Befehlsplatzierungen verfügen über guid, idund priority Attribute. Die GUID und DIE ID müssen mit denen des Elements übereinstimmen, das positioniert ist. Das priority Attribut steuert die Platzierung des Elements in Bezug auf andere Elemente. Wenn die IDE zwei oder mehr Elemente mit der gleichen Priorität zusammenführt, sind ihre Platzierungen nicht definiert, da die IDE nicht garantiert, dass Paketressourcen bei jeder Erstellung des Pakets in derselben Reihenfolge gelesen werden.

Wenn ein Menü oder eine Gruppe an mehreren Speicherorten angezeigt wird, werden alle untergeordneten Elemente dieses Menüs oder dieser Gruppe in jeder Instanz angezeigt.

Sichtbarkeit und Kontext von Befehlen

Wenn mehrere VSPackages installiert werden, kann die IDE durch eine Vielzahl von Menüs, Menüelementen und Symbolleisten überladen werden. Um dieses Problem zu vermeiden, können Sie die Sichtbarkeit einzelner UI-Elemente mithilfe von Sichtbarkeitseinschränkungen und Befehlskennzeichnungen steuern.

Sichtbarkeitseinschränkungen

Eine Sichtbarkeitseinschränkung wird als VisibilityItem-Element im VisibilityConstraints Abschnitt festgelegt. Eine Sichtbarkeitseinschränkung definiert bestimmte UI-Kontexte, in denen das Zielelement sichtbar ist. Ein Menü oder Befehl, das in diesem Abschnitt enthalten ist, ist nur sichtbar, wenn einer der definierten Kontexte aktiv ist. Wenn in diesem Abschnitt nicht auf ein Menü oder einen Befehl verwiesen wird, ist es standardmäßig immer sichtbar. Dieser Abschnitt gilt nicht für Gruppen.

VisibilityItem Elemente müssen drei Attribute aufweisen, wie folgt: das guid Und id das Ziel-UI-Element und context. Das context Attribut gibt an, wann das Zielelement sichtbar ist, und verwendet einen gültigen UI-Kontext als Wert. Die Ui-Kontextkonstanten für Visual Studio sind Member der VSConstants Klasse. Jedes VisibilityItem Element kann nur einen Kontextwert annehmen. Um einen zweiten Kontext anzuwenden, erstellen Sie ein zweites VisibilityItem Element, das auf dasselbe Element verweist, wie im folgenden Beispiel gezeigt.

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

Befehlskennzeichnungen

Die folgenden Befehlskennzeichnungen können sich auf die Sichtbarkeit der Menüs und Befehle auswirken, auf die sie angewendet werden.

AlwaysCreate Das Menü wird auch dann erstellt, wenn es keine Gruppen oder Schaltflächen enthält.

Gültig für: Menu

CommandWellOnly Wenden Sie dieses Kennzeichen an, wenn der Befehl nicht im Menü der obersten Ebene angezeigt wird und Sie es für zusätzliche Shellanpassungen verfügbar machen möchten, z. B. binden Sie ihn an einen Schlüssel. Nachdem das VSPackage installiert wurde, kann ein Benutzer diese Befehle anpassen, indem er das Dialogfeld "Optionen " öffnet und dann die Befehlsplatzierung unter der Kategorie " Tastaturumgebung " bearbeitet. Wirkt sich nicht auf die Platzierung in Kontextmenüs, Symbolleisten, Menücontrollern oder Untermenüs aus.

Gültig für: Button, Combo

DefaultDisabled Der Befehl ist standardmäßig deaktiviert, wenn der VSPackage, der den Befehl implementiert, nicht geladen wird oder die QueryStatus-Methode nicht aufgerufen wurde.

Gültig für: Button, Combo

DefaultInvisible Standardmäßig ist der Befehl unsichtbar, wenn der VSPackage, der den Befehl implementiert, nicht geladen wird oder die QueryStatus-Methode nicht aufgerufen wurde.

Sollte mit der DynamicVisibility Kennzeichnung kombiniert werden.

Gültig für: Button, , ComboMenu

DynamicVisibility Die Sichtbarkeit des Befehls kann mithilfe der QueryStatus Methode oder einer Kontext-GUID geändert werden, die VisibilityConstraints im Abschnitt enthalten ist.

Gilt für Befehle, die in Menüs und nicht auf Symbolleisten angezeigt werden. Symbolleistenelemente der obersten Ebene können deaktiviert, aber nicht ausgeblendet werden, wenn das OLECMDF_INVISIBLE Flag von der QueryStatus Methode zurückgegeben wird.

In einem Menü gibt dieses Flag auch an, dass es automatisch ausgeblendet werden soll, wenn seine Mitglieder ausgeblendet sind. Dieses Flag wird in der Regel Untermenüs zugewiesen, da Menüs der obersten Ebene bereits dieses Verhalten aufweisen.

Sollte mit der DefaultInvisible Kennzeichnung kombiniert werden.

Gültig für: Button, , ComboMenu

NoShowOnMenuController Wenn ein Befehl mit dieser Kennzeichnung auf einem Menücontroller positioniert ist, wird der Befehl nicht in der Dropdownliste angezeigt.

Gültig für: Button

Weitere Informationen zu Befehlskennzeichnungen finden Sie in der Dokumentation zum CommandFlag-Element .

Allgemeine Anforderungen

Ihr Befehl muss die folgende Testreihe bestehen, bevor er angezeigt und aktiviert werden kann:

  • Der Befehl ist richtig positioniert.

  • Die DefaultInvisible Kennzeichnung ist nicht festgelegt.

  • Das übergeordnete Menü oder die Symbolleiste ist sichtbar.

  • Der Befehl ist aufgrund eines Kontexteintrags im VisibilityConstraints-Elementabschnitt nicht unsichtbar.

  • VSPackage-Code, der die IOleCommandTarget Schnittstelle implementiert, zeigt den Befehl an und aktiviert den Befehl. Es wurde kein Schnittstellencode abgefangen und darauf reagiert.

  • Wenn ein Benutzer auf Ihren Befehl klickt, unterliegt er der Prozedur, die im Routingalgorithmus beschrieben wird.

Aufrufen vordefinierter Befehle

Das UsedCommands-Element ermöglicht VSPackages den Zugriff auf Befehle, die von anderen VSPackages oder der IDE bereitgestellt werden. Erstellen Sie dazu ein UsedCommand-Element mit der GUID und ID des zu verwendenden Befehls. Dadurch wird sichergestellt, dass der Befehl von Visual Studio geladen wird, auch wenn er nicht Teil der aktuellen Visual Studio-Konfiguration ist. Weitere Informationen finden Sie unter UsedCommand-Element.

Darstellung des Schnittstellenelements

Überlegungen zum Auswählen und Positionieren von Befehlselementen sind wie folgt:

  • Visual Studio bietet viele UI-Elemente, die je nach Platzierung unterschiedlich angezeigt werden.

  • Ein ui-Element, das mithilfe des DefaultInvisible Flags definiert wird, wird nicht in der IDE angezeigt, es sei denn, es wird von der VSPackage-Implementierung der QueryStatus Methode angezeigt oder einem bestimmten Ui-Kontext im VisibilityConstraints Abschnitt zugeordnet.

  • Selbst ein erfolgreich positionierter Befehl wird möglicherweise nicht angezeigt. Dies liegt daran, dass die IDE einige Befehle automatisch ausblendet oder anzeigt, je nach Schnittstellen, die das VSPackage implementiert hat (oder nicht). Die Implementierung einiger Buildschnittstellen durch eine VSPackage führt beispielsweise dazu, dass buildbezogene Menüelemente automatisch angezeigt werden.

  • Das Anwenden des CommandWellOnly Flags in der Definition des UI-Elements bedeutet, dass der Befehl nur durch Anpassung hinzugefügt werden kann.

  • Befehle sind möglicherweise nur in bestimmten UI-Kontexten verfügbar, z. B. nur, wenn ein Dialogfeld angezeigt wird, wenn sich die IDE in der Entwurfsansicht befindet.

  • Damit bestimmte UI-Elemente in der IDE angezeigt werden, müssen Sie eine oder mehrere Schnittstellen implementieren oder Code schreiben.

Zugehöriger Inhalt