Aracılığıyla paylaş

VSPackages kullanıcı arabirimi öğelerini nasıl ekler?

  • Makale

VSPackage, .vsct dosyası aracılığıyla Visual Studio'ya menüler, araç çubukları ve araç pencereleri gibi kullanıcı arabirimi (UI) öğeleri ekleyebilir.

Kullanıcı arabirimi öğelerine yönelik tasarım yönergelerini Visual Studio kullanıcı deneyimi yönergelerinde bulabilirsiniz.

Visual Studio komut tablosu mimarisi

Belirtildiği gibi, komut tablosu mimarisi, daha önce belirtilen mimari ilkelerini destekler. Komut tablosu mimarisinin soyutlamalarının, veri yapılarının ve araçlarının arkasındaki kavramlar aşağıdaki gibidir:

  • Üç temel öğe türü vardır: menüler, komutlar ve gruplar. Menüler kullanıcı arabiriminde menüler, alt menüler, araç çubukları veya araç pencereleri olarak gösterilebilir. Komutlar, kullanıcının IDE'de yürütebileceği yordamlardır ve menü öğeleri, düğmeler, liste kutuları veya diğer denetimler olarak gösterilebilir. Gruplar hem menüler hem de komutlar için kapsayıcılardır.

  • Her öğe, öğeyi, diğer öğelere göre önceliğini ve davranışını değiştiren bayrakları tanımlayan bir tanım tarafından belirtilir.

  • Her öğenin, öğenin üst öğesini tanımlayan bir yerleşimi vardır. Bir öğenin birden çok ana öğesi olabilir, böylece kullanıcı arabiriminde birden çok konumda görünebilir.

Bu gruptaki tek alt öğe olsa bile, her komutun üst öğesi olarak bir grubu olmalıdır. Her standart menünün de bir üst grubu olmalıdır. Araç çubukları ve araç pencereleri kendi ebeveyni gibi davranır. Bir grubun ana Visual Studio menü çubuğu veya herhangi bir menü, araç çubuğu veya araç penceresi üst öğesi olabilir.

Öğeler nasıl tanımlanır?

. vsct dosyası XML olarak biçimlendirilir. Bir paket için kullanıcı arabirimi öğelerini tanımlar ve bu öğelerin IDE'de nerede görüneceğini belirler. Paketteki her menü, grup veya komuta önce bölümünde bir GUID ve kimlik Symbols atanır. .vsct dosyasının geri kalanı boyunca, her menü, komut ve grup GUID ve kimlik bileşimiyle tanımlanır. Aşağıdaki örnekte, şablonda Menü Komutu seçildiğinde Visual Studio paket şablonu tarafından oluşturulan tipik Symbols bir bölüm gösterilmektedir.

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

Bölümün Symbols en üst düzey öğesi GuidSymbol öğesidir. GuidSymbol öğeleri, paketleri ve bunların bileşen parçalarını tanımlamak için IDE tarafından kullanılan GUID'lerle adları eşler.

Not

GUID'ler Visual Studio paket şablonu tarafından otomatik olarak oluşturulur. Araçlar menüsünde GUID Oluştur'a tıklayarak da benzersiz bir GUID oluşturabilirsiniz.

İlk GuidSymbol öğesi, guid<PackageName>Pkgpaketin guid değeridir. Bu, Visual Studio tarafından paketi yüklemek için kullanılan GUID'dir. Genellikle alt öğeleri yoktur.

Kurala göre, menüler ve komutlar ikinci GuidSymbol bir öğe guid<PackageName>CmdSetaltında gruplandırılır ve bit eşlemler üçüncü GuidSymbol guidImagesöğe olan altındadır. Bu kuralı izlemeniz gerekmez, ancak her menü, grup, komut ve bit eşlem bir GuidSymbol öğenin alt öğesi olmalıdır.

Paket komut kümesini temsil eden ikinci GuidSymbol öğede birkaç IDSymbol öğe vardır. Her IDSymbol öğesi bir adı sayısal değerle eşler ve komut kümesinin parçası olan menü, grup veya komutu temsil edebilir. IDSymbol Üçüncü GuidSymbol öğedeki öğeler, komutlar için simge olarak kullanılabilecek bit eşlemleri temsil eder. GUID/KIMLIK çiftlerinin bir uygulamada benzersiz olması gerektiğinden, aynı GuidSymbol öğenin iki alt öğesi aynı değere sahip olmayabilir.

Menü, grup veya komut guid ve kimliğe sahipse, IDE'ye eklenebilir. Her kullanıcı arabirimi öğesi aşağıdakilere sahip olmalıdır:

  • guid UI öğesinin altında tanımlandığı öğenin adıyla GuidSymbol eşleşen bir öznitelik.

  • id İlişkili IDSymbol öğenin adıyla eşleşen bir öznitelik.

guid ve id öznitelikleri birlikte kullanıcı arabirimi öğesinin imzasını oluşturur.

Her menü, bölümünde Menü öğesi Menus olarak tanımlanır. Menülerde , id, ve öznitelikleri, priority bir Parent öğesi ve ayrıca aşağıdaki ek öznitelikler ve alt öğeler olmalıdırguid:

  • type Menünün IDE'de bir tür menü olarak mı yoksa araç çubuğu olarak mı görüneceğini belirten bir öznitelik.

  • IDE'deki menünün başlığını belirten ButtonText öğesini ve menüye erişmek için Komut penceresinde kullanılan adı belirten commandname öğesini içeren Strings öğesi.

  • İsteğe bağlı bayraklar. CommandFlag öğesi, IDE'deki görünümünü veya davranışını değiştirmek için menü tanımında görüntülenebilir.

Araç çubuğu gibi sabitlenebilir bir öğe olmadığı sürece her Menu öğenin üst öğesi olarak bir grubu olmalıdır. Yerleştirilebilir menü kendi üst öğesidir. Özniteliğinin menüleri ve değerleri hakkında daha fazla bilgi için type Menu öğesi belgelerine bakın.

Aşağıdaki örnekte, Araçlar menüsünün yanındaki Visual Studio menü çubuğunda görüntülenen bir menü gösterilmektedir.

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

Gruplar

Grup, .vsct dosyasının Groups bölümünde tanımlanan bir öğedir. Gruplar yalnızca kapsayıcılardır. IDE'de, bir menüdeki bölme satırı dışında görünmezler. Bu nedenle, bir Group öğesi yalnızca imzası, önceliği ve üst öğesiyle tanımlanır.

Bir grubun menüsü, başka bir grubu veya kendisini üst öğe olarak kullanabilir. Ancak, üst öğe genellikle bir menü veya araç çubuğudur. Önceki örnekteki menü grubun alt öğesidir IDG_VS_MM_TOOLSADDINS ve bu grup Visual Studio menü çubuğunun alt öğesidir. Aşağıdaki örnekteki grup, önceki örnekteki menünün alt öğesidir.

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

Bir menünün parçası olduğundan, bu grup genellikle komutlar içerir. Ancak, başka menüler de içerebilir. Aşağıdaki örnekte gösterildiği gibi alt menüler bu şekilde tanımlanır.

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

Komutlar

IDE'ye sağlanan komut, Button öğesi veya Birleşik giriş öğesi olarak tanımlanır. Bir menüde veya araç çubuğunda görünmesi için komutun üst öğesi olarak bir grup olması gerekir.

Düğmeler

Düğmeler bölümünde tanımlanır Buttons . Bir kullanıcının tek bir komutu yürütmek için tıklattığını herhangi bir menü öğesi, düğme veya başka bir öğe düğme olarak kabul edilir. Bazı düğme türleri liste işlevselliği de içerebilir. Düğmeler, menülerle aynı gerekli ve isteğe bağlı özniteliklere sahiptir ve IDE'deki düğmeyi temsil eden bit eşlemin GUID'sini ve kimliğini belirten bir Icon öğesine de sahip olabilir. Düğmeler ve bunların öznitelikleri hakkında daha fazla bilgi için Düğmeler öğesi belgelerine bakın.

Aşağıdaki örnekteki düğme, önceki örnekte grubun alt öğesidir ve IDE'de bu grubun üst menüsünde menü öğesi olarak görünür.

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

Birleşik girişler bölümünde tanımlanır Combos . Her Combo öğe IDE'deki bir açılan liste kutusunu temsil eder. Liste kutusu, birleşik giriş özniteliğinin type değerine bağlı olarak kullanıcılar tarafından yazılabilir veya yazılamaz. Birleşik girişler, düğmelerin sahip olduğu öğelere ve davranışlara sahiptir ve aşağıdaki ek özniteliklere de sahip olabilir:

  • Piksel defaultWidth genişliğini belirten bir öznitelik.

  • Liste idCommandList kutusunda görüntülenen öğeleri içeren bir liste belirten öznitelik. Komut listesi birleşik giriş içeren aynı GuidSymbol düğümde bildirilmelidir.

Aşağıdaki örnek bir birleşik giriş öğesi tanımlar.

<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>
Bit Eşlemler

Bir simgeyle birlikte görüntülenecek komutlar, GUID ve kimliğini kullanarak bit eşlemlere başvuran bir öğe içermelidir Icon . Her bit eşlem, bölümünde Bir Bit Eşlem öğesi Bitmaps olarak tanımlanır. Bir Bitmap tanımın tek gerekli öznitelikleri, kaynak dosyaya işaret eden ve href'tirguid. Kaynak dosya bir kaynak şeridiyse, şeritteki kullanılabilir görüntüleri listelemek için usedList özniteliği de gereklidir. Daha fazla bilgi için Bit Eşlem öğesi belgelerine bakın.

Ebeveyn -lik

Aşağıdaki kurallar, bir öğenin başka bir öğeyi üst öğe olarak nasıl çağırabileceğini yönetir.

Öğe Komut Tablosunun bu bölümünde tanımlanmış İçerebilir (üst öğe olarak veya bölüme CommandPlacements yerleştirilerek ya da her ikisiyle birlikte) içerebilir (üst öğe olarak adlandırılır)
Gruplandırma Gruplar öğesi, IDE, diğer VSPackage'lar Menü, grup, öğenin kendisi Menüler, gruplar ve komutlar
Menü Menus öğesi, IDE, diğer VSPackage'lar 1 - n grup 0 - n grup
Araç Çubuğu Menus öğesi, IDE, diğer VSPackage'lar Öğenin kendisi 0 - n grup
Menü Öğesi Düğmeler öğesi, IDE, diğer VSPackage'lar 1 ile n arasında grup, öğenin kendisi -0 - n grupları
Düğme Düğmeler öğesi, IDE, diğer VSPackage'lar 1 ile n arasında grup, öğenin kendisi
Açılan Combos öğesi, IDE, diğer VSPackage'lar 1 ile n arasında grup, öğenin kendisi

IDE'de birden fazla konumda bir menü, grup veya komut görüntülenebilir. Bir öğenin birden çok konumda görünmesi için bölüme CommandPlacements CommandPlacement öğesi olarak eklenmesi gerekir. Herhangi bir menü, grup veya komut, komut yerleşimi olarak eklenebilir. Ancak, birden çok bağlama duyarlı konumda görünemedikleri için araç çubukları bu şekilde konumlandırılamaz.

Komut yerleşimlerinde , idve priority öznitelikleri vardırguid. GUID ve kimlik, konumlandırılan öğeyle eşleşmelidir. özniteliği, priority öğenin diğer öğelerle ilgili yerleşimini yönetir. IDE, aynı önceliğe sahip iki veya daha fazla öğeyi birleştirdiğinde, IDE paket kaynaklarının paket oluşturulduğunda aynı sırada okunmasını garanti etmediğinden yerleşimleri tanımlanmamış olur.

Bir menü veya grup birden çok konumda görünürse, her örnekte söz diziminin veya grubun tüm alt öğeleri görünür.

Komut görünürlüğü ve bağlamı

Birden çok VSPackage yüklendiğinde menülerin, menü öğelerinin ve araç çubuklarının bir kısmı IDE'yi karmaşık hale gelebilir. Bu sorunu önlemek için görünürlük kısıtlamalarını ve komut bayraklarını kullanarak tek tek kullanıcı arabirimi öğelerinin görünürlüğünü denetleyebilirsiniz.

Görünürlük kısıtlamaları

Görünürlük kısıtlaması bölümünde VisibilityItem öğesi VisibilityConstraints olarak ayarlanır. Görünürlük kısıtlaması, hedef öğenin görünür olduğu belirli kullanıcı arabirimi bağlamlarını tanımlar. Bu bölümde yer alan bir menü veya komut yalnızca tanımlı bağlamlardan biri etkin olduğunda görünür. Bu bölümde bir menüye veya komuta başvurulmazsa, varsayılan olarak her zaman görünür. Bu bölüm gruplar için geçerli değildir.

VisibilityItem öğelerinin aşağıdaki gibi üç özniteliği olmalıdır: guid hedef UI öğesinin ve id ve context. context özniteliği, hedef öğenin ne zaman görünür olacağını belirtir ve geçerli kullanıcı arabirimi bağlamını değeri olarak alır. Visual Studio'nun kullanıcı arabirimi bağlam sabitleri sınıfın VSConstants üyeleridir. Her VisibilityItem öğe yalnızca bir bağlam değeri alabilir. İkinci bir bağlam uygulamak için, aşağıdaki örnekte gösterildiği gibi aynı öğeye işaret eden ikinci VisibilityItem bir öğe oluşturun.

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

Komut bayrakları

Aşağıdaki komut bayrakları, uygulandıkları menülerin ve komutların görünürlüğünü etkileyebilir.

AlwaysCreate Menü, grup veya düğme olmasa bile oluşturulur.

Geçerli olan: Menu

CommandWellOnly Komut üst düzey menüde görünmüyorsa ve ek kabuk özelleştirmesi için kullanılabilir hale getirmek istiyorsanız (örneğin, bir anahtara bağlama) bu bayrağı uygulayın. VSPackage yüklendikten sonra, bir kullanıcı Seçenekler iletişim kutusunu açıp Klavye Ortamı kategorisi altındaki komut yerleşimini düzenleyerek bu komutları özelleştirebilir. Kısayol menülerine, araç çubuklarına, menü denetleyicilerine veya alt menülere yerleştirmeyi etkilemez.

Geçerli: Button, Combo

DefaultDisabled Varsayılan olarak, komutu uygulayan VSPackage yüklenmediyse veya QueryStatus yöntemi çağrılmadıysa komut devre dışı bırakılır.

Geçerli: Button, Combo

DefaultInvisible Varsayılan olarak, komutu uygulayan VSPackage yüklenmediyse veya QueryStatus yöntemi çağrılmadıysa komut görünmez.

bayrağıyla DynamicVisibility birleştirilmelidir.

Geçerli: Button, Combo, Menu

DynamicVisibilityKomutun görünürlüğü, yöntemi veya bölümüne dahil edilen bir bağlam GUID'i VisibilityConstraints kullanılarak QueryStatus değiştirilebilir.

Araç çubuklarında değil, menülerde görünen komutlar için geçerlidir. Üst düzey araç çubuğu öğeleri, yönteminden bayrak döndürülürken OLECMDF_INVISIBLE devre dışı bırakılabilir, ancak gizlenemez QueryStatus .

Bir menüde bu bayrak, üyeleri gizlendiğinde otomatik olarak gizlenmesi gerektiğini de gösterir. Üst düzey menülerde bu davranış zaten olduğundan bu bayrak genellikle alt menülere atanır.

bayrağıyla DefaultInvisible birleştirilmelidir.

Geçerli: Button, Combo, Menu

NoShowOnMenuController Bu bayrağı içeren bir komut bir menü denetleyicisinde konumlandırılmışsa, komut açılan listede görünmez.

Geçerli olan: Button

Komut bayrakları hakkında daha fazla bilgi için CommandFlag öğesi belgelerine bakın.

Genel gereksinimler

Komutunuz görüntülenebilmesi ve etkinleştirilmesi için aşağıdaki test serisini geçmelidir:

  • Komut doğru konumlandırıldı.

  • Bayrak DefaultInvisible ayarlanmadı.

  • Üst menü veya araç çubuğu görünür.

  • VisibilityConstraints öğesi bölümündeki bir bağlam girdisi nedeniyle komut görünmez.

  • Arabirimi uygulayan IOleCommandTarget VSPackage kodu, komutunuzu görüntüler ve etkinleştirir. Hiçbir arabirim kodu araya girip üzerinde işlem yapmamış.

  • Kullanıcı komutunuza tıkladığında, yönlendirme algoritmasında özetlenen yordama tabi olur.

Önceden tanımlanmış komutları çağırma

UsedCommands öğesi, VSPackage'ların diğer VSPackage'lar veya IDE tarafından sağlanan komutlara erişmesini sağlar. Bunu yapmak için, kullanılacak komutun GUID'sine ve kimliğine sahip bir UsedCommand öğesi oluşturun. Bu, komutun geçerli Visual Studio yapılandırmasının bir parçası olmasa bile Visual Studio tarafından yüklenmesini sağlar. Daha fazla bilgi için bkz . UsedCommand öğesi.

Arabirim öğesi görünümü

Komut öğelerini seçme ve konumlandırma konusunda dikkat edilmesi gerekenler şunlardır:

  • Visual Studio, yerleştirmeye bağlı olarak farklı görünen birçok kullanıcı arabirimi öğesi sunar.

  • bayrağı kullanılarak tanımlanan bir UI öğesi, yönteminin DefaultInvisible VSPackage uygulaması QueryStatus tarafından görüntülenmediği veya bölümdeki belirli bir kullanıcı arabirimi bağlamıyla ilişkilendirilmediği sürece IDE'de VisibilityConstraints görüntülenmez.

  • Başarıyla konumlandırılmış bir komut bile görüntülenmeyebilir. Bunun nedeni, VSPackage'ın uyguladığı (veya uygulamadığı) arabirimlere bağlı olarak IDE'nin bazı komutları otomatik olarak gizlemesi veya görüntülemesidir. Örneğin, VSPackage'ın bazı derleme arabirimlerini uygulaması, derlemeyle ilgili menü öğelerinin otomatik olarak gösterilmesine neden olur.

  • UI öğesinin CommandWellOnly tanımında bayrağın uygulanması, komutun yalnızca özelleştirme yoluyla eklenebileceği anlamına gelir.

  • Komutlar yalnızca belirli kullanıcı arabirimi bağlamlarında, örneğin, yalnızca IDE tasarım görünümündeyken bir iletişim kutusu görüntülendiğinde kullanılabilir.

  • IDE'de belirli kullanıcı arabirimi öğelerinin görüntülenmesine neden olmak için bir veya daha fazla arabirim uygulamanız veya kod yazmanız gerekir.

İlgili içerik