Share via

Come i pacchetti VSPackage aggiungono elementi dell'interfaccia utente

  • Articolo

Un VSPackage può aggiungere elementi dell'interfaccia utente, ad esempio menu, barre degli strumenti e finestre degli strumenti, a Visual Studio tramite il file vsct .

È possibile trovare linee guida per la progettazione per gli elementi dell'interfaccia utente in Linee guida per l'esperienza utente di Visual Studio.

Architettura della tabella dei comandi di Visual Studio

Come indicato, l'architettura della tabella dei comandi supporta i principi architetturali precedenti. I principi dietro le astrazioni, le strutture di dati e gli strumenti dell'architettura della tabella dei comandi sono i seguenti:

  • Esistono tre tipi di elementi di base: menu, comandi e gruppi. I menu possono essere esposti nell'interfaccia utente come menu, sottomenu, barre degli strumenti o finestre degli strumenti. I comandi sono procedure che l'utente può eseguire nell'IDE e può essere esposto come voci di menu, pulsanti, caselle di riepilogo o altri controlli. I gruppi sono contenitori sia per i menu che per i comandi.

  • Ogni elemento viene specificato da una definizione che descrive l'elemento, la relativa priorità rispetto ad altri elementi e i flag che ne modificano il comportamento.

  • Ogni elemento ha una posizione che descrive l'elemento padre dell'elemento. Un elemento può avere più elementi padre, in modo che possa essere visualizzato in più posizioni nell'interfaccia utente.

Ogni comando deve avere un gruppo come padre, anche se è l'unico elemento figlio in tale gruppo. Ogni menu standard deve avere anche un gruppo padre. Le barre degli strumenti e le finestre degli strumenti fungono da elementi padre. Un gruppo può avere come elemento padre la barra dei menu principale di Visual Studio o qualsiasi menu, barra degli strumenti o finestra degli strumenti.

Modalità di definizione degli elementi

Un file con estensione vsct è formattato in XML. Definisce gli elementi dell'interfaccia utente per un pacchetto e determina dove vengono visualizzati nell'IDE. A ogni menu, gruppo o comando nel pacchetto viene assegnato un GUID e un ID nella Symbols sezione. Nel resto del file vsct , ogni menu, comando e gruppo viene identificato dalla combinazione GUID e ID. L'esempio seguente mostra una sezione tipica Symbols generata dal modello di pacchetto di Visual Studio quando viene selezionato un comando di menu nel modello.

<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'elemento di primo livello della Symbols sezione è l'elemento GuidSymbol. GuidSymbol gli elementi eseguono il mapping dei nomi ai GUID usati dall'IDE per identificare i pacchetti e le relative parti del componente.

Nota

I GUID vengono generati automaticamente dal modello di pacchetto di Visual Studio. È anche possibile creare un GUID univoco facendo clic su Crea GUID dal menu Strumenti .

Il primo GuidSymbol elemento, guid<PackageName>Pkg, è il GUID del pacchetto stesso. Si tratta del GUID usato da Visual Studio per caricare il pacchetto. In genere, non dispone di elementi figlio.

Per convenzione, i menu e i comandi vengono raggruppati in un secondo GuidSymbol elemento, guid<PackageName>CmdSete le bitmap si trovano in un terzo GuidSymbol elemento, guidImages. Non è necessario seguire questa convenzione, ma ogni menu, gruppo, comando e bitmap deve essere figlio di un GuidSymbol elemento.

Nel secondo GuidSymbol elemento, che rappresenta il set di comandi del pacchetto, sono diversi IDSymbol elementi. Ogni elemento IDSymbol esegue il mapping di un nome a un valore numerico e può rappresentare un menu, un gruppo o un comando che fa parte del set di comandi. Gli IDSymbol elementi nel terzo GuidSymbol elemento rappresentano bitmap che possono essere usate come icone per i comandi. Poiché le coppie GUID/ID devono essere univoce in un'applicazione, non è possibile che due elementi figlio dello stesso elemento abbiano lo stesso GuidSymbol valore.

Quando un menu, un gruppo o un comando ha un GUID e un ID, può essere aggiunto all'IDE. Ogni elemento dell'interfaccia utente deve avere gli elementi seguenti:

  • Attributo guid che corrisponde al nome dell'elemento GuidSymbol in cui è definito l'elemento dell'interfaccia utente.

  • Attributo id che corrisponde al nome dell'elemento associato IDSymbol .

Insieme, gli guid attributi e id compongono la firma dell'elemento dell'interfaccia utente.

  • Attributo priority che determina la posizione dell'elemento dell'interfaccia utente nel menu o nel gruppo padre.

  • Elemento Parent con attributi e id che guid specificano la firma del menu o del gruppo padre.

Ogni menu è definito come elemento Menu nella Menus sezione . I menu devono avere guidattributi , ide priority e un Parent elemento e anche gli attributi e gli elementi figlio aggiuntivi seguenti:

  • Attributo type che specifica se il menu deve essere visualizzato nell'IDE come tipo di menu o come barra degli strumenti.

  • Elemento Strings che contiene un elemento ButtonText, che specifica il titolo del menu nell'IDE e un elemento CommandName, che specifica il nome utilizzato nella finestra Command per accedere al menu.

  • Flag facoltativi. Un elemento CommandFlag può essere visualizzato in una definizione di menu per modificarne l'aspetto o il comportamento nell'IDE.

Ogni Menu elemento deve avere un gruppo come elemento padre, a meno che non sia un elemento ancorabile, ad esempio una barra degli strumenti. Un menu ancorabile è un proprio elemento padre. Per altre informazioni sui menu e i valori per l'attributo type , vedere la documentazione relativa agli elementi menu.

L'esempio seguente mostra un menu visualizzato nella barra dei menu di Visual Studio, accanto al menu Strumenti .

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

Gruppi

Un gruppo è un elemento definito nella Groups sezione del file vsct . I gruppi sono solo contenitori. Non vengono visualizzati nell'IDE, ad eccezione di una riga di divisione in un menu. Pertanto, un elemento Group viene definito solo dalla firma, dalla priorità e dall'elemento padre.

Un gruppo può avere un menu, un altro gruppo o se stesso come padre. Tuttavia, l'elemento padre è in genere un menu o una barra degli strumenti. Il menu nell'esempio precedente è un elemento figlio del gruppo e tale IDG_VS_MM_TOOLSADDINS gruppo è un elemento figlio della barra dei menu di Visual Studio. Il gruppo nell'esempio seguente è un elemento figlio del menu nell'esempio precedente.

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

Poiché fa parte di un menu, questo gruppo in genere contiene comandi. Tuttavia, potrebbe anche contenere altri menu. Questo è il modo in cui vengono definiti i sottomenu, come illustrato nell'esempio seguente.

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

Comandi

Un comando fornito all'IDE viene definito come un elemento Button o un elemento Combo. Per essere visualizzato in un menu o in una barra degli strumenti, il comando deve avere un gruppo come elemento padre.

Pulsanti

I pulsanti sono definiti nella Buttons sezione . Qualsiasi voce di menu, pulsante o altro elemento che un utente fa clic per eseguire un singolo comando è considerato un pulsante. Alcuni tipi di pulsante possono includere anche la funzionalità elenco. I pulsanti hanno gli stessi attributi obbligatori e facoltativi che i menu hanno e possono avere anche un elemento Icon che specifica il GUID e l'ID della bitmap che rappresenta il pulsante nell'IDE. Per altre informazioni sui pulsanti e sui relativi attributi, vedere la documentazione relativa agli elementi Buttons.

Il pulsante nell'esempio seguente è un elemento figlio del gruppo nell'esempio precedente e viene visualizzato nell'IDE come voce di menu nel menu padre di tale gruppo.

<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

Le combinazioni vengono definite nella Combos sezione . Ogni Combo elemento rappresenta una casella di riepilogo a discesa nell'IDE. La casella di riepilogo può essere o meno scrivibile dagli utenti, a seconda del valore dell'attributo type della combinazione. Le combinazioni hanno gli stessi elementi e gli stessi comportamenti dei pulsanti e possono avere anche gli attributi aggiuntivi seguenti:

  • Attributo defaultWidth che specifica la larghezza dei pixel.

  • Attributo idCommandList che specifica un elenco contenente gli elementi visualizzati nella casella di riepilogo. L'elenco di comandi deve essere dichiarato nello stesso GuidSymbol nodo che contiene la combinazione.

Nell'esempio seguente viene definito un elemento combinato.

<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

I comandi che verranno visualizzati insieme a un'icona devono includere un Icon elemento che fa riferimento a una bitmap usando il GUID e l'ID. Ogni bitmap viene definita come elemento Bitmap nella Bitmaps sezione . Gli unici attributi obbligatori per una Bitmap definizione sono guid e href, che punta al file di origine. Se il file di origine è una striscia di risorse, è necessario anche un attributo usedList per elencare le immagini disponibili nella striscia. Per altre informazioni, vedere la documentazione relativa agli elementi Bitmap.

Genitorialità

Le regole seguenti regolano il modo in cui un elemento può chiamare un altro elemento come elemento padre.

Elemento Definito in questa sezione della tabella dei comandi Può essere contenuto (come elemento padre o posizionandolo nella CommandPlacements sezione o in entrambi) Può contenere (denominata padre)
Raggruppa Elemento Groups, IDE, altri VSPackage Un menu, un gruppo, l'elemento stesso Menu, gruppi e comandi
Menu Elemento Menus, IDE, altri VSPackage Da 1 a n gruppi Da 0 a n gruppi
Barra degli strumenti Elemento Menus, IDE, altri VSPackage Elemento stesso Da 0 a n gruppi
MenuItem Elemento Buttons, IDE, altri VSPackage Da 1 a n gruppi, l'elemento stesso Da -0 a n gruppi
Pulsante Elemento Buttons, IDE, altri VSPackage Da 1 a n gruppi, l'elemento stesso
Combinato Elemento Combos, IDE, altri VSPackage Da 1 a n gruppi, l'elemento stesso

Un menu, un gruppo o un comando può essere visualizzato in più posizioni nell'IDE. Affinché un elemento venga visualizzato in più posizioni, deve essere aggiunto alla CommandPlacements sezione come elemento CommandPlacement. Qualsiasi menu, gruppo o comando può essere aggiunto come posizionamento dei comandi. Tuttavia, le barre degli strumenti non possono essere posizionate in questo modo perché non possono essere visualizzate in più posizioni sensibili al contesto.

I posizionamenti dei comandi hanno guidattributi , ide priority . Il GUID e l'ID devono corrispondere a quelli dell'elemento posizionato. L'attributo priority regola la posizione dell'elemento rispetto ad altri elementi. Quando l'IDE unisce due o più elementi con la stessa priorità, i posizionamenti non sono definiti perché l'IDE non garantisce che le risorse del pacchetto vengano lette nello stesso ordine ogni volta che viene compilato il pacchetto.

Se un menu o un gruppo viene visualizzato in più posizioni, tutti gli elementi figlio di tale menu o gruppo verranno visualizzati in ogni istanza.

Visibilità e contesto dei comandi

Quando vengono installati più pacchetti VSPackage, una gamma di menu, voci di menu e barre degli strumenti può ingombrare l'IDE. Per evitare questo problema, è possibile controllare la visibilità dei singoli elementi dell'interfaccia utente usando vincoli di visibilità e flag di comando.

Vincoli di visibilità

Un vincolo di visibilità viene impostato come elemento VisibilityItem nella VisibilityConstraints sezione . Un vincolo di visibilità definisce contesti di interfaccia utente specifici in cui l'elemento di destinazione è visibile. Un menu o un comando incluso in questa sezione è visibile solo quando uno dei contesti definiti è attivo. Se in questa sezione non viene fatto riferimento a un menu o a un comando, è sempre visibile per impostazione predefinita. Questa sezione non si applica ai gruppi.

VisibilityItem Gli elementi devono avere tre attributi, come indicato di seguito: e guidid dell'elemento dell'interfaccia utente di destinazione e context. L'attributo context specifica quando l'elemento di destinazione sarà visibile e accetta qualsiasi contesto dell'interfaccia utente valido come valore. Le costanti del contesto dell'interfaccia utente per Visual Studio sono membri della VSConstants classe . Ogni VisibilityItem elemento può accettare un solo valore di contesto. Per applicare un secondo contesto, creare un secondo VisibilityItem elemento che punta allo stesso elemento, come illustrato nell'esempio seguente.

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

Flag di comando

I flag di comando seguenti possono influire sulla visibilità dei menu e dei comandi a cui si applicano.

AlwaysCreate Il menu viene creato anche se non dispone di gruppi o pulsanti.

Valido per: Menu

CommandWellOnly Applica questo flag se il comando non viene visualizzato nel menu di primo livello e vuoi renderlo disponibile per una personalizzazione aggiuntiva della shell, ad esempio associandolo a una chiave. Dopo aver installato il pacchetto VSPackage, un utente può personalizzare questi comandi aprendo la finestra di dialogo Opzioni e quindi modificando il posizionamento dei comandi nella categoria Ambiente tastiera. Non influisce sul posizionamento nei menu di scelta rapida, nelle barre degli strumenti, nei controller di menu o nei sottomenu.

Valido per: Button, Combo

DefaultDisabled Per impostazione predefinita, il comando è disabilitato se il VSPackage che implementa il comando non viene caricato o il metodo QueryStatus non è stato chiamato.

Valido per: Button, Combo

DefaultInvisible Per impostazione predefinita, il comando è invisibile se il VSPackage che implementa il comando non viene caricato o il metodo QueryStatus non è stato chiamato.

Deve essere combinato con il DynamicVisibility flag .

Valido per: Button, Combo, Menu

DynamicVisibility La visibilità del comando può essere modificata usando il QueryStatus metodo o un GUID di contesto incluso nella VisibilityConstraints sezione .

Si applica ai comandi visualizzati nei menu, non sulle barre degli strumenti. Gli elementi della barra degli strumenti di primo livello possono essere disabilitati, ma non nascosti, quando il OLECMDF_INVISIBLE flag viene restituito dal QueryStatus metodo .

In un menu, questo flag indica anche che deve essere nascosto automaticamente quando i relativi membri sono nascosti. Questo flag viene in genere assegnato a sottomenu perché i menu di primo livello hanno già questo comportamento.

Deve essere combinato con il DefaultInvisible flag .

Valido per: Button, Combo, Menu

NoShowOnMenuController Se un comando con questo flag è posizionato in un controller di menu, il comando non viene visualizzato nell'elenco a discesa.

Valido per: Button

Per altre informazioni sui flag di comando, vedere la documentazione dell'elemento CommandFlag.

Requisiti generali

Il comando deve superare la serie di test seguente prima che possa essere visualizzata e abilitata:

  • Il comando è posizionato correttamente.

  • Il DefaultInvisible flag non è impostato.

  • Il menu padre o la barra degli strumenti è visibile.

  • Il comando non è invisibile a causa di una voce di contesto nella sezione elemento VisibilityConstraints .

  • Codice VSPackage che implementa l'interfaccia IOleCommandTarget visualizza e abilita il comando. Nessun codice di interfaccia l'intercetta e ha agito su di esso.

  • Quando un utente fa clic sul comando, diventa soggetto alla procedura descritta in Algoritmo di routing.

Chiamare comandi predefiniti

L'elemento UsedCommands consente ai pacchetti VSPackage di accedere ai comandi forniti da altri pacchetti VSPackage o dall'IDE. A tale scopo, creare un elemento UsedCommand con il GUID e l'ID del comando da usare. In questo modo, il comando verrà caricato da Visual Studio, anche se non fa parte della configurazione corrente di Visual Studio. Per altre informazioni, vedere Elemento UsedCommand.

Aspetto dell'elemento di interfaccia

Le considerazioni relative alla selezione e al posizionamento degli elementi di comando sono le seguenti:

  • Visual Studio offre molti elementi dell'interfaccia utente visualizzati in modo diverso a seconda del posizionamento.

  • Un elemento dell'interfaccia utente definito tramite il DefaultInvisible flag non verrà visualizzato nell'IDE a meno che non venga visualizzato dalla relativa implementazione VSPackage del QueryStatus metodo o associato a un particolare contesto dell'interfaccia utente nella VisibilityConstraints sezione.

  • Anche un comando posizionato correttamente potrebbe non essere visualizzato. Questo avviene perché l'IDE nasconde o visualizza automaticamente alcuni comandi, a seconda delle interfacce che il pacchetto VSPackage ha o non ha implementato. Ad esempio, l'implementazione di un VSPackage di alcune interfacce di compilazione determina la visualizzazione automatica delle voci di menu correlate alla compilazione.

  • L'applicazione del CommandWellOnly flag nella definizione dell'elemento dell'interfaccia utente significa che il comando può essere aggiunto solo dalla personalizzazione.

  • I comandi possono essere disponibili solo in determinati contesti dell'interfaccia utente, ad esempio solo quando viene visualizzata una finestra di dialogo quando l'IDE è in visualizzazione struttura.

  • Per fare in modo che determinati elementi dell'interfaccia utente vengano visualizzati nell'IDE, è necessario implementare una o più interfacce o scrivere codice.

Contenuto correlato