Sdílet prostřednictvím

Jak balíčky VSPackage přidávají prvky uživatelského rozhraní

  • Článek

Balíček VSPackage může do sady Visual Studio přidat prvky uživatelského rozhraní, například nabídky, panely nástrojů a okna nástrojů, pomocí souboru .vsct .

Pokyny k návrhu prvků uživatelského rozhraní najdete v pokynech k uživatelskému prostředí sady Visual Studio.

Architektura tabulky příkazů sady Visual Studio

Jak je uvedeno, architektura tabulky příkazů podporuje výše uvedené principy architektury. Principy abstrakcí, datových struktur a nástrojů architektury tabulek příkazů jsou následující:

  • Existují tři základní druhy položek: nabídky, příkazy a skupiny. Nabídky se dají v uživatelském rozhraní zpřístupnit jako nabídky, podnabídky, panely nástrojů nebo okna nástrojů. Příkazy jsou procedury, které může uživatel spustit v integrovaném vývojovém prostředí (IDE) a dají se zobrazit jako položky nabídky, tlačítka, seznamy nebo jiné ovládací prvky. Skupiny jsou kontejnery pro nabídky i příkazy.

  • Každá položka je určena definicí, která popisuje položku, její prioritu vzhledem k jiným položkám a příznaky, které mění jeho chování.

  • Každá položka má umístění, které popisuje nadřazenou položku. Položka může mít více nadřazených prvků, aby se v uživatelském rozhraní zobrazovala v několika umístěních.

Každý příkaz musí mít skupinu jako nadřazenou, i když je to jediná podřízená položka v této skupině. Každá standardní nabídka musí mít také nadřazenou skupinu. Panely nástrojů a okna nástrojů fungují jako jejich vlastní rodiče. Skupina může mít jako nadřazený hlavní řádek nabídek sady Visual Studio nebo jakoukoli nabídku, panel nástrojů nebo okno nástrojů.

Jak jsou definovány položky

Soubor .vsct je formátován v jazyce XML. Definuje prvky uživatelského rozhraní pro balíček a určuje, kde se tyto prvky v integrovaném vývojovém prostředí zobrazují. Každá nabídka, skupina nebo příkaz v balíčku má v oddílu Symbols nejprve přiřazený identifikátor GUID a ID. Ve zbytku souboru .vsct se jednotlivé nabídky, příkazy a skupiny identifikují pomocí kombinace identifikátorů GUID a ID. Následující příklad ukazuje typickou Symbols část vygenerovanou šablonou balíčku sady Visual Studio při výběru příkazu nabídky v šabloně.

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

Prvek nejvyšší úrovně oddílu Symbolsje GuidSymbol element. GuidSymbol elementy mapují názvy na identifikátory GUID, které rozhraní IDE používá k identifikaci balíčků a jejich součástí.

Poznámka:

Identifikátory GUID se generují automaticky pomocí šablony balíčku sady Visual Studio. Jedinečný identifikátor GUID můžete vytvořit také kliknutím na Vytvořit identifikátor GUID v nabídce Nástroje .

První GuidSymbol prvek, guid<PackageName>Pkgje IDENTIFIKÁTOR GUID samotného balíčku. Toto je identifikátor GUID, který sada Visual Studio používá k načtení balíčku. Obvykle neobsahuje podřízené prvky.

Podle konvence jsou nabídky a příkazy seskupeny pod druhým GuidSymbol prvkem guid<PackageName>CmdSeta rastrové obrázky jsou pod třetím GuidSymbol prvkem, guidImages. Nemusíte postupovat podle této konvence, ale každá nabídka, skupina, příkaz a rastrový obrázek musí být podřízeným prvkem GuidSymbol .

Ve druhém GuidSymbol prvku, který představuje sadu příkazů balíčku, je několik IDSymbol prvků. Každý prvek IDSymbol mapuje název na číselnou hodnotu a může představovat nabídku, skupinu nebo příkaz, který je součástí sady příkazů. Prvky IDSymbol ve třetím GuidSymbol prvku představují rastrové obrázky, které lze použít jako ikony pro příkazy. Vzhledem k tomu, že páry GUID/ID musí být v aplikaci jedinečné, nemusí mít žádné dvě podřízené položky stejného GuidSymbol prvku stejnou hodnotu.

Pokud má nabídka, skupina nebo příkaz identifikátor GUID a ID, můžete ho přidat do integrovaného vývojového prostředí (IDE). Každý prvek uživatelského rozhraní musí mít následující věci:

  • Atribut guid , který odpovídá názvu GuidSymbol prvku, pod kterým je definován prvek uživatelského rozhraní.

  • Atribut id , který odpovídá názvu přidruženého IDSymbol prvku.

guid Společně a id atributy tvoří podpis prvku uživatelského rozhraní.

  • Atribut priority , který určuje umístění prvku uživatelského rozhraní v nadřazené nabídce nebo skupině.

  • Nadřazený prvek, který má guid a id atributy, které určují podpis nadřazené nabídky nebo skupiny.

Každá nabídka je definována jako prvek Menu v oddílu Menus . Nabídky musí obsahovat guidatributy , ida priority atributy a Parent element a také následující další atributy a podřízené položky:

  • Atribut type , který určuje, zda má být nabídka zobrazena v integrovaném vývojovém prostředí jako druh nabídky nebo jako panel nástrojů.

  • A Strings element, který obsahuje ButtonText element, který určuje název nabídky v integrovaném vývojovém prostředí a CommandName element, který určuje název, který se používá v příkazovém okně pro přístup k nabídce.

  • Volitelné příznaky. Element CommandFlag se může objevit v definici nabídky, aby se změnil jeho vzhled nebo chování v integrovaném vývojovém prostředí.

Každý Menu prvek musí mít skupinu jako nadřazenou, pokud se nejedná o dokovatelný prvek, například panel nástrojů. Dockable menu is its own parent. Další informace o nabídkách a hodnotách atributu type naleznete v dokumentaci k prvku Menu.

Následující příklad ukazuje nabídku, která se zobrazí na řádku nabídek sady Visual Studio vedle nabídky Nástroje .

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

Skupiny

Skupina je položka definovaná v Groups části souboru .vsct . Skupiny jsou jen kontejnery. Nezobrazují se v integrovaném vývojovém prostředí (IDE) s výjimkou dělicí čáry v nabídce. Proto je prvek Group definován pouze jeho podpis, priorita a nadřazený.

Skupina může mít jako nadřazenou nabídku, jinou skupinu nebo samotnou. Nadřazený objekt je však obvykle nabídkou nebo panelem nástrojů. Nabídka v předchozím příkladu je podřízenou položkou IDG_VS_MM_TOOLSADDINS skupiny a tato skupina je podřízenou položkou řádku nabídek sady Visual Studio. Skupina v následujícím příkladu je podřízenou položkou nabídky v předchozím příkladu.

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

Protože je součástí nabídky, tato skupina obvykle obsahuje příkazy. Může ale obsahovat i další nabídky. Takto jsou definovány podnabídky, jak je znázorněno v následujícím příkladu.

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

Příkazy

Příkaz, který je k dispozici integrovanému vývojovému prostředí (IDE), je definován jako element Button nebo combo element. Aby se příkaz zobrazil v nabídce nebo panelu nástrojů, musí mít jako nadřazenou skupinu.

Tlačítka

Tlačítka jsou definována v oddílu Buttons . Každá položka nabídky, tlačítko nebo jiný prvek, na který uživatel klikne, aby spustil jeden příkaz, se považuje za tlačítko. Některé typy tlačítek můžou obsahovat také funkce seznamu. Tlačítka mají stejné povinné a volitelné atributy, které mají nabídky, a mohou mít také element Icon, který určuje identifikátor GUID a ID rastrového obrázku, který představuje tlačítko v integrovaném vývojovém prostředí( IDE). Další informace o tlačítkách a jejich atributech najdete v dokumentaci k elementu Buttons.

Tlačítko v následujícím příkladu je podřízenou položkou skupiny v předchozím příkladu a zobrazí se v integrovaném vývojovém prostředí jako položka nabídky v nadřazené nabídce této skupiny.

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

Komba jsou definována Combos v části. Každý Combo prvek představuje rozevírací seznam v integrovaném vývojovém prostředí( IDE). Seznam může nebo nemusí být zapisovatelný uživateli v závislosti na hodnotě type atributu se seznamem. Komba mají stejné prvky a chování jako tlačítka a mohou mít také následující další atributy:

  • Atribut defaultWidth , který určuje šířku pixelů.

  • Atribut idCommandList , který určuje seznam obsahující položky, které jsou zobrazeny v seznamu. Seznam příkazů musí být deklarován ve stejném GuidSymbol uzlu, který obsahuje seznam.

Následující příklad definuje prvek se seznamem.

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

Příkazy, které se zobrazí společně s ikonou, musí obsahovat Icon prvek odkazující na rastrový obrázek pomocí jeho identifikátoru GUID a ID. Každý rastrový obrázek je definován jako bitmapový prvek v oddílu Bitmaps . Jediné požadované atributy definice Bitmap jsou guid a hrefkteré odkazuje na zdrojový soubor. Pokud je zdrojovým souborem pruh prostředku, vyžaduje se také atribut usedList , který vypíše dostupné obrázky v pruhu. Další informace najdete v dokumentaci k elementu Bitmap.

Rodičovství

Následující pravidla určují, jak může položka volat jinou položku jako nadřazenou položku.

Element (Prvek) Definováno v této části tabulky příkazů Může být obsažen (jako nadřazený objekt nebo umístěním v oddílu CommandPlacements nebo obojím) Může obsahovat (označuje se jako nadřazený)
Seskupit Groups – element, integrované vývojové prostředí (IDE), ostatní balíčky VSPackage Nabídka, skupina, samotná položka Nabídky, skupiny a příkazy
Nabídka Menus – element, integrované vývojové prostředí (IDE), ostatní balíčky VSPackages 1 až n skupin 0 až n skupin
Panel nástrojů Menus – element, integrované vývojové prostředí (IDE), ostatní balíčky VSPackages Samotná položka 0 až n skupin
Položka nabídky Buttons – element, integrované vývojové prostředí (IDE), ostatní balíčky VSPackages 1 až n skupin, samotná položka -0 až n skupin
Tlačítko Buttons – element, integrované vývojové prostředí (IDE), ostatní balíčky VSPackages 1 až n skupin, samotná položka
Combo Combos – element, integrované vývojové prostředí (IDE), ostatní balíčky VSPackage 1 až n skupin, samotná položka

Nabídka, skupina nebo příkaz se může v integrovaném vývojovém prostředí zobrazit ve více umístěních. Aby se položka objevila v několika umístěních, musí být přidána do oddílu CommandPlacementsjako CommandPlacement element. Libovolnou nabídku, skupinu nebo příkaz lze přidat jako umístění příkazu. Panely nástrojů však nelze tímto způsobem umístit, protože se nedají zobrazit v několika kontextových umístěních.

Umístění příkazů mají guidvlastnosti , ida priority atributy. Identifikátor GUID a ID musí odpovídat identifikátoru GUID položky, která je umístěna. Atribut priority řídí umístění položky s ohledem na ostatní položky. Když integrované vývojové prostředí (IDE) sloučí dvě nebo více položek se stejnou prioritou, jejich umístění se nedefinuje, protože integrované vývojové prostředí nezaručuje čtení prostředků balíčků ve stejném pořadí při každém sestavení balíčku.

Pokud se nabídka nebo skupina zobrazí ve více umístěních, zobrazí se v každé instanci všechny podřízené položky této nabídky nebo skupiny.

Viditelnost a kontext příkazů

Pokud je nainstalováno více balíčků VSPackage, může integrované vývojové prostředí (IDE) nepřehledné množství nabídek, položek nabídek a panelů nástrojů. Chcete-li se tomuto problému vyhnout, můžete řídit viditelnost jednotlivých prvků uživatelského rozhraní pomocí omezení viditelnosti a příznaků příkazů.

Omezení viditelnosti

Omezení viditelnosti je nastaveno jako element VisibilityItem v oddílu VisibilityConstraints . Omezení viditelnosti definuje konkrétní kontexty uživatelského rozhraní, ve kterých je cílová položka viditelná. Nabídka nebo příkaz, který je součástí tohoto oddílu, je viditelný pouze v případě, že je aktivní některý z definovaných kontextů. Pokud se na nabídku nebo příkaz v této části neodkazuje, je ve výchozím nastavení vždy viditelný. Tato část se nevztahuje na skupiny.

VisibilityItem elementy musí mít tři atributy, a to následujícím způsobem: guid a id cílový prvek uživatelského rozhraní a context. Atribut context určuje, kdy bude cílová položka viditelná, a jako hodnotu převezme libovolný platný kontext uživatelského rozhraní. Kontextové konstanty uživatelského rozhraní pro Visual Studio jsou členy VSConstants třídy. Každý VisibilityItem prvek může mít pouze jednu kontextové hodnoty. Pokud chcete použít druhý kontext, vytvořte druhý VisibilityItem prvek, který odkazuje na stejnou položku, jak je znázorněno v následujícím příkladu.

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

Příznaky příkazů

Následující příznaky příkazů můžou ovlivnit viditelnost nabídek a příkazů, na které se vztahují.

AlwaysCreate Nabídka se vytvoří i v případě, že neobsahuje žádné skupiny nebo tlačítka.

Platné pro: Menu

CommandWellOnly Tento příznak použijte, pokud se příkaz nezobrazí v nabídce nejvyšší úrovně a chcete ho zpřístupnit pro další přizpůsobení prostředí, například jeho vazbu na klíč. Po instalaci balíčku VSPackage může uživatel tyto příkazy přizpůsobit otevřením dialogového okna Možnosti a následným úpravou umístění příkazu v kategorii Prostředí klávesnice . Nemá vliv na umístění v místních nabídkách, panelech nástrojů, řadičích nabídek nebo podnabídkách.

Platné pro: Button, Combo

DefaultDisabled Ve výchozím nastavení je příkaz zakázán, pokud VSPackage, který implementuje příkaz není načten nebo QueryStatus metoda nebyla volána.

Platné pro: Button, Combo

DefaultInvisible Ve výchozím nastavení je příkaz neviditelný, pokud VSPackage, který implementuje příkaz není načten nebo QueryStatus metoda nebyla volána.

Měla by být kombinována s příznakem DynamicVisibility .

Platné pro: Button, ComboMenu

DynamicVisibility Viditelnost příkazu lze změnit pomocí QueryStatus metody nebo kontextového identifikátoru GUID, který je součástí oddílu VisibilityConstraints .

Platí pro příkazy, které se zobrazují v nabídkách, ne na panelech nástrojů. Položky panelu nástrojů nejvyšší úrovně mohou být zakázány, ale ne skryté, pokud OLECMDF_INVISIBLE je příznak vrácen z QueryStatus metody.

V nabídce tento příznak také označuje, že by měl být automaticky skrytý, když jsou jeho členové skryti. Tento příznak je obvykle přiřazen k podnabídce, protože nabídky nejvyšší úrovně už toto chování mají.

Měla by být kombinována s příznakem DefaultInvisible .

Platné pro: Button, ComboMenu

NoShowOnMenuController Pokud je příkaz s tímto příznakem umístěný v kontroleru nabídek, příkaz se v rozevíracím seznamu nezobrazí.

Platné pro: Button

Další informace o příznakech příkazů naleznete v dokumentaci k elementu CommandFlag.

Obecné požadavky

Příkaz musí před zobrazením a povolením projít následující řadou testů:

  • Příkaz se správně umístí.

  • Příznak DefaultInvisible není nastavený.

  • Zobrazí se nadřazená nabídka nebo panel nástrojů.

  • Příkaz není neviditelný kvůli kontextové položce v oddílu elementu VisibilityConstraints.

  • Kód VSPackage, který implementuje IOleCommandTarget rozhraní, zobrazí a povolí váš příkaz. Kód rozhraní ho nezachytil a zachytil ho.

  • Když uživatel klikne na váš příkaz, bude podléhat postupu popsanému v algoritmu směrování.

Volání předdefinovaných příkazů

Element UsedCommands umožňuje VSPackages přistupovat k příkazům, které poskytují jiné balíčky VSPackage nebo integrované vývojové prostředí (IDE). Chcete-li to provést, vytvořte UsedCommand element , který má identifikátor GUID a ID příkazu použít. Tím se zajistí, že se příkaz načte sadou Visual Studio, i když není součástí aktuální konfigurace sady Visual Studio. Další informace naleznete v tématu UsedCommand element.

Vzhled elementu rozhraní

Důležité informace o výběru a umístění prvků příkazů jsou následující:

  • Visual Studio nabízí mnoho prvků uživatelského rozhraní, které se v závislosti na umístění zobrazují odlišně.

  • Prvek uživatelského rozhraní, který je definován pomocí příznaku DefaultInvisible , nebude zobrazen v integrovaném vývojovém prostředí, pokud není zobrazen jeho implementací QueryStatus VSPackage metody nebo přidružený k určitému kontextu uživatelského rozhraní v oddílu VisibilityConstraints .

  • Nemusí se zobrazit ani úspěšně umístěný příkaz. Důvodem je to, že integrované vývojové prostředí (IDE) automaticky skryje nebo zobrazí některé příkazy v závislosti na rozhraních, která má balíček VSPackage (nebo nemá) implementovaný. Například implementace VSPackage některých rozhraní sestavení způsobí automatické zobrazení položek nabídky související s sestavením.

  • Použití příznaku CommandWellOnly v definici prvku uživatelského rozhraní znamená, že příkaz lze přidat pouze vlastním nastavením.

  • Příkazy můžou být dostupné jenom v určitých kontextech uživatelského rozhraní, například pouze v případě, že se zobrazí dialogové okno, když je integrované vývojové prostředí (IDE) v návrhovém zobrazení.

  • Pokud chcete, aby se určité prvky uživatelského rozhraní zobrazovaly v integrovaném vývojovém prostředí, musíte implementovat jedno nebo více rozhraní nebo napsat nějaký kód.

Související obsah