Share via

Hoe VSPackages elementen van de gebruikersinterface toevoegt

Een VSPackage kan elementen van de gebruikersinterface (UI) toevoegen, bijvoorbeeld menu's, werkbalken en toolvensters, aan Visual Studio via het VSCT-bestand .

U vindt ontwerprichtlijnen voor UI-elementen in de richtlijnen voor gebruikerservaring van Visual Studio.

De visual Studio-opdrachttabelarchitectuur

Zoals vermeld, ondersteunt de opdrachttabelarchitectuur de voorgaande architectuurprincipes. De tenets achter de abstracties, gegevensstructuren en hulpprogramma's van de opdrachttabelarchitectuur zijn als volgt:

  • Er zijn drie basistypen items: menu's, opdrachten en groepen. Menu's kunnen in de gebruikersinterface worden weergegeven als menu's, submenu's, werkbalken of werkvensters. Opdrachten zijn procedures die de gebruiker kan uitvoeren in de IDE en ze kunnen worden weergegeven als menu-items, knoppen, keuzelijsten of andere besturingselementen. Groepen zijn containers voor zowel menu's als opdrachten.

  • Elk item wordt opgegeven door een definitie die het item beschrijft, de prioriteit ten opzichte van andere items en de vlaggen die het gedrag ervan wijzigen.

  • Elk item heeft een toewijzing die het ouderitem aangeeft. Een item kan meerdere bovenouders hebben, zodat het kan worden weergegeven op meerdere locaties in de gebruikersinterface.

Elke opdracht moet een groep als bovenliggende groep hebben, zelfs als dit het enige onderdeel in die groep is. Elk standaardmenu moet ook een bovenliggende groep hebben. Werkbalken en gereedschapsvensters fungeren als hun eigen ouders. Een groep kan als bovenliggend element de hoofdmenubalk van Visual Studio hebben, of een menu, werkbalk of toolvenster.

Hoe items worden gedefinieerd

Een VSCT-bestand is opgemaakt in XML. Hiermee worden de UI-elementen voor een pakket gedefinieerd en wordt bepaald waar deze elementen worden weergegeven in de IDE. Aan elk menu, elke groep of opdracht in het pakket wordt eerst een GUID en id in de Symbols sectie toegewezen. In de rest van het .vsct-bestand wordt elk menu, elke opdracht en groep geïdentificeerd door de GUID- en ID-combinatie. In het volgende voorbeeld ziet u een typische Symbols sectie die wordt gegenereerd door de Visual Studio-pakketsjabloon wanneer een menuopdracht is geselecteerd in de sjabloon.

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

Het element op het hoogste niveau van de Symbols sectie is het guidSymbol-element. GuidSymbol elementen wijzen namen toe aan GUID's die door de IDE worden gebruikt om pakketten en de bijbehorende onderdelen te identificeren.

Opmerking

GUID's worden automatisch gegenereerd door de Visual Studio-pakketsjabloon. U kunt ook een unieke GUID maken door te klikken op Unieke GUID maken in het menu Extra.

Het eerste GuidSymbol element, guid<PackageName>Pkgis de GUID van het pakket zelf. Dit is de GUID die door Visual Studio wordt gebruikt om het pakket te laden. Normaal gesproken bevat het geen onderliggende elementen.

Standaard worden menu's en opdrachten gegroepeerd onder een tweede GuidSymbol element, guid<PackageName>CmdSeten bitmaps bevinden zich onder een derde GuidSymbol element. guidImages U hoeft deze conventie niet te volgen, maar elk menu, elke groep, opdracht en bitmap moet een onderliggend GuidSymbol element zijn.

In het tweede GuidSymbol element, dat de pakketopdrachtset vertegenwoordigt, zijn verschillende IDSymbol elementen. Elk ELEMENT IDSymbol wijst een naam toe aan een numerieke waarde en kan een menu, groep of opdracht vertegenwoordigen die deel uitmaakt van de opdrachtenset. De IDSymbol elementen in het derde GuidSymbol element vertegenwoordigen bitmaps die kunnen worden gebruikt als pictogrammen voor opdrachten. Omdat GUID-/id-paren uniek moeten zijn in een toepassing, hebben geen twee onderliggende elementen van hetzelfde GuidSymbol element mogelijk dezelfde waarde.

Wanneer een menu, groep of opdracht een GUID en id heeft, kan deze worden toegevoegd aan de IDE. Elk UI-element moet de volgende zaken hebben:

  • Een guid kenmerk dat overeenkomt met de naam van het GuidSymbol element waaronder het UI-element is gedefinieerd.

  • Een id kenmerk dat overeenkomt met de naam van het gekoppelde IDSymbol element.

Samen vormen de guid en id kenmerken de handtekening van het ui-element.

  • Een priority kenmerk dat de plaatsing van het UI-element in het bovenliggende menu of de bovenliggende groep bepaalt.

  • Een bovenliggend element dat de guid en id attributen heeft, die de handtekening van het bovenliggende menu of de bovenliggende groep specificeren.

Elk menu wordt gedefinieerd als een menu-element in de Menus sectie. Menu's moeten de attributen guid, id, priority en een Parent element hebben, alsook de volgende extra attributen en onderliggende elementen:

  • Een type kenmerk dat aangeeft of het menu moet worden weergegeven in de IDE als een soort menu of als werkbalk.

  • Een tekenreekselement dat een ButtonText-element bevat, waarmee de titel van het menu in de IDE wordt opgegeven en een CommandName-element, waarmee de naam wordt opgegeven die wordt gebruikt in het opdrachtvenster voor toegang tot het menu.

  • Optionele vlaggen. Een CommandFlag-element kan worden weergegeven in een menudefinitie om het uiterlijk of gedrag ervan in de IDE te wijzigen.

Elk Menu-element moet als bovenliggend element een groep hebben, tenzij het een verankerbaar element is, zoals een werkbalk. Een koppelbaar menu is zijn eigen ouder. Zie type voor menu-elementen voor meer informatie over menu's en waarden voor het kenmerk.

In het volgende voorbeeld ziet u een menu dat wordt weergegeven op de menubalk van Visual Studio, naast het menu Extra .

<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

Een groep is een item dat is gedefinieerd in de Groups sectie van het VSCT-bestand . Groepen zijn slechts containers. Ze worden niet weergegeven in de IDE, behalve als een scheidingslijn in een menu. Daarom wordt een groepselement alleen gedefinieerd door de handtekening, prioriteit en het bovenliggende element.

Een groep kan een menu, een andere groep of zichzelf als bovenliggend item hebben. Het bovenliggende item is echter meestal een menu of werkbalk. Het menu in het eerdere voorbeeld is een onderliggend element van de IDG_VS_MM_TOOLSADDINS groep en die groep is een onderliggend element van de menubalk van Visual Studio. De groep in het volgende voorbeeld is een onderliggend element van het menu in het eerdere voorbeeld.

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

Omdat deze groep deel uitmaakt van een menu, bevat deze groep meestal opdrachten. Het kan echter ook andere menu's bevatten. Dit is hoe submenu's worden gedefinieerd, zoals wordt weergegeven in het volgende voorbeeld.

<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

Een opdracht die aan de IDE wordt geleverd, wordt gedefinieerd als een knopelement of een combinatie-element. Om in een menu of werkbalk te verschijnen, moet de opdracht een groep als ouder hebben.

Buttons

Knoppen worden gedefinieerd in de Buttons sectie. Een menu-item, knop of ander element waarop een gebruiker klikt om één opdracht uit te voeren, wordt beschouwd als een knop. Sommige knoptypen kunnen ook lijstfunctionaliteit bevatten. Knoppen hebben dezelfde vereiste en optionele kenmerken die menu's hebben en kunnen ook een pictogramelement hebben waarmee de GUID en id van de bitmap worden opgegeven die de knop in de IDE vertegenwoordigt. Zie de documentatie voor knoppenelement voor meer informatie over knoppen en hun kenmerken.

De knop in het volgende voorbeeld is een onderliggend element van de groep in het eerdere voorbeeld en wordt in de IDE weergegeven als een menu-item in het bovenliggende menu van die groep.

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

Combinaties worden gedefinieerd in de Combos sectie. Elk Combo element vertegenwoordigt een vervolgkeuzelijst in de IDE. De keuzelijst kan wel of niet beschrijfbaar zijn door gebruikers, afhankelijk van de waarde van het type kenmerk van de combinatie. Combinaties hebben dezelfde elementen en hetzelfde gedrag als knoppen en kunnen ook de volgende extra kenmerken hebben:

  • Een defaultWidth kenmerk dat pixelbreedte aangeeft.

  • Een idCommandList kenmerk waarmee een lijst wordt opgegeven die de items bevat die in de keuzelijst worden weergegeven. De opdrachtlijst moet worden gedeclareerd in hetzelfde GuidSymbol knooppunt dat de combinatie bevat.

In het volgende voorbeeld wordt een combinatie-element gedefinieerd.

<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

Opdrachten die samen met een pictogram worden weergegeven, moeten een Icon element bevatten dat verwijst naar een bitmap met behulp van de GUID en id. Elke bitmap wordt gedefinieerd als bitmapelement in de Bitmaps sectie. De enige vereiste kenmerken voor een Bitmap definitie zijn guid en href, die naar het bronbestand verwijst. Als het bronbestand een resourcestrip is, is ook een usedList-kenmerk vereist om de afbeeldingen in de strip beschikbaar te maken. Zie de documentatie voor bitmapelementen voor meer informatie.

Ouderschap

De volgende regels bepalen hoe een item een ander item kan aanroepen als bovenliggend item.

Onderdeel Gedefinieerd in deze sectie van de opdrachttabel Kan zijn opgenomen (als ouderitem of door plaatsing ervan in de CommandPlacements sectie, of beide) Mag bevatten (ook wel een bovenliggend element genoemd)
Groep Het element Groepen, de IDE, andere VSPackages Een menu, een groep, het item zelf Menu's, groepen en opdrachten
Menulijst Menu-element, de IDE, andere VSPackages 1 tot n groepen 0 tot n groepen
Werkbalk Menu-element, de IDE, andere VSPackages Het item zelf 0 tot n groepen
Menuoptie Knoppenelement, de IDE, andere VSPackages 1 tot n groepen, het item zelf -0 tot n groepen
Knop Knoppenelement, de IDE, andere VSPackages 1 tot n groepen, het item zelf
Combo Combos-element, de IDE, andere VSPackages 1 tot n groepen, het item zelf

Een menu, groep of opdracht kan op meer dan één locatie in de IDE worden weergegeven. Als u een item op meerdere locaties wilt weergeven, moet het als CommandPlacements aan de sectie worden toegevoegd. Een menu, groep of opdracht kan worden toegevoegd als opdrachtplaatsing. Werkbalken kunnen echter niet op deze manier worden geplaatst omdat ze niet op meerdere contextgevoelige locaties kunnen worden weergegeven.

Opdrachtplaatsingen hebben guid, iden priority kenmerken. De GUID en id moeten overeenkomen met die van het item dat is positioneerd. Het priority kenmerk bepaalt de plaatsing van het item met betrekking tot andere items. Wanneer de IDE twee of meer items met dezelfde prioriteit samenvoegt, zijn hun plaatsingen niet gedefinieerd omdat de IDE niet garandeert dat pakketresources in dezelfde volgorde worden gelezen telkens wanneer het pakket wordt gebouwd.

Als een menu of groep op meerdere locaties wordt weergegeven, zullen alle kinderen van dat menu of die groep in elk voorbeeld worden weergegeven.

Zichtbaarheid en context van opdracht

Wanneer meerdere VSPackages zijn geïnstalleerd, kan een overvloed aan menu's, menu-items en werkbalken de IDE overladen. U kunt dit probleem voorkomen door de zichtbaarheid van afzonderlijke UI-elementen te beheren met behulp van zichtbaarheidsbeperkingen en opdrachtvlagmen.

Zichtbaarheidsbeperkingen

Een zichtbaarheidsbeperking wordt ingesteld als een VisibilityItem-element in de VisibilityConstraints sectie. Een zichtbaarheidsbeperking definieert specifieke UI-contexten waarin het doelitem zichtbaar is. Een menu of opdracht die in deze sectie is opgenomen, is alleen zichtbaar wanneer een van de gedefinieerde contexten actief is. Als in deze sectie niet naar een menu of opdracht wordt verwezen, is dit altijd standaard zichtbaar. Deze sectie is niet van toepassing op groepen.

VisibilityItem elementen moeten drie attributen hebben, namelijk de guid en id van het doel-UI-element, en context. Het context kenmerk geeft aan wanneer het doelitem zichtbaar is en gebruikt een geldige UI-context als waarde. De contextconstanten van de gebruikersinterface voor Visual Studio zijn lid van de VSConstants klasse. Elk VisibilityItem element kan slechts één contextwaarde aannemen. Als u een tweede context wilt toepassen, maakt u een tweede VisibilityItem element dat verwijst naar hetzelfde item, zoals wordt weergegeven in het volgende voorbeeld.

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

Opdrachtvlagmen

De volgende opdrachtvlagmen kunnen van invloed zijn op de zichtbaarheid van de menu's en opdrachten waarvoor ze van toepassing zijn.

AlwaysCreate Het menu wordt gemaakt, zelfs als het geen groepen of knoppen bevat.

Geldig voor: Menu

CommandWellOnly Pas deze vlag toe als de opdracht niet wordt weergegeven in het menu op het hoogste niveau en u deze beschikbaar wilt maken voor extra shellaanpassing, bijvoorbeeld door deze aan een sleutel te koppelen. Nadat de VSPackage is geïnstalleerd, kan een gebruiker deze opdrachten aanpassen door het dialoogvenster Opties te openen en vervolgens de plaatsing van de opdracht onder de categorie Toetsenbordomgeving te bewerken. Heeft geen invloed op de plaatsing van snelkoppelmenu's, werkbalken, menubedieningspanelen of submenu's.

Geldig voor: Button, Combo

DefaultDisabled De opdracht is standaard uitgeschakeld als de VSPackage waarmee de opdracht wordt geïmplementeerd, niet is geladen of als de QueryStatus-methode niet is aangeroepen.

Geldig voor: Button, Combo

DefaultInvisible De opdracht is standaard onzichtbaar als de VSPackage waarmee de opdracht wordt geïmplementeerd, niet is geladen of als de QueryStatus-methode niet is aangeroepen.

Moet worden gecombineerd met de DynamicVisibility vlag.

Geldig voor: Button, ComboMenu

DynamicVisibility De zichtbaarheid van de opdracht kan worden gewijzigd met behulp van de QueryStatus methode of een context-GUID die is opgenomen in de VisibilityConstraints sectie.

Van toepassing op opdrachten die worden weergegeven in menu's, niet op werkbalken. Werkbalkitems op het hoogste niveau kunnen worden uitgeschakeld, maar niet verborgen wanneer de OLECMDF_INVISIBLE vlag wordt geretourneerd vanuit de QueryStatus methode.

In een menu geeft deze vlag ook aan dat deze automatisch moet worden verborgen wanneer de onderdelen zijn verborgen. Deze vlag wordt doorgaans toegewezen aan submenu's omdat menu's op het hoogste niveau dit gedrag al hebben.

Moet worden gecombineerd met de DefaultInvisible vlag.

Geldig voor: Button, ComboMenu

NoShowOnMenuController Als een opdracht met deze vlag op een menucontroller is geplaatst, wordt de opdracht niet weergegeven in de vervolgkeuzelijst.

Geldig voor: Button

Zie de commandFlag-elementdocumentatie voor meer informatie over opdrachtvlag-vlaggen.

Algemene vereisten

Uw opdracht moet voldoen aan de volgende reeks tests voordat deze kan worden weergegeven en ingeschakeld:

  • De opdracht is correct gepositioneerd.

  • De DefaultInvisible vlag is niet ingesteld.

  • Het bovenliggende menu of de werkbalk is zichtbaar.

  • De opdracht is niet onzichtbaar vanwege een contextvermelding in de sectie VisibilityConstraints-element .

  • VSPackage-code die de IOleCommandTarget interface implementeert, geeft uw opdracht weer en schakelt deze in. Geen interfacecode heeft het onderschept en er actie op ondernomen.

  • Wanneer een gebruiker op uw opdracht klikt, wordt deze onderworpen aan de procedure die wordt beschreven in het routeringsalgoritmen.

Vooraf gedefinieerde opdrachten aanroepen

Met het element UsedCommands kunnen VSPackages toegang krijgen tot opdrachten die worden geleverd door andere VSPackages of door de IDE. Hiervoor maakt u een UsedCommand-element met de GUID en id van de opdracht die u wilt gebruiken. Dit zorgt ervoor dat de opdracht wordt geladen door Visual Studio, zelfs als deze geen deel uitmaakt van de huidige Visual Studio-configuratie. Zie Het element UsedCommand voor meer informatie.

Uiterlijk van interface-element

Overwegingen voor het selecteren en positioneren van opdrachtelementen zijn als volgt:

  • Visual Studio biedt veel UI-elementen die verschillend worden weergegeven, afhankelijk van de plaatsing.

  • Een UI-element dat is gedefinieerd met behulp van de DefaultInvisible vlag, wordt niet weergegeven in de IDE, tenzij het wordt weergegeven door de VSPackage-implementatie van de QueryStatus methode of gekoppeld aan een bepaalde UI-context in de VisibilityConstraints sectie.

  • Zelfs een succesvol geplaatste opdracht wordt mogelijk niet weergegeven. Dit komt doordat de IDE automatisch bepaalde opdrachten verbergt of weergeeft, afhankelijk van interfaces die de VSPackage heeft (of niet) heeft geïmplementeerd. De implementatie van een VSPackage van sommige buildinterfaces zorgt er bijvoorbeeld voor dat menu-items die betrekking hebben op de build automatisch worden weergegeven.

  • Het toepassen van de CommandWellOnly vlag in de definitie van het UI-element betekent dat de opdracht alleen kan worden toegevoegd door aanpassing.

  • Opdrachten zijn mogelijk alleen beschikbaar in bepaalde UI-contexten, bijvoorbeeld alleen wanneer een dialoogvenster wordt weergegeven wanneer de IDE zich in de ontwerpweergave bevindt.

  • Als u wilt dat bepaalde UI-elementen worden weergegeven in de IDE, moet u een of meer interfaces implementeren of code schrijven.

Verwante inhoud

  • Last updated on