Udostępnij za pośrednictwem

Jak pakiety VSPackage dodają elementy interfejsu użytkownika

  • Artykuł

Pakiet VSPackage może dodawać elementy interfejsu użytkownika, na przykład menu, paski narzędzi i okna narzędzi, do programu Visual Studio za pomocą pliku vsct .

Wskazówki dotyczące projektowania elementów interfejsu użytkownika można znaleźć w wytycznych dotyczących środowiska użytkownika programu Visual Studio.

Architektura tabeli poleceń programu Visual Studio

Jak wspomniano, architektura tabeli poleceń obsługuje powyższe zasady architektury. Zestawy za abstrakcjami, strukturami danych i narzędziami architektury tabeli poleceń są następujące:

  • Istnieją trzy podstawowe rodzaje elementów: menu, polecenia i grupy. Menu można uwidocznić w interfejsie użytkownika jako menu, podmenu, paski narzędzi lub okna narzędzi. Polecenia to procedury, które użytkownik może wykonać w środowisku IDE i mogą być widoczne jako elementy menu, przyciski, pola listy lub inne kontrolki. Grupy to kontenery zarówno dla menu, jak i poleceń.

  • Każdy element jest określany przez definicję, która opisuje element, jego priorytet względem innych elementów oraz flagi modyfikujące jego zachowanie.

  • Każdy element ma umieszczanie, które opisuje element nadrzędny elementu. Element może mieć wiele elementów nadrzędnych, dzięki czemu może być wyświetlany w wielu lokalizacjach w interfejsie użytkownika.

Każde polecenie musi mieć grupę jako element nadrzędny, nawet jeśli jest jedynym elementem podrzędnym w tej grupie. Każde standardowe menu musi mieć również grupę nadrzędną. Paski narzędzi i okna narzędzi działają jako ich rodzice. Grupa może mieć jako element nadrzędny główny pasek menu programu Visual Studio lub dowolne menu, pasek narzędzi lub okno narzędzi.

Sposób definiowania elementów

Plik vsct jest sformatowany w formacie XML. Definiuje elementy interfejsu użytkownika pakietu i określa, gdzie te elementy są wyświetlane w środowisku IDE. Każde menu, grupa lub polecenie w pakiecie jest najpierw przypisane identyfikator GUID i identyfikator w Symbols sekcji . W pozostałej części pliku vsct każde menu, polecenie i grupa są identyfikowane przez jego identyfikator GUID i identyfikator kombinacji. Poniższy przykład przedstawia typową Symbols sekcję wygenerowaną przez szablon pakietu programu Visual Studio po wybraniu polecenia menu w szablonie.

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

Element najwyższego Symbols poziomu sekcji jest elementem GuidSymbol. GuidSymbol elementy mapują nazwy na identyfikatory GUID używane przez środowisko IDE do identyfikowania pakietów i ich części składników.

Uwaga

Identyfikatory GUID są generowane automatycznie przez szablon pakietu programu Visual Studio. Możesz również utworzyć unikatowy identyfikator GUID, klikając pozycję Utwórz identyfikator GUID w menu Narzędzia .

Pierwszy GuidSymbol element , guid<PackageName>Pkgto identyfikator GUID samego pakietu. Jest to identyfikator GUID używany przez program Visual Studio do ładowania pakietu. Zazwyczaj nie ma elementów podrzędnych.

Zgodnie z konwencją menu i polecenia są grupowane pod drugim GuidSymbol elementem, guid<PackageName>CmdSeta mapy bitowe znajdują się w trzecim GuidSymbol elememencie guidImages. Nie musisz przestrzegać tej konwencji, ale każde menu, grupa, polecenie i mapa bitowa muszą być elementem podrzędnym GuidSymbol elementu.

W drugim GuidSymbol elemecie reprezentującym zestaw poleceń pakietu jest kilka IDSymbol elementów. Każdy element IDSymbol mapuje nazwę na wartość liczbową i może reprezentować menu, grupę lub polecenie będące częścią zestawu poleceń. IDSymbol Elementy w trzecim GuidSymbol elemecie reprezentują mapy bitowe, które mogą być używane jako ikony poleceń. Ponieważ pary identyfikatorów GUID/ID muszą być unikatowe w aplikacji, żadne dwie elementy podrzędne tego samego GuidSymbol elementu nie mogą mieć tej samej wartości.

Gdy menu, grupa lub polecenie ma identyfikator GUID i identyfikator, można go dodać do środowiska IDE. Każdy element interfejsu użytkownika musi mieć następujące elementy:

  • Atrybut guid zgodny z nazwą GuidSymbol elementu zdefiniowanego przez element interfejsu użytkownika.

  • Atrybut id zgodny z nazwą skojarzonego IDSymbol elementu.

Razem atrybuty guid i id tworzą podpis elementu interfejsu użytkownika.

  • Atrybut priority określający umieszczanie elementu interfejsu użytkownika w menu nadrzędnym lub grupie.

  • Element nadrzędny z guid atrybutami i id określający sygnaturę menu nadrzędnego lub grupy.

Każde menu jest definiowane jako element Menu w Menus sekcji. Menu muszą mieć guidatrybuty , idi priority oraz Parent element, a także następujące dodatkowe atrybuty i elementy podrzędne:

  • Atrybut type określający, czy menu powinno być wyświetlane w środowisku IDE jako rodzaj menu, czy jako pasek narzędzi.

  • Element Strings zawierający element ButtonText, który określa tytuł menu w środowisku IDE i element CommandName, który określa nazwę używaną w oknie Polecenia w celu uzyskania dostępu do menu.

  • Flagi opcjonalne. Element CommandFlag może pojawić się w definicji menu, aby zmienić jego wygląd lub zachowanie w środowisku IDE.

Każdy Menu element musi mieć grupę jako element nadrzędny, chyba że jest to element dokowalny, taki jak pasek narzędzi. Zadokowalne menu jest własnym elementem nadrzędnym. Aby uzyskać więcej informacji na temat menu i wartości atrybutu type , zobacz dokumentację elementu Menu.

W poniższym przykładzie pokazano menu wyświetlane na pasku menu programu Visual Studio obok menu Narzędzia .

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

Grupy

Grupa jest elementem zdefiniowanym w Groups sekcji pliku vsct . Grupy to tylko kontenery. Nie są one wyświetlane w środowisku IDE z wyjątkiem linii podziału w menu. W związku z tym element Grupy jest definiowany tylko przez jego podpis, priorytet i element nadrzędny.

Grupa może mieć menu, inną grupę lub samą siebie jako nadrzędną. Jednak element nadrzędny jest zazwyczaj menu lub paskiem narzędzi. Menu we wcześniejszym przykładzie jest elementem podrzędnym IDG_VS_MM_TOOLSADDINS grupy, a ta grupa jest elementem podrzędnym paska menu programu Visual Studio. Grupa w poniższym przykładzie jest elementem podrzędnym menu we wcześniejszym przykładzie.

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

Ponieważ jest to część menu, ta grupa zwykle zawiera polecenia. Może również zawierać inne menu. W ten sposób zdefiniowano podmenu, jak pokazano w poniższym przykładzie.

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

Polecenia

Polecenie dostarczane do środowiska IDE jest definiowane jako element Przycisku lub element kombi. Aby wyświetlić się w menu lub na pasku narzędzi, polecenie musi mieć grupę jako element nadrzędny.

Przyciski

Przyciski są definiowane w Buttons sekcji . Każdy element menu, przycisk lub inny element, który użytkownik klika, aby wykonać jedno polecenie, jest uważany za przycisk. Niektóre typy przycisków mogą również zawierać funkcje listy. Przyciski mają te same wymagane i opcjonalne atrybuty, które mają menu, a także mogą mieć element Ikona, który określa identyfikator GUID i identyfikator mapy bitowej, który reprezentuje przycisk w środowisku IDE. Aby uzyskać więcej informacji na temat przycisków i ich atrybutów, zobacz dokumentację elementu Buttons.

Przycisk w poniższym przykładzie jest elementem podrzędnym grupy we wcześniejszym przykładzie i będzie wyświetlany w środowisku IDE jako element menu w menu nadrzędnym tej grupy.

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

Kombi są definiowane w Combos sekcji . Każdy Combo element reprezentuje pole listy rozwijanej w środowisku IDE. Pole listy może lub nie może być zapisywalne przez użytkowników, w zależności od wartości type atrybutu kombi. Kombi mają te same elementy i zachowanie, które mają przyciski, a także mogą mieć następujące dodatkowe atrybuty:

  • Atrybut defaultWidth określający szerokość pikseli.

  • Atrybut idCommandList określający listę zawierającą elementy wyświetlane w polu listy. Lista poleceń musi być zadeklarowana w tym samym GuidSymbol węźle, który zawiera kombi.

W poniższym przykładzie zdefiniowano element kombi.

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

Polecenia, które będą wyświetlane razem z ikoną, muszą zawierać Icon element odwołujący się do mapy bitowej przy użyciu identyfikatora GUID i identyfikatora. Każda mapa bitowa jest definiowana jako element mapy bitowej w Bitmaps sekcji . Jedynymi wymaganymi atrybutami definicji Bitmap są guid i href, które wskazują plik źródłowy. Jeśli plik źródłowy jest paskiem zasobów, wymagany jest również atrybut usedList , aby wyświetlić listę dostępnych obrazów na pasku. Aby uzyskać więcej informacji, zobacz dokumentację elementu Mapy bitowej.

Rodzicielstwo

Poniższe reguły określają, jak element może wywoływać inny element jako element nadrzędny.

Element Zdefiniowano w tej sekcji tabeli poleceń Może być zawarty (jako element nadrzędny lub przez umieszczenie w CommandPlacements sekcji lub obu) Może zawierać (nazywany elementem nadrzędnym)
Grupuj Groups, element, IDE, inne pakiety VSPackage Menu, grupa, sam element Menu, grupy i polecenia
Menu Menu, element IDE, inne pakiety VSPackage Od 1 do n grup Od 0 do n grup
Pasek narzędzi Menu, element IDE, inne pakiety VSPackage Sam element Od 0 do n grup
Element menu Buttons, ide, inne pakiety VSPackage Od 1 do n grup, sam element Od -0 do n grup
Przycisk Buttons, ide, inne pakiety VSPackage Od 1 do n grup, sam element
Kombi Combos, ide, inne pakiety VSPackage Od 1 do n grup, sam element

Menu, grupa lub polecenie może być wyświetlane w więcej niż jednej lokalizacji w środowisku IDE. Aby element był wyświetlany w wielu lokalizacjach, należy go dodać do CommandPlacements sekcji jako element CommandPlacement. Dowolne menu, grupę lub polecenie można dodać jako umieszczanie poleceń. Nie można jednak umieścić pasków narzędzi w taki sposób, ponieważ nie mogą być wyświetlane w wielu lokalizacjach kontekstowych.

Umieszczanie poleceń ma guidatrybuty , idi priority . Identyfikator GUID i identyfikator muszą być zgodne z identyfikatorem elementu, który jest umieszczony. Atrybut priority określa umieszczanie elementu w odniesieniu do innych elementów. Gdy środowisko IDE scala co najmniej dwa elementy, które mają ten sam priorytet, ich umieszczanie jest niezdefiniowane, ponieważ środowisko IDE nie gwarantuje, że zasoby pakietu są odczytywane w tej samej kolejności za każdym razem, gdy pakiet jest kompilowany.

Jeśli menu lub grupa pojawi się w wielu lokalizacjach, wszystkie elementy podrzędne tego menu lub grupy będą wyświetlane w każdym wystąpieniu.

Widoczność poleceń i kontekst

Po zainstalowaniu wielu pakietów VSPackage mogą zostać zaśmiecone środowisko IDE za pomocą menu, elementów menu i pasków narzędzi. Aby uniknąć tego problemu, możesz kontrolować widoczność poszczególnych elementów interfejsu użytkownika przy użyciu ograniczeń widoczności i flag poleceń.

Ograniczenia widoczności

Ograniczenie widoczności jest ustawiane jako element VisibilityItem w VisibilityConstraints sekcji. Ograniczenie widoczności definiuje określone konteksty interfejsu użytkownika, w których element docelowy jest widoczny. Menu lub polecenie uwzględnione w tej sekcji jest widoczne tylko wtedy, gdy jeden ze zdefiniowanych kontekstów jest aktywny. Jeśli w tej sekcji nie ma odwołania do menu lub polecenia, zawsze jest ono widoczne domyślnie. Ta sekcja nie dotyczy grup.

VisibilityItem elementy muszą mieć trzy atrybuty w następujący sposób: guid i id docelowego elementu interfejsu użytkownika i context. Atrybut context określa, kiedy element docelowy będzie widoczny i przyjmuje dowolny prawidłowy kontekst interfejsu użytkownika jako jego wartość. Stałe kontekstu interfejsu użytkownika dla programu Visual Studio są elementami członkowskimi VSConstants klasy. Każdy VisibilityItem element może przyjmować tylko jedną wartość kontekstu. Aby zastosować drugi kontekst, utwórz drugi VisibilityItem element wskazujący ten sam element, jak pokazano w poniższym przykładzie.

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

Flagi poleceń

Następujące flagi poleceń mogą mieć wpływ na widoczność menu i poleceń, do których mają zastosowanie.

AlwaysCreate Menu jest tworzone, nawet jeśli nie ma żadnych grup ani przycisków.

Prawidłowe dla: Menu

CommandWellOnly Zastosuj tę flagę, jeśli polecenie nie jest wyświetlane w menu najwyższego poziomu i chcesz udostępnić ją w celu dodatkowego dostosowania powłoki, na przykład powiązania go z kluczem. Po zainstalowaniu pakietu VSPackage użytkownik może dostosować te polecenia, otwierając okno dialogowe Opcje , a następnie edytując umieszczanie poleceń w kategorii Środowisko klawiatury. Nie ma wpływu na umieszczanie w menu skrótów, paskach narzędzi, kontrolerach menu lub podmenu.

Prawidłowe dla: Button, Combo

DefaultDisabled Domyślnie polecenie jest wyłączone, jeśli pakiet VSPackage, który implementuje polecenie nie jest załadowany, lub metoda QueryStatus nie została wywołana.

Prawidłowe dla: Button, Combo

DefaultInvisible Domyślnie polecenie jest niewidoczne, jeśli pakiet VSPackage implementujący polecenie nie jest załadowany lub metoda QueryStatus nie została wywołana.

Powinna być połączona z flagą DynamicVisibility .

Prawidłowe dla: Button, , ComboMenu

DynamicVisibility Widoczność polecenia można zmienić przy użyciu QueryStatus metody lub identyfikatora GUID kontekstu zawartego VisibilityConstraints w sekcji .

Dotyczy poleceń wyświetlanych w menu, a nie na paskach narzędzi. Elementy paska narzędzi najwyższego poziomu można wyłączyć, ale nie ukrywać, gdy flaga OLECMDF_INVISIBLE jest zwracana z QueryStatus metody .

W menu ta flaga wskazuje również, że powinna być automatycznie ukryta, gdy jego elementy członkowskie są ukryte. Ta flaga jest zwykle przypisywana do podmenu, ponieważ menu najwyższego poziomu mają już to zachowanie.

Powinna być połączona z flagą DefaultInvisible .

Prawidłowe dla: Button, , ComboMenu

NoShowOnMenuController Jeśli polecenie, które ma tę flagę, znajduje się na kontrolerze menu, polecenie nie jest wyświetlane na liście rozwijanej.

Prawidłowe dla: Button

Aby uzyskać więcej informacji na temat flag poleceń, zobacz dokumentację elementu CommandFlag.

Wymagania ogólne

Przed wyświetleniem i włączeniem polecenia należy wykonać następującą serię testów:

  • Polecenie jest poprawnie umieszczone.

  • Flaga nie jest ustawiona DefaultInvisible .

  • Widoczne jest menu nadrzędne lub pasek narzędzi.

  • Polecenie nie jest niewidoczne z powodu wpisu kontekstu w sekcji elementu VisibilityConstraints.

  • Program VSPackage, który implementuje IOleCommandTarget interfejs wyświetla i włącza polecenie. Żaden kod interfejsu go nie przechwycił i działał na nim.

  • Gdy użytkownik kliknie polecenie, staje się przedmiotem procedury opisanej w algorytmie routingu.

Wywoływanie wstępnie zdefiniowanych poleceń

Element UsedCommands umożliwia pakietom VSPackage uzyskiwanie dostępu do poleceń udostępnianych przez inne pakiety VSPackage lub środowisko IDE. W tym celu utwórz element UsedCommand z identyfikatorem GUID i identyfikatorem polecenia do użycia. Dzięki temu polecenie zostanie załadowane przez program Visual Studio, nawet jeśli nie jest częścią bieżącej konfiguracji programu Visual Studio. Aby uzyskać więcej informacji, zobacz UsedCommand, element.

Wygląd elementu interfejsu

Zagadnienia dotyczące wybierania i pozycjonowania elementów poleceń są następujące:

  • Program Visual Studio oferuje wiele elementów interfejsu użytkownika, które są wyświetlane inaczej w zależności od rozmieszczenia.

  • Element interfejsu DefaultInvisible użytkownika zdefiniowany przy użyciu flagi nie będzie wyświetlany w środowisku IDE, chyba że jest wyświetlany przez implementację QueryStatus pakietu VSPackage metody lub skojarzony z określonym kontekstem interfejsu VisibilityConstraints użytkownika w sekcji.

  • Nawet pomyślnie umieszczone polecenie może nie być wyświetlane. Dzieje się tak, ponieważ środowisko IDE automatycznie ukrywa lub wyświetla niektóre polecenia, w zależności od interfejsów, które ma zaimplementowany pakiet VSPackage (lub nie). Na przykład implementacja niektórych interfejsów kompilacji pakietu VSPackage powoduje automatyczne pokazywanie elementów menu związanych z kompilacją.

  • Zastosowanie flagi CommandWellOnly w definicji elementu interfejsu użytkownika oznacza, że polecenie można dodać tylko przez dostosowanie.

  • Polecenia mogą być dostępne tylko w niektórych kontekstach interfejsu użytkownika, na przykład tylko wtedy, gdy okno dialogowe jest wyświetlane, gdy środowisko IDE jest w widoku projektu.

  • Aby spowodować wyświetlanie niektórych elementów interfejsu użytkownika w środowisku IDE, należy zaimplementować co najmniej jeden interfejs lub napisać kod.

Powiązana zawartość