Sdílet prostřednictvím

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

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 UI zobrazovala na různých místech.

Každý příkaz musí mít skupinu jako nadřazenou skupinu, i když je to jediný příkaz 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í panel 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ě v oddílu Symbols je prvek GuidSymbol. GuidSymbol elementy přiřazují názvy k identifikátorům GUID, které 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>Pkg je identifikátor GUID samotného balíčku. Toto je identifikátor GUID, který Visual Studio používá k načítání 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 dodržovat tuto konvenci, ale každá nabídka, skupina, příkaz a rastrový obrázek musí být prvkem podřízeným 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í sadě 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 a id atributy tvoří společně 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 s atributy guid a id, které definují nadřazenou nabídku nebo skupinu.

Každá nabídka je definována jako Menu prvek v sekci Menus. Nabídky musí obsahovat atributy guid, id a priority a element Parent a také následující 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 může být použit v definici nabídky pro změnu vzhledu nebo chování v integrovaném vývojovém prostředí (IDE).

Každý Menu prvek musí mít skupinu jako nadřazenou, pokud se nejedná o dokovatelný prvek, například panel nástrojů. Ukotvitelné menu je vlastní rodič. 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>

Groups

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 svým podpisem, prioritou a nadřazeným prvkem.

Skupina může mít jako nadřazenou položku nabídky, jinou skupinu nebo být sama sobě nadřazenou. Nadřazený prvek je však obvykle menu nebo panel 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>

Commands

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.

Buttons

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

Komba jsou definována v části Combos. 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 combo.

Následující příklad definuje kombinační prvek.

<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>
Rastrové obrázky

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 strip prostředků, vyžaduje se také atribut usedList, který vypíše dostupné obrázky ve stripu. 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.

prvek Definováno v této části tabulky příkazů Může být obsažen (jako rodič, umístěním v oddílu CommandPlacements, nebo obojím) Může obsahovat (označuje se jako nadřazený)
Skupina Groups element, integrované vývojové prostředí (IDE), ostatní balíčky VSPackages Nabídka, skupina, samotná položka Nabídky, skupiny a příkazy
Jídelní lístek Menus – element, integrované vývojové prostředí (IDE), ostatní balíčky VSPackages 1 až n skupin 0 až n skupin
Panel nástrojů Elementy menu, integrované vývojové prostředí (IDE), ostatní balíčky VSPackages Samotná položka 0 až n skupin
Položka v menu Buttons – element, integrované vývojové prostředí (IDE), ostatní balíčky VSPackages 1 až n skupin, položka samotná -0 až n skupin
Button Element tlačítek, IDE, ostatní balíčky VSPackages 1 až n skupin, samotná položka
Kombo 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 na více místech. Aby se položka objevila v několika umístěních, musí být přidána do oddílu CommandPlacements jako 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í guid, id a priority atributy. Identifikátor GUID a ID musí odpovídat těm položky, která je polohová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, všechny podřízené položky této nabídky nebo skupiny se zobrazí v každém jednotlivém umístění.

Viditelnost a kontext příkazů

Pokud je nainstalováno více balíčků VSPackage, může v integrovaném vývojovém prostředí (IDE) dojít k zahlcení množstvím 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 když 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 prvky musí mít tři atributy, a to následující: guid a id cílového prvku 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í parametry příkazů mohou ovlivnit viditelnost nabídek a příkazů, ke kterým 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é, když je vrácen příznak OLECMDF_INVISIBLE z metody QueryStatus.

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 podnabídkám, protože hlavní nabídky 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

Pro další informace o příznacích příkazů, nahlédněte do dokumentace 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 je správně umístěn.

  • 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 neprovedl žádnou akci.

  • 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á GUID a ID příkazu, který chcete 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 některých rozhraní sestavení v "VSPackage" způsobí automatické zobrazení položek nabídky souvisejících se 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

  • Last updated on