Comment les VSPackages ajoutent des éléments de l'interface utilisateur à l'IDE

Article
05/17/2015

Un VSPackage peut ajouter des éléments de l' (UI)interface utilisateur, par exemple, les menus, barres d'outils, les fenêtres et, à l'environnement de développement intégré Visual (IDE) Studio.

principes architecturaux

l'ensemble de règles et de structures qui permettent à un VSPackage pour personnaliser l'interface utilisateur est nommé l' architecture de Tableau de commande. L'architecture de Tableau de commande est basé sur les principes de conception suivants :

L'interface utilisateur ne doit pas être encombré ou portait à confusion.
L'interface utilisateur doit être dynamique, non statique.
L'interface utilisateur doit pouvoir personnaliser.
L'interface utilisateur doit être utile.

L'interface utilisateur ne doit pas être encombré ou confus

Plusieurs VSPackages peut être installé dans une session de Visual Studio qui héberge votre VSPackage. Lorsque votre VSPackage ajoute les commandes, il ne doit pas interrompre VSPackages déjà installé, mais il doit également rendre ses fonctionnalités disponibles à l'autre des VSPackages et leur permettre de fournir des fonctionnalités en retour.
Chaque menu, s'il est accessible à l'aide de la barre de menu principal, d'un sous-menu, ou un menu contextuel, peut contenir des éléments de menu fournies par l'autre des VSPackages. Par conséquent, soyez prudent à ne pas surcharger l'interface utilisateur. Si trop de commandes s'affichent simultanément, l'interface utilisateur peut que les utilisateurs.

L'interface utilisateur doit être Dynamic, non statique

Les commandes peuvent être affichées ou masquées à tout moment, selon l'état des données sous-jacentes et l'activité d'utilisateur actuel.
Un VSPackage doit être activé pour modifier le nom d'un élément d'interface utilisateur, ainsi que le contenu de ses zones de liste déroulante ou menus.
Les éléments d'interface utilisateur peuvent être ajoutés ou supprimés lorsque le VSPackage est utilisé.
Les éléments d'interface utilisateur peuvent nécessiter des appels supplémentaires au VSPackage pour remplir leurs valeurs ou pour détecter leur état actuel. Parmi ces éléments incluent les listes de fichiers (MRU) les plus récemment utilisés, des zones de liste déroulante, et de sélecteurs de la couleur ou la texture.
Il peut améliorer l'expérience utilisateur pour ajouter votre commande aux menus dans l'autre des VSPackages. Par exemple, si la commande que vous fournissez ressemble à Copier, vous pouvez placer votre commande dans chaque VSPackage où Copier s'affiche.

L'interface utilisateur doit être personnalisable

À tout moment, un utilisateur peut personnaliser les éléments d'interface utilisateur dans le VSPackage, par exemple, en ajoutant un bouton dans une fenêtre Outil ou en réorganisant un menu. Toutefois, dans certains cas, vous pouvez souhaiter désactiver la personnalisation.
Certaines commandes ne sont disponibles qu'à l'aide de la personnalisation ; autrement dit, une commande ne peut pas être disponible dans un menu ou une barre d'outils jusqu'à ce qu'un utilisateur l'ajoute à l'aide de la boîte de dialogue de Personnaliser .
À tout moment, un utilisateur peut personnaliser les raccourcis clavier pour vos commandes, avec les raccourcis clavier des commandes qui proviennent de Visual Studio et autre VSPackages.
vos commandes peuvent être exécutées à l'aide de la fenêtre de Commande . Par conséquent, l'IDE doit savoir que la commande correspond à un nom particulier de commande. L'IDE effectue ceci en utilisant un processus appelé " canonisation, où les espaces sont supprimés pour compresser un nom de commande dans un mot unique. Par exemple, la canonisation «&File ouvert » est « FileOpen ».

L'interface utilisateur doit être utile

La plupart des éléments d'interface utilisateur doivent avoir des info-bulles.
Pour de meilleures performances, votre VSPackage doit être chargé uniquement lorsqu'une de ses fonctions est appelée. Ce concept est appelé « chargement différé. »
Les ajouts à l'IDE demandé par un VSPackage doivent être localisables.
Vous pouvez utiliser les bitmaps inclus dans Visual Studio ou vous pouvez fournir votre propre code.

L'architecture de Tableau de commande Visual Studio

Comme indiqué, l'architecture du comité de contrôle prend en charge les principes architecturaux précédents. Les principes derrière les abstractions, les structures de données, et des outils de l'architecture de Tableau de commande sont les suivantes :

Il existe trois genres d'éléments de base : menus, commandes, et groupes. Les menus peuvent être exposés dans l'interface utilisateur comme menus, sous-menus, les barres d'outils, et les fenêtres Outil. Les commandes sont des procédures que l'utilisateur peut exécuter dans l'IDE, et peuvent être exposées en tant qu'éléments de menu, des boutons, zones de liste, ou un autre contrôle. Les groupes sont des conteneurs pour les menus et des commandes.
Chaque élément est spécifié par une définition qui décrit l'élément, sa priorité relative à d'autres éléments, et les balises qui modifient son comportement.
chaque élément a un positionnement qui décrit le parent de l'élément. Un élément peut avoir plusieurs parents, afin qu'il puisse apparaître dans plusieurs emplacements dans l'interface utilisateur.

Chaque commande doit avoir un groupe comme son parent, même si c'est le seul enfant à ce groupe. chaque menu standard doit également avoir un groupe parent. Les barres d'outils et des fenêtres Outil agissent en tant que leurs propres parents. Un groupe peut avoir comme son parent la barre de menus principale de Visual Studio, ou toute menu, toolbar, ou la fenêtre Outil.

La façon dont les éléments sont définis

. Les fichiers de Vsct sont mis en forme dans XML. Un fichier de .vsct définit les éléments d'interface utilisateur d'un package et détermine où ces éléments apparaissent dans l'IDE. Chaque menu, groupe, ou ordre dans le package est premier assigné GUID et un ID dans la section d' Symbols . Dans le reste du fichier de .vsct, chaque menu, commande, et groupe est identifié par sa combinaison de GUID et d'ID. L'exemple suivant présente une section standard d' Symbols comme générée par le modèle de package Visual Studio lorsque Commande de menu est sélectionné dans le modèle.

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

l'élément de niveau supérieur de la section d' Symbols est GuidSymbol, élément. noms de mappage d'éléments d'GuidSymbol à les GUID utilisés par l'IDE pour identifier des packages et leurs éléments.

Notes

GUID sont générés automatiquement par le modèle de package Visual Studio.Vous pouvez également créer un GUID unique en cliquant sur Create GUID dans le menu d' Outils .

Le premier élément d' GuidSymbol , « package de GUID PackageName [] », est un GUID du package lui-même. C'est un GUID utilisé par Visual Studio pour charger le package. En général, il n'a pas d'éléments enfants.

Par convention, les menus et les commandes sont regroupés sous un élément d' GuidSymbol de seconde, « guid PackageName [] CmdSet », et les bitmaps sont sous un élément d' GuidSymbol tiers, des « guidImages ». vous ne devez pas suivre cette convention, mais chaque menu, groupe, commande, et bitmap doivent être un enfant d'un élément d' GuidSymbol .

dans le deuxième élément d' GuidSymbol , qui représente le jeu de commandes de package, sont plusieurs éléments d' IDSymbol . chaque IDSymbol, élément mappe un nom à une valeur numérique, et peut représenter un menu, un groupe, ou une commande qui fait partie du jeu de commandes. Les éléments d' IDSymbol dans le troisième élément d' GuidSymbol représentent les bitmaps qui peuvent être utilisés comme icônes des commandes. Étant donné que les paires de GUID/ID doivent être uniques dans une application, aucun deux enfants du même élément d' GuidSymbol peuvent ne pas avoir la même valeur.

menus, groupes, et commandes

Lorsqu'un menu, d'un groupe, ou une commande a GUID et un ID, il peut être ajouté à l'IDE. Chaque élément d'interface doit disposer des éléments suivants :

Un attribut d' guid qui correspond au nom de l'élément d' GuidSymbol que l'élément d'interface est défini sous.
Un attribut d' id qui correspond au nom de l'élément associé d' IDSymbol .

Ensemble, guid et les attributs d' id constituent la signature de l'élément d'interface utilisateur.
un attribut d' priority qui détermine le positionnement de l'élément d'interface à son menu ou groupe parent.
Élément parent qui a guid et les attributs d' id qui spécifient la signature du menu ou du groupe parent.

Menus

chaque menu est défini comme Menu, élément dans la section d' Menus . Les menus doivent avoir guid, id, les attributs et d' priority , et un élément d' Parent , et également les attributs et les enfants supplémentaires suivants :

Un attribut d' type qui spécifie si le menu doit apparaître dans l'IDE comme une sorte de menu ou la barre d'outils.
Strings, élément qui contient ButtonText, élément, qui spécifie le titre du menu de l'IDE, et CommandName, élément, qui spécifie le nom utilisé dans la fenêtre de Commande pour accéder au menu.
Indicateurs facultatifs. CommandFlag, élément peut apparaître dans une définition de menu pour modifier son apparence ou comportement de l'IDE.

Chaque élément d' Menu doit avoir un groupe comme son parent, à moins qu'il soit un élément ancrable tel qu'une barre d'outils. un menu ancrable est son propre parent. Pour plus d'informations sur les menus et des valeurs pour type attribut, consultez la documentation de Menu, élément .

L'exemple suivant montre un menu qui s'affiche dans la barre de menus de Visual Studio, en regard de le menu d' Outils .

<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

Un groupe est un élément défini dans la section d' Groups du fichier de .vsct. Les groupes sont uniquement des conteneurs. Ils n'apparaissent pas dans l'IDE sauf comme une ligne de séparation dans un menu. Par conséquent, Group, élément est défini uniquement par la signature, priorité, et parent.

Un groupe peut avoir un menu, un autre groupe, ou lui-même comme parent. Toutefois, le parent est en général un menu ou une barre d'outils. Le menu dans l'exemple précédent est un enfant du groupe d' IDG_VS_MM_TOOLSADDINS , et ce groupe est un enfant de la barre de menus de Visual Studio. Le groupe dans l'exemple suivant est un enfant du menu dans l'exemple précédent.

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

Dans la mesure où ce fait partie d'un menu, ce groupe contient généralement des commandes. Toutefois, il peut également contenir d'autres menus. Voici comment des sous-menus sont définis, comme indiqué dans l'exemple suivant.

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

Commandes

Une commande qui est fournie à l'IDE est définie comme Button, élément ou Combo, élément. Pour apparaître dans un menu ou une barre d'outils, la commande doit avoir un groupe comme son parent.

Boutons

Les boutons sont définis dans la section d' Buttons . Tout élément de menu, bouton, ou un autre élément qu'un utilisateur clique sur pour exécuter une commande unique est considéré comme un bouton. Certains types de bouton peuvent également inclure la fonctionnalité liste. Les boutons ont la même chose requise et des attributs facultatifs que les menus ont, et peuvent également avoir Icon, élément qui spécifie le GUID et l'ID de la bitmap qui représente le bouton dans l'IDE. Pour plus d'informations sur les boutons et leurs attributs, consultez la documentation de Buttons, élément .

Le bouton dans l'exemple suivant est un enfant du groupe dans l'exemple précédent, et apparaîtrait dans l'IDE en tant qu'élément de menu dans le menu parent de ce groupe.

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

combos

Les combos sont définis dans la section d' Combos . Chaque élément d' Combo représente une zone de liste déroulante dans l'IDE. La zone de liste peut ou ne pas être accessible en écriture par les utilisateurs, en fonction de la valeur de l'attribut d' type de configuration pgorelease. Les combos ont les mêmes éléments et comportement que les boutons ont, et peuvent également avoir des attributs supplémentaires suivants :

un attribut d' defaultWidth qui spécifie la largeur de pixel.
Un attribut d' idCommandList qui spécifie une liste qui contient les éléments affichés dans la zone de liste. La commande doit être déclarée au même nœud d' GuidSymbol qui contient la zone.

l'exemple suivant définit un élément modifiable.

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

bitmap

Les commandes qui seront affichées avec une icône doivent inclure un élément d' Icon qui fait référence à une bitmap à l'aide de son GUID et l'ID chaque bitmap est définie comme Bitmap, élément dans la section d' Bitmaps . Les seuls attributs requis pour une définition d' Bitmap sont guid et href, indiquant que le fichier source. si le fichier source est une bande de ressource, un attribut d' usedList est également requis, pour répertorier les images disponibles dans la bande. Pour plus d'informations, consultez la documentation Bitmap, élément.

Parentage

Les règles suivantes déterminent la façon dont un élément peut appeler un autre élément comme son parent.

Élément	Défini dans cette section de la table de commande	Peut être contenu (en tant que parent, ou par positionnement dans la section d' CommandPlacements , ou les deux)	Peut contenir de (dénommé parent)
Groupe	Groups, élément, l'IDE, l'autre des VSPackages	un menu, un groupe, l'élément lui-même	menus, groupes, et commandes
Menu	Menus, élément, l'IDE, l'autre des VSPackages	1 aux groupes de n	0 aux groupes de n
Barre d'outils	Menus, élément, l'IDE, l'autre des VSPackages	l'élément lui-même	0 aux groupes de n
Menu Item	Buttons, élément, l'IDE, l'autre des VSPackages	1 aux groupes de n , l'élément lui-même	-0 aux groupes de n
Button	Buttons, élément, l'IDE, l'autre des VSPackages	1 aux groupes de n , l'élément lui-même
combo	Combos, élément, l'IDE, l'autre des VSPackages	1 aux groupes de n , l'élément lui-même

Un menu, un groupe, ou une commande peuvent apparaître dans plusieurs emplacement de l'IDE. Pour qu'un élément apparaisse dans plusieurs emplacements, il doit être ajouté dans la section de CommandPlacements comme CommandPlacement, élément. Les menus, groupe, ou commandes peuvent être ajoutés comme positionnement de commande. Toutefois, les barres d'outils ne peuvent pas être placées de cette manière parce qu'elles ne peuvent pas apparaître dans plusieurs emplacements contextuels.

Les positionnements de commande a guid, id, les attributs et d' priority . Le GUID et l'ID doivent correspondre à celles de l'élément qui est positionné. L'attribut d' priority détermine le positionnement de l'élément par rapport à d'autres éléments. Lorsque l'IDE fusionne deux ou plusieurs éléments qui ont la même priorité, leurs positionnements sont indéfinis car l'IDE ne garantit pas que les ressources de package sont lues dans le même ordre chaque fois que le package est généré.

Si un menu ou un groupe s'affiche dans plusieurs emplacements, tous les enfants de ce menu ou groupe apparaissent dans chaque instance.

Visibilité et le contexte de commande

Lorsque plusieurs des VSPackages sont installés, une profusion des menus, des éléments de menu, les barres d'outils peut encombrer l'IDE. Pour éviter ce problème, vous pouvez contrôler la visibilité des éléments d'interface utilisateur à l'aide de les balises de contraintes et de commande de visibilité .

contraintes de visibilité

Une contrainte de visibilité est définie comme Élément VisibilityItem dans la section d' VisibilityConstraints . Une contrainte de visibilité définit les contextes d'interface utilisateur spécifiques dans lesquels l'élément cible est visible. Un menu ou une commande inclus de cette section est visible uniquement lorsque l'un des contextes définis est actif. Si un menu ou une commande n'est pas référencé dans cette section, il est toujours visible par défaut. cette section ne s'applique pas aux groupes.

les éléments d'VisibilityItem doivent posséder trois attributs, comme suit : guid et id de l'élément d'interface cible, et context. L'attribut d' context spécifie à quel moment l'élément cible sera visible, et prend tout contexte valide d'interface utilisateur en tant que valeur. Les constantes de contexte de l'interface utilisateur de Visual Studio sont des membres de la classe d' VSConstants . Chaque élément d' VisibilityItem peut prendre une seule valeur de contexte. Pour appliquer un deuxième contexte, créez un élément d' VisibilityItem de seconde qui pointe vers le même élément, comme indiqué dans l'exemple suivant.

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

Indicateurs de commande

les balises de commande suivante peuvent affecter la visibilité des menus et des commandes qu'elles s'appliquent à.

AlwaysCreate
Le menu est créé même s'il n'a aucun groupe bouton ou.

valide pour : Menu
CommandWellOnly
Appliquez cet indicateur si la commande ne s'affiche pas dans le menu du niveau supérieur et vous souhaitez que le rendre disponible pour la personnalisation supplémentaire de shell, par exemple, le liant à une clé. Une fois le VSPackage installé, un utilisateur peut personnaliser ces commandes en ouvrant la boîte de dialogue d' Options puis en modifiant le positionnement de commande sous la catégorie d' environnement de clavier . N'affecte pas le positionnement des menus contextuels, des barres d'outils, des contrôleurs de menu, ou des sous-menus.

valide pour : Button, Combo
DefaultDisabled
Par défaut, la commande est désactivée si le VSPackage qui implémente la commande n'est pas chargé ou la méthode de QueryStatus n'a pas été appelée.

valide pour : Button, Combo
DefaultInvisible
Par défaut, la commande est invisible si le VSPackage qui implémente la commande n'est pas chargé ou la méthode de QueryStatus n'a pas été appelée.

Doit être associée à la balise d' DynamicVisibility .

valide pour : Button, Combo, Menu
DynamicVisibility
La visibilité de la commande peut être modifiée à l'aide de la méthode ou un contexte GUID de QueryStatus inclus dans la section d' VisibilityConstraints .

S'applique aux commandes qui s'affichent dans les menus, et non sur les barres d'outils. Les éléments de niveau supérieur de barre d'outils peuvent être désactivés, mais ne pas être masqués, lorsque la balise d'OLECMDF_INVISIBLE est retournée à partir de la méthode de QueryStatus.

Dans un menu, cet indicateur indique également qu'elle doit être automatiquement masquée lorsque ses membres sont masqués. Cette balise est généralement assignée à des sous-menus car les menus de niveau supérieur ont déjà ce comportement.

Doit être associée à la balise d' DefaultInvisible .

valide pour : Button, Combo, Menu
NoShowOnMenuController
Si une commande qui a cette balise est positionnée sur un contrôleur de menu, la commande ne s'affiche pas dans la liste déroulante.

valide pour : Button

Pour plus d'informations sur les indicateurs de commande, consultez la documentation de CommandFlag, élément .

Spécifications générales

Votre commande doit passer la série de tests suivante avant de pouvoir être affichées et activée :

la commande est positionnée correctement.
la balise d' DefaultInvisible n'est pas définie.
le menu ou la barre d'outils parent est visible.
La commande n'est pas invisible en raison d'une entrée de contexte dans la section de VisibilityConstraints, élément .
Code d'un VSPackage qui implémente l'interface d' IOleCommandTarget affiche et permet à votre commande. Aucun code d'interface ne l'a désactivé et a effectué sur celui-ci.
Lorsqu'un utilisateur clique sur votre commande, il est soumis à la procédure qui est encadré dans algorithme de routage des commandes.

appeler des commandes prédéfinies

UsedCommands, élément permet à des VSPackages pour accéder aux commandes qui sont fournies par l'autre des VSPackages ou par l'IDE. Pour ce faire, créez UsedCommand, élément qui a le GUID et l'ID de la commande à utiliser. Cela garantit que la commande sera chargée par Visual Studio, même si elle ne fait pas partie de la configuration actuelle de Visual Studio. Pour plus d'informations, consultez UsedCommand, élément.

Apparence des éléments de l'interface utilisateur

Les considérations pour sélectionner et positionner des éléments de commande sont les suivantes :

Visual Studio offre de nombreux éléments d'interface utilisateur qui s'affichent différemment selon le positionnement.
Un élément d'interface qui est définie à l'aide de la balise d' DefaultInvisible ne sera pas affiché dans l'IDE à moins qu'elles soient affichées par son implémentation d'un VSPackage de la méthode d' QueryStatus , ou est associé à un contexte particulier d'interface utilisateur dans la section d' VisibilityConstraints .
même une commande avec succès positionnée ne peut être affichée. Cela est dû au fait que les masque de l'IDE automatiquement ou affiche certaines commandes, selon les interfaces que le VSPackage (ou non) a implémentées. Par exemple, l'implémentation d'un VSPackage de certaines interfaces de génération entraîne des éléments de menu génération-mis en relation à afficher automatiquement.
Appliquer la balise d' CommandWellOnly dans la définition de l'élément d'interface signifie que la commande peut être ajoutée uniquement par la personnalisation.
Les commandes peuvent être disponibles uniquement dans certains contextes d'interface utilisateur, par exemple, uniquement lorsqu'une boîte de dialogue s'affiche lorsque l'IDE est en mode Design.
Pour que certains éléments d'interface utilisateur à afficher dans l'IDE, vous devez implémenter une ou plusieurs interfaces ou écrire du code.

Voir aussi

Concepts

Making Commands Available

Autres ressources

Tâches courantes avec des commandes, des menus, et les barres d'outils

Command Table Configuration (.ctc) Files

Command Table Format Reference

Command Routing in VSPackages

Partager via