Comment les VSPackages ajoutent des éléments d’interface utilisateur

Un VSPackage peut ajouter des éléments d’interface utilisateur (UI), par exemple, des menus, des barres d’outils et des fenêtres d’outils à Visual Studio au moyen du fichier .vsct .

Vous trouverez des instructions de conception pour les éléments d’interface utilisateur dans les instructions relatives à l’expérience utilisateur visual Studio.

Architecture de la table de commandes Visual Studio

Comme indiqué, l’architecture de la table de commandes prend en charge les principes architecturaux précédents. Les principes derrière les abstractions, les structures de données et les outils de l’architecture de table de commandes sont les suivants :

• Il existe trois types d’éléments de base : menus, commandes et groupes. Les menus peuvent être exposés dans l’interface utilisateur en tant que menus, sous-menus, barres d’outils ou fenêtres d’outils. Les commandes sont des procédures que l’utilisateur peut exécuter dans l’IDE, et elles peuvent être exposées en tant qu’éléments de menu, boutons, zones de liste ou autres contrôles. Les groupes sont des conteneurs pour les menus et les commandes.

• Chaque élément est spécifié par une définition qui décrit l’élément, sa priorité par rapport à d’autres éléments et les indicateurs qui modifient son comportement.

• Chaque élément a un emplacement qui décrit le parent de l’élément. Un élément peut avoir plusieurs parents, afin qu’il puisse apparaître à plusieurs emplacements dans l’interface utilisateur.

Chaque commande doit avoir un groupe en tant que parent, même s’il est le seul enfant de ce groupe. Chaque menu standard doit également avoir un groupe parent. Les barres d’outils et les fenêtres d’outils agissent comme leurs propres parents. Un groupe peut avoir comme parent la barre de menus principale de Visual Studio, ou n’importe quel menu, barre d’outils ou fenêtre outil.

Définition des éléments

Un fichier .vsct est mis en forme en XML. Il 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 commande dans le package reçoit d’abord un GUID et un ID dans la Symbols section. Tout au long du reste du fichier .vsct , chaque menu, commande et groupe est identifié par sa combinaison GUID et ID. L’exemple suivant montre une section classique Symbols générée par le modèle de package Visual Studio lorsqu’une commande de menu est sélectionnée 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 Symbols section est l’élément GuidSymbol. GuidSymbol les éléments mappent les noms aux GUID utilisés par l’IDE pour identifier les packages et leurs composants.

Le premier GuidSymbol élément, guid<PackageName>Pkgest le GUID du package lui-même. Il s’agit du GUID utilisé par Visual Studio pour charger le package. En règle générale, il n’a pas d’éléments enfants.

Par convention, les menus et les commandes sont regroupés sous un deuxième GuidSymbol élément, guid<PackageName>CmdSetet les bitmaps se trouvent sous un troisième GuidSymbol élément. guidImages Vous n’avez pas besoin de suivre cette convention, mais chaque menu, groupe, commande et bitmap doit être un enfant d’un GuidSymbol élément.

Dans le deuxième GuidSymbol élément, qui représente le jeu de commandes du package, sont plusieurs IDSymbol éléments. Chaque élément IDSymbol 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 IDSymbol éléments du troisième GuidSymbol élément représentent des bitmaps qui peuvent être utilisées comme icônes pour les commandes. Étant donné que les paires GUID/ID doivent être uniques dans une application, aucun deux enfants du même GuidSymbol élément peuvent avoir la même valeur.

Menus, groupes et commandes

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

• Attribut guid qui correspond au nom de l’élément GuidSymbol sous lequel l’élément d’interface utilisateur est défini.

• Attribut id qui correspond au nom de l’élément associé IDSymbol .

Ensemble, les attributs et id les guid attributs composent la signature de l’élément d’interface utilisateur.

• Attribut priority qui détermine le placement de l’élément d’interface utilisateur dans son menu ou groupe parent.

• Élément Parent qui a guid et id attributs qui spécifient la signature du menu ou du groupe parent.

Menus

Chaque menu est défini en tant qu’élément Menu dans la Menus section. Les menus doivent avoir guiddes attributs, iddes priority attributs et un Parent élément, ainsi que les attributs et enfants supplémentaires suivants :

• Attribut type qui spécifie si le menu doit apparaître dans l’IDE en tant que type de menu ou en tant que barre d’outils.

• Élément Strings qui contient un élément ButtonText, qui spécifie le titre du menu dans l’IDE et un élément CommandName, qui spécifie le nom utilisé dans la fenêtre Commande pour accéder au menu.

• Indicateurs facultatifs. Un élément CommandFlag peut apparaître dans une définition de menu pour modifier son apparence ou son comportement dans l’IDE.

Chaque Menu élément doit avoir un groupe comme parent, sauf s’il s’agit d’un élément dockable tel qu’une barre d’outils. Un menu ancre est son propre parent. Pour plus d’informations sur les menus et les valeurs de l’attributtype, consultez la documentation de l’élément Menu.

L’exemple suivant montre un menu qui s’affiche dans la barre de menus de Visual Studio, en regard du menu 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>

Groupes

Un groupe est un élément défini dans la Groups section du fichier .vsct . Les groupes ne sont que des conteneurs. Ils n’apparaissent pas dans l’IDE, à l’exception d’une ligne de division dans un menu. Par conséquent, un élément Group est défini uniquement par sa signature, sa priorité et son parent.

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

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

Étant donné qu’il fait partie d’un menu, ce groupe contient généralement des commandes. Toutefois, il peut également contenir d’autres menus. Il s’agit de la façon dont les sous-menus sont définis, comme illustré 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 fournie à l’IDE est définie comme un élément Button ou un élément Combo. Pour apparaître dans un menu ou une barre d’outils, la commande doit avoir un groupe en tant que parent.

Boutons

Les boutons sont définis dans la Buttons section. Tout élément de menu, bouton ou autre élément sur lequel un utilisateur clique pour exécuter une seule commande est considéré comme un bouton. Certains types de boutons peuvent également inclure des fonctionnalités de liste. Les boutons ont les mêmes attributs obligatoires et facultatifs que les menus, et peuvent également avoir un élément Icon 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 l’élément Buttons.

Le bouton de l’exemple suivant est un enfant du groupe dans l’exemple précédent et apparaît 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 Combos section. Chaque Combo élément représente une zone de liste déroulante dans l’IDE. La zone de liste peut ou non être accessible en écriture par les utilisateurs, en fonction de la valeur de l’attribut type de la liste déroulante. Les combos ont les mêmes éléments et comportement que ceux dont disposent les boutons, et peuvent également avoir les attributs supplémentaires suivants :

• Attribut defaultWidth qui spécifie la largeur des pixels.

• Attribut idCommandList qui spécifie une liste qui contient les éléments affichés dans la zone de liste. La liste de commandes doit être déclarée dans le même GuidSymbol nœud que celui qui contient la liste déroulante.

L’exemple suivant définit un élément combo.

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

Images bitmap

Les commandes qui seront affichées avec une icône doivent inclure un Icon élément qui fait référence à une bitmap à l’aide de son GUID et de son ID. Chaque bitmap est définie en tant qu’élément Bitmap dans la Bitmaps section. Les seuls attributs requis pour une Bitmap définition sont guid et href, ce qui pointe vers le fichier source. Si le fichier source est une bande de ressources, un attribut usedList est également nécessaire pour répertorier les images disponibles dans la bande. Pour plus d’informations, consultez la documentation de l’élément Bitmap.

Parentales

Les règles suivantes régissent la façon dont un élément peut appeler un autre élément en tant que parent.

Menu, commande et placement de groupe

Un menu, un groupe ou une commande peut apparaître à plusieurs emplacements dans l’IDE. Pour qu’un élément apparaisse à plusieurs emplacements, il doit être ajouté à la CommandPlacements section en tant qu’élément CommandPlacement. N’importe quel menu, groupe ou commande peut être ajouté en tant que placement de commandes. Toutefois, les barres d’outils ne peuvent pas être positionnées de cette façon, car elles ne peuvent pas apparaître dans plusieurs emplacements sensibles au contexte.

Les placements de commandes ont guid, idet priority les attributs. Le GUID et l’ID doivent correspondre à ceux de l’élément positionné. L’attribut priority régit le placement de l’élément en ce qui concerne les autres éléments. Lorsque l’IDE fusionne deux éléments ou plus ayant la même priorité, leurs placements ne sont pas dé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 apparaît à plusieurs emplacements, tous les enfants de ce menu ou groupe apparaissent dans chaque instance.

Visibilité et contexte des commandes

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

Contraintes de visibilité

Une contrainte de visibilité est définie en tant qu’élément VisibilityItem dans la VisibilityConstraints section. Une contrainte de visibilité définit des contextes d’interface utilisateur spécifiques dans lesquels l’élément cible est visible. Un menu ou une commande inclus dans cette section n’est visible que 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.

VisibilityItem les éléments doivent avoir trois attributs, comme suit : l’élément guid d’interface id utilisateur cible et context. L’attribut context spécifie quand l’élément cible sera visible et prend n’importe quel contexte d’interface utilisateur valide comme valeur. Les constantes de contexte de l’interface utilisateur pour Visual Studio sont membres de la VSConstants classe. Chaque VisibilityItem élément ne peut prendre qu’une seule valeur de contexte. Pour appliquer un deuxième contexte, créez un deuxième VisibilityItem élément qui pointe vers le même élément, comme illustré 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 indicateurs de commande suivants peuvent affecter la visibilité des menus et des commandes auxquels ils s’appliquent.

AlwaysCreate Le menu est créé même s’il n’a pas de groupes ou de boutons.

Valide pour : Menu

CommandWellOnly Appliquez cet indicateur si la commande n’apparaît pas dans le menu de niveau supérieur et que vous souhaitez la rendre disponible pour une personnalisation d’interpréteur de commandes supplémentaire, par exemple, la lier à une clé. Une fois le VSPackage installé, un utilisateur peut personnaliser ces commandes en ouvrant la boîte de dialogue Options , puis en modifiant l’emplacement des commandes sous la catégorie Environnement du clavier. N’affecte pas le positionnement sur les menus contextuels, les barres d’outils, les contrôleurs de menu ou les 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 que la méthode 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 si la méthode QueryStatus n’a pas été appelée.

Doit être combiné avec l’indicateur DynamicVisibility .

Valide pour : Button, , ComboMenu

DynamicVisibility La visibilité de la commande peut être modifiée à l’aide de la QueryStatus méthode ou d’un GUID de contexte inclus dans la VisibilityConstraints section.

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

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

Doit être combiné avec l’indicateur DefaultInvisible .

Valide pour : Button, , ComboMenu

NoShowOnMenuController Si une commande avec cet indicateur est positionnée sur un contrôleur de menu, la commande n’apparaît pas dans la liste déroulante.

Valide pour : Button

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

Exigences générales

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

• La commande est positionnée correctement.

• L’indicateur DefaultInvisible n’est pas défini.

• Le menu parent ou la barre d’outils est visible.

• La commande n’est pas invisible en raison d’une entrée de contexte dans la section élément VisibilityConstraints.

• Le code VSPackage qui implémente l’interface IOleCommandTarget affiche et active votre commande. Aucun code d’interface l’a intercepté et a agi dessus.

• Lorsqu’un utilisateur clique sur votre commande, il est soumis à la procédure décrite dans l’algorithme de routage.

Appeler des commandes prédéfinies

L’élément UsedCommands permet aux VSPackages d’accéder aux commandes fournies par d’autres VSPackages ou par l’IDE. Pour ce faire, créez un élément UsedCommand 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 l’élément UsedCommand.

Apparence de l’élément interface

Les considérations relatives à la sélection et au positionnement d’éléments de commande sont les suivantes :

• Visual Studio propose de nombreux éléments d’interface utilisateur qui apparaissent différemment en fonction du positionnement.

• Un élément d’interface utilisateur défini à l’aide de l’indicateur DefaultInvisible ne s’affiche pas dans l’IDE, sauf s’il est affiché par son implémentation VSPackage de la QueryStatus méthode, ou associé à un contexte d’interface utilisateur particulier dans la VisibilityConstraints section.

• Même une commande correctement positionnée peut ne pas être affichée. Cela est dû au fait que l’IDE masque ou affiche automatiquement certaines commandes, en fonction des interfaces que VSPackage a (ou n’a pas) implémentées. Par exemple, l’implémentation d’un VSPackage de certaines interfaces de génération entraîne l’affichage automatique des éléments de menu liés à la génération.

• L’application de l’indicateur CommandWellOnly dans la définition de l’élément d’interface utilisateur signifie que la commande ne peut être ajoutée qu’en personnalisation.

• Les commandes peuvent être disponibles uniquement dans certains contextes d’interface utilisateur, par exemple quand une boîte de dialogue s’affiche lorsque l’IDE est en mode Création.

• Pour que certains éléments d’interface utilisateur soient affichés dans l’IDE, vous devez implémenter une ou plusieurs interfaces ou écrire du code.

Contenu connexe

• Étendre les menus et les commandes