Så här lägger VSPackages till användargränssnittselement

En VSPackage kan lägga till användargränssnittselement (UI), till exempel menyer, verktygsfält och verktygsfönster, till Visual Studio med hjälp av .vsct-filen .

Du hittar designriktlinjer för gränssnittselement i Riktlinjer för användarupplevelse i Visual Studio.

Visual Studio-kommandotabellarkitekturen

Som nämnts stöder kommandotabellarkitekturen ovanstående arkitekturprinciper. Grundsatserna bakom abstraktionerna, datastrukturerna och verktygen i kommandotabellarkitekturen är följande:

• Det finns tre grundläggande typer av objekt: menyer, kommandon och grupper. Menyer kan visas i användargränssnittet som menyer, undermenyer, verktygsfält eller verktygsfönster. Kommandon är procedurer som användaren kan köra i IDE och de kan exponeras som menyalternativ, knappar, listrutor eller andra kontroller. Grupper är containrar för både menyer och kommandon.

• Varje objekt anges av en definition som beskriver objektet, dess prioritet i förhållande till andra objekt och flaggorna som ändrar dess beteende.

• Varje objekt har en placering som beskriver objektets föräldraobjekt. Ett objekt kan ha flera överordnade objekt, så att det kan visas på flera platser i användargränssnittet.

Varje kommando måste ha en grupp som föräldragrupp, även om det är det enda barnet i den gruppen. Varje standardmeny måste också ha en överordnad grupp. Verktygsfält och verktygsfönster fungerar som sina egna föräldrar. En grupp kan som överordnad ha huvudmenyn i Visual Studio, eller valfri meny, verktygsfält eller verktygsfönster.

Hur objekt definieras

En .vsct-fil är formaterad i XML. Den definierar gränssnittselementen för ett paket och avgör var dessa element visas i IDE:t. Varje meny, grupp eller kommando i paketet tilldelas först ett GUID och ID i Symbols avsnittet. I resten av .vsct-filen identifieras varje meny, kommando och grupp med dess kombination av GUID och ID. I följande exempel visas ett typiskt Symbols avsnitt som genereras av Visual Studio-paketmallen när ett menykommando väljs i mallen.

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

Det översta elementet i Symbols avsnittet är GuidSymbol-elementet. GuidSymbol element mappar namn till GUID:er som används av IDE för att identifiera paket och deras komponentdelar.

Det första GuidSymbol elementet, guid<PackageName>Pkg, är GUID för själva paketet. Det här är det GUID som används av Visual Studio för att läsa in paketet. Vanligtvis har den inte underordnade element.

Enligt konventionen grupperas menyer och kommandon under ett andra GuidSymbol element, guid<PackageName>CmdSet, och bitmappar är under ett tredje GuidSymbol element, guidImages. Du behöver inte följa den här konventionen, men varje meny, grupp, kommando och bitmapp måste vara underordnad ett GuidSymbol element.

I det andra GuidSymbol elementet, som representerar paketkommandouppsättningen, finns flera IDSymbol element. Varje IDSymbol-element mappar ett namn till ett numeriskt värde och kan representera en meny, grupp eller ett kommando som ingår i kommandouppsättningen. Elementen IDSymbol i det tredje GuidSymbol elementet representerar bitmappar som kan användas som ikoner för kommandon. Eftersom GUID/ID-par måste vara unika i ett program får inga två underordnade element till samma GuidSymbol element ha samma värde.

Menyer, grupper och kommandon

När en meny, grupp eller kommando har ett GUID och ID kan den läggas till i IDE:t. Varje gränssnittselement måste ha följande:

• Ett guid attribut som matchar namnet på GuidSymbol det element som användargränssnittselementet definieras under.

• Ett id attribut som matchar namnet på det associerade IDSymbol elementet.

Tillsammans utgör attributen guid och idsignaturen för användargränssnittselementet.

• Ett priority attribut som avgör placeringen av användargränssnittselementet i den överordnade menyn eller gruppen.

• Ett överordnat element som har guid och id attribut som anger signaturen för den överordnade menyn eller gruppen.

Menyer

Varje meny definieras som ett menyelement i Menus avsnittet. Menyer måste ha guid, id och priority attribut, och ett Parent element, och även följande ytterligare attribut och barn:

• Ett type attribut som anger om menyn ska visas i IDE som en typ av meny eller som ett verktygsfält.

• Ett Strings-element som innehåller ett ButtonText-element, som anger rubriken på menyn i IDE och ett CommandName-element, som anger det namn som används i kommandofönstret för att komma åt menyn.

• Valfria flaggor. Ett CommandFlag-element kan visas i en menydefinition för att ändra dess utseende eller beteende i IDE.

Varje Menu element måste ha en grupp som överordnad, såvida det inte är ett dockbart element, till exempel ett verktygsfält. En dockbar meny är en egen överordnad meny. Mer information om menyer och värden för type attributet finns i dokumentationen för menyelement.

I följande exempel visas en meny som visas på menyraden i Visual Studio bredvid menyn Verktyg .

<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

En grupp är ett objekt som definieras i avsnittet i Groups.vsct-filen . Grupper är bara containrar. De visas inte i IDE förutom som en skiljelinje på en meny. Därför definieras ett gruppelement endast av dess signatur, prioritet och överordnade element.

En grupp kan ha en meny, en annan grupp eller sig själv som överordnad. Det överordnade elementet är dock vanligtvis en meny eller ett verktygsfält. Menyn i det tidigare exemplet är underordnad gruppen IDG_VS_MM_TOOLSADDINS och den gruppen är underordnad menyraden i Visual Studio. Gruppen i följande exempel är underordnad menyn i det tidigare exemplet.

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

Eftersom den ingår i en meny innehåller den här gruppen vanligtvis kommandon. Den kan dock också innehålla andra menyer. Så här definieras undermenyer, som du ser i följande exempel.

<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

Ett kommando som tillhandahålls till IDE definieras som antingen ett knappelement eller ett kombinationselement. Om du vill visas på en meny eller ett verktygsfält måste kommandot ha en grupp som överordnad.

Buttons

Knappar definieras i avsnittet Buttons . Alla menyalternativ, knappar eller andra element som en användare klickar på för att köra ett enda kommando betraktas som en knapp. Vissa knapptyper kan också innehålla listfunktioner. Knappar har samma obligatoriska och valfria attribut som menyerna har, och kan också ha ett ikonelement som anger GUID och ID för bitmappen som representerar knappen i IDE. Mer information om knappar och deras attribut finns i dokumentationen för elementet Knappar .

Knappen i följande exempel är underordnad gruppen i det tidigare exemplet och visas i IDE som ett menyalternativ på den överordnade menyn i gruppen.

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

Kombinationer

Kombinationer definieras i avsnittet Combos . Varje Combo element representerar en rullgardinsmeny i IDE:n. Listrutan kan skrivas av användare beroende på kombinationsrutans type-attributvärde. Kombinationer har samma element och beteende som knapparna har och kan också ha följande ytterligare attribut:

• Ett defaultWidth attribut som anger pixelbredd.

• Ett idCommandList attribut som anger en lista som innehåller de objekt som visas i listrutan. Kommandolistan måste deklareras i samma GuidSymbol nod som innehåller kombinationsrutan.

I följande exempel definieras ett kombinationselement.

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

Bitmappar

Kommandon som ska visas tillsammans med en ikon måste innehålla ett Icon element som refererar till en bitmapp med hjälp av dess GUID och ID. Varje bitmapp definieras som ett Bitmap-element i Bitmaps avsnittet. De enda obligatoriska attributen för en Bitmap definition är guid och href, som pekar på källfilen. Om källfilen är en resursremsa krävs även ett usedList-attribut för att visa de tillgängliga bilderna i remsan. Mer information finns i dokumentationen för Bitmap-element.

Föräldraskap

Följande regler styr hur ett objekt kan anropa ett annat objekt som överordnat objekt.

Meny, kommando och gruppplacering

En meny, grupp eller ett kommando kan visas på mer än en plats i IDE. För att ett objekt ska visas på flera platser måste det läggas till i CommandPlacements avsnittet som ett CommandPlacement-element. Valfri meny, grupp eller kommando kan läggas till som en kommandoplacering. Verktygsfält kan dock inte placeras på det här sättet eftersom de inte kan visas på flera sammanhangskänsliga platser.

Kommandoplaceringar har guidattributen , idoch priority . GUID och ID måste överensstämma med dem för det objekt som är placerat. Attributet priority styr placeringen av objektet när det gäller andra objekt. När IDE sammanfogar två eller flera objekt som har samma prioritet är deras placeringar odefinierade eftersom IDE:n inte garanterar att paketresurser läse i samma ordning varje gång paketet skapas.

Om en meny eller grupp visas på flera platser visas alla underordnade i den menyn eller gruppen i varje förekomst.

Kommandots synlighet och kontext

När flera VSPackages installeras kan en mängd menyer, menyalternativ och verktygsfält göra IDE:t rörigt. För att undvika det här problemet kan du styra synligheten för enskilda användargränssnittselement med hjälp av synlighetsbegränsningar och kommandoflaggor.

Synlighetsbegränsningar

En synlighetsbegränsning anges som ett VisibilityItem-element i VisibilityConstraints avsnittet. En synlighetsbegränsning definierar specifika användargränssnittskontexter där målobjektet är synligt. En meny eller ett kommando som ingår i det här avsnittet visas bara när en av de definierade kontexterna är aktiv. Om en meny eller ett kommando inte refereras till i det här avsnittet visas den alltid som standard. Det här avsnittet gäller inte för grupper.

VisibilityItem element måste ha tre attribut, enligt följande: guid och id för målgränssnittselementet och context. Attributet context anger när målobjektet ska vara synligt och tar alla giltiga användargränssnittskontexter som värde. Användargränssnittets kontextkonstanter för Visual Studio är medlemmar i VSConstants klassen. Varje VisibilityItem element kan bara ha ett kontextvärde. Om du vill använda en andra kontext skapar du ett andra VisibilityItem element som pekar på samma objekt, som du ser i följande exempel.

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

Kommandoflaggor

Följande kommandoflaggor kan påverka synligheten för menyer och kommandon som de gäller för.

AlwaysCreate Menyn skapas även om den inte har några grupper eller knappar.

Giltigt för: Menu

CommandWellOnly Använd den här flaggan om kommandot inte visas på menyn på den översta nivån och du vill göra den tillgänglig för ytterligare gränssnittsanpassning, till exempel genom att binda den till en nyckel. När VSPackage har installerats kan en användare anpassa dessa kommandon genom att öppna dialogrutan Alternativ och sedan redigera kommandoplaceringen under kategorin Tangentbordsmiljö . Påverkar inte placeringen på snabbmenyer, verktygsfält, menykontrollanter eller undermenyer.

Giltigt för: Button, Combo

DefaultDisabled Som standard inaktiveras kommandot om VSPackage som implementerar kommandot inte läses in eller om QueryStatus-metoden inte har anropats.

Giltigt för: Button, Combo

DefaultInvisible Som standard är kommandot osynligt om VSPackage som implementerar kommandot inte läses in eller om QueryStatus-metoden inte har anropats.

Ska kombineras med DynamicVisibility flaggan.

Giltigt för: Button, Combo, Menu

DynamicVisibility Du kan ändra kommandots synlighet med hjälp av metoden QueryStatus eller ett kontext-GUID som ingår i VisibilityConstraints avsnittet.

Gäller för kommandon som visas på menyer, inte i verktygsfält. Objekt i verktygsfältet på den översta nivån kan inaktiveras, men inte döljas, när OLECMDF_INVISIBLE flaggan returneras från QueryStatus -metoden.

På en meny anger den här flaggan också att den ska döljas automatiskt när dess medlemmar är dolda. Den här flaggan tilldelas vanligtvis till undermenyer eftersom menyer på den översta nivån redan har det här beteendet.

Ska kombineras med DefaultInvisible flaggan.

Giltigt för: Button, Combo, Menu

NoShowOnMenuController Om ett kommando som har den här flaggan är placerat på en menykontrollant visas inte kommandot i listrutan.

Giltigt för: Button

Mer information om kommandoflaggor finns i dokumentationen för CommandFlag-elementet .

Allmänna krav

Kommandot måste klara följande serie tester innan det kan visas och aktiveras:

• Kommandot är korrekt placerat.

• Flaggan DefaultInvisible har inte angetts.

• Den överordnade menyn eller verktygsfältet visas.

• Kommandot är inte osynligt på grund av en kontextpost i elementavsnittet VisibilityConstraints .

• VSPackage-kod som implementerar IOleCommandTarget gränssnittet visar och aktiverar kommandot. Ingen gränssnittskod snappade upp den och agerade på den.

• När en användare klickar på kommandot blir det föremål för den procedur som beskrivs i routningsalgoritmen.

Anropa fördefinierade kommandon

Elementet UsedCommands gör det möjligt för VSPackages att komma åt kommandon som tillhandahålls av andra VSPackages eller av IDE. Det gör du genom att skapa ett UsedCommand-element som har GUID och ID för kommandot som ska användas. Detta säkerställer att kommandot läses in av Visual Studio, även om det inte ingår i den aktuella Visual Studio-konfigurationen. Mer information finns i UsedCommand-element.

Gränssnittselementsutseende

Överväganden för att välja och placera kommandoelement är följande:

• Visual Studio erbjuder många gränssnittselement som visas olika beroende på placering.

• Ett gränssnittselement som definieras med hjälp DefaultInvisible av flaggan visas inte i IDE:t om det inte antingen visas av vsPackage-implementeringen av QueryStatus metoden eller associeras med en viss användargränssnittskontext i VisibilityConstraints avsnittet.

• Även ett kommando som har placerats korrekt kanske inte visas. Detta beror på att IDE automatiskt döljer eller visar vissa kommandon, beroende på gränssnitt som VSPackage har (eller inte har) implementerat. En VSPackage-implementering av vissa bygggränssnitt gör till exempel att byggrelaterade menyobjekt visas automatiskt.

• CommandWellOnly Om du använder flaggan i definitionen av UI-elementet innebär det att kommandot bara kan läggas till genom anpassning.

• Kommandon kan endast vara tillgängliga i vissa användargränssnittskontexter, till exempel endast när en dialogruta visas när IDE:en är i designvyn.

• Om du vill att vissa gränssnittselement ska visas i IDE måste du implementera ett eller flera gränssnitt eller skriva kod.

Relaterat innehåll

• Utöka menyer och kommandon