Compartilhar via

Como a VSPackages adicionar elementos de Interface do usuário ao IDE

  • Artigo

Um VSPackage pode adicionar elementos de interface (UI) do usuário, por exemplo, menus, barras de ferramentas e janelas de ferramentas, para o Visual Studio (IDE) do ambiente de desenvolvimento integrado.

Princípios de arquitetura

O conjunto de regras e estruturas que permitem a um VSPackage personalizar a interface do usuário é chamado de Arquitetura de tabela do comando. A arquitetura da tabela de comando é baseada em princípios de design a seguir:

  • A interface do usuário não deve ser livre ou confusos.

  • A interface do usuário deve ser dinâmico e estático não.

  • A interface do usuário deve ser personalizável.

  • A interface do usuário deve ser úteis.

A interface do usuário não deve ser livre ou confuso

  • Vários VSPackages pode ser instalados na sessão Visual Studio que hospeda seu VSPackage. Quando seu VSPackage adiciona comandos, ele não deve interromper VSPackages previamente instalados, mas ele também deve disponibilizar seus recursos para os outros VSPackages e habilitá-los contribuir com recursos de retorno.

  • Cada menu, se ele é acessado usando a barra de menus principal, um submenu ou um menu de atalho, pode conter itens de menu que são doados por outros VSPackages. Portanto, tenha cuidado para não overcrowd a interface do usuário. Se muitos comandos são exibidos ao mesmo tempo, a interface do usuário poderá confundir os usuários.

A interface do usuário deve ser dinâmico e estático não

  • Comandos podem ser exibidos ou ocultos a qualquer momento, dependendo do estado dos dados subjacentes e a atividade do usuário atual.

  • Um VSPackage deve ser habilitado para alterar o rótulo de um item de interface do usuário e também o conteúdo de suas caixas de combinação ou menus.

  • Os itens de interface do usuário talvez precise ser adicionados ou removidos quando o VSPackage é usado.

  • Os itens de interface do usuário podem exigir mais chamadas para o VSPackage para preencher seus valores ou detectar seu estado atual. Exemplos desses itens incluem listas de usados mais recentemente (MRU) arquivos, caixas de combinação e seletores de cor ou textura.

  • Ela pode melhorar a experiência do usuário para adicionar o comando menus em outros VSPackages. Por exemplo, se se parece com o comando que você fornecer Copy, você pode colocar seu comando em cada VSPackage onde Copy aparece.

A interface do usuário deve ser personalizável

  • A qualquer momento, o usuário pode personalizar os elementos de interface do usuário em seu VSPackage, por exemplo, adicionando um botão para uma janela de ferramenta ou reorganizando um menu. No entanto, em alguns casos, talvez você queira desativar a personalização.

  • Alguns comandos estão disponíveis somente através do uso de personalização; ou seja, um comando pode não estar disponível em um menu ou barra de ferramentas até que um usuário adiciona-lo usando o Personalizar caixa de diálogo.

  • A qualquer momento, o usuário pode personalizar os atalhos de teclado para seus comandos, juntamente com os atalhos de teclado dos comandos de Visual Studio e outros VSPackages.

  • Os comandos podem ser executados usando o comando janela. Portanto, o IDE possui saber que comando corresponde a um rótulo de um determinado comando. O IDE realiza isso por meio de um processo conhecido como canonização, onde os espaços são removidos para compactar um nome de comando em uma única palavra. Por exemplo, a padronização de ' & Abrir arquivo ' é 'FileOpen'.

A interface do usuário deve ser úteis

  • A maioria dos itens de interface do usuário deve ter as dicas de ferramentas.

  • Para obter melhor desempenho, o VSPackage deve carregar somente quando uma das funções é invocada. Isso é conhecido como "atrasada carregando".

  • Adições ao IDE solicitado por um VSPackage devem ser localizáveis.

  • Você pode usar bitmaps que estão incluídos no Visual Studio ou você pode fornecer seu próprio.

A arquitetura de tabela de comando Visual Studio

Como observado, a arquitetura da tabela de comando suporta os princípios de arquitetura precedente. Estas são as filosofias por trás de abstrações, estruturas de dados e ferramentas da arquitetura de tabela do comando:

  • Há três tipos básicos de itens: menus, comandos e grupos. Menus podem ser expostos na interface de usuário como menus, submenus, barras de ferramentas ou janelas de ferramentas. Comandos são procedimentos que o usuário pode executar no IDE, e eles podem ser expostos como itens de menu, botões, caixas de listagem ou outros controles. Os grupos são recipientes para os menus e comandos.

  • Cada item é especificado por uma definição que descreve o item, sua prioridade em relação a outros itens e os sinalizadores que modificam seu comportamento.

  • Cada item possui um posicionamento que descreve o pai do item. Um item pode ter vários pais, para que ele pode ser exibido em vários locais na interface de usuário.

    Cada comando deve ter um grupo pai, mesmo se ele for o único filho desse grupo. Cada menu padrão também deve ter um grupo pai. Barras de ferramentas e janelas de ferramentas agem como seus próprios pais. Um grupo pode ter como seu pai, a barra de menus principal do Visual Studio, ou qualquer menu, barra de ferramentas ou janela de ferramenta.

Como os itens são definidos

.VSCT arquivos são formatados em XML. Um arquivo de .vsct define os elementos de interface do usuário para um pacote e determina onde esses elementos aparecem no IDE. Cada menu, um grupo ou um comando no pacote é atribuído pela primeira vez um GUID e ID na Symbols seção. Em todo o .vsct o arquivo, cada menu, comando e grupo é identificado por sua combinação de GUID e ID. O exemplo a seguir mostra uma típica Symbols seção conforme gerado pelo modelo de pacote de Visual Studio quando uma Comando de Menu está selecionado no modelo.

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

O elemento de nível superior a Symbols seção é o Elemento de GuidSymbol. GuidSymbolelementos de mapeiam nomes aos GUIDs são usados pelo IDE para identificar os pacotes e suas partes do componente.

Dica

GUIDs são gerados automaticamente pelo modelo de pacote de Visual Studio.Você também pode criar um GUID exclusivo, clicando em Criar GUID sobre o Ferramentas menu.

O primeiro GuidSymbol elemento, "guid [PackageName] Pkg", é o GUID do pacote em si. Este é o GUID que é usado por Visual Studio para carregar o pacote. Normalmente, ele não tem elementos filho.

Por convenção, os menus e comandos estão agrupados sob um segundo GuidSymbol elemento, "guid [PackageName] CmdSet", e os bitmaps são em um terceiro GuidSymbol elemento, "guidImages". Você não precisará seguir essa convenção, mas cada menu, o grupo, o comando e o bitmap devem ser um filho de um GuidSymbol elemento.

Na segunda GuidSymbol elemento, que representa o conjunto de comandos do pacote, são vários IDSymbol elementos. Cada Elemento de IDSymbol mapeia um nome para um valor numérico e pode representar um menu, um grupo ou um comando que faz parte do conjunto de comandos. O IDSymbol elementos no terceiro GuidSymbol elemento representam bitmaps que podem ser usados como ícones para comandos. Porque os pares GUID/ID devem ser exclusivos em um aplicativo, não há dois filhos do mesmo GuidSymbol elemento pode ter o mesmo valor.

Comandos de menus e grupos

Quando um menu, o grupo ou o comando tem um GUID e ID, ele pode ser adicionado ao IDE. Cada elemento de interface do usuário deve ter as seguintes ações:

  • A guid que corresponde ao nome do atributo de GuidSymbol elemento que o elemento de interface do usuário é definido em.

  • Um id atributo que corresponde ao nome de associado IDSymbol elemento.

    Juntos, o guid e id atributos compõem a assinatura do elemento da interface do usuário.

  • A priority atributo que determina o posicionamento do elemento da interface do usuário em seu menu pai ou grupo.

  • A Elemento pai que tem guid e id atributos que especificam a assinatura do menu pai ou grupo.

Cada menu é definido como um Elemento menu na Menus seção. Menus devem ter guid, id, e priority atributos e um Parent elemento e também os seguintes atributos adicionais e filhos:

Cada Menu elemento deve ter um grupo como seu pai, a menos que ele seja um elemento acoplável como, por exemplo, uma barra de ferramentas. Um menu acoplável é seu próprio pai. Para obter mais informações sobre a menus e os valores para o type de atributo, consulte o Elemento menu documentação.

O exemplo a seguir mostra um menu que aparece na barra de menus de Visual Studio, próxima a Ferramentas menu.

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

Grupos

Um grupo é um item que é definido na Groups seção do arquivo .vsct. Os grupos são apenas recipientes. Eles não aparecem no IDE, exceto como uma linha divisória em um menu. Portanto, um Elemento de grupo é definida somente por sua assinatura, a prioridade e o pai.

Um grupo pode ter um menu, outro grupo ou si mesmo como pai. No entanto, o pai é normalmente um menu ou barra de ferramentas. No menu do exemplo anterior é um filho a IDG_VS_MM_TOOLSADDINS grupo e esse grupo é um filho da barra de menus de Visual Studio. O grupo no exemplo a seguir é um filho do menu no exemplo anterior.

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

Porque ela é parte de um menu, esse grupo normalmente conteria comandos. No entanto, ele também pode conter outros menus. Isso é como submenus são definidas, conforme mostrado no exemplo a seguir.

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

Comandos

Um comando que é fornecido para o IDE é definido como um Elemento button ou um Elemento de combinação. Para aparecer em um menu ou uma barra de ferramentas, o comando deve ter um grupo pai.

Botões

Botões estão definidos na Buttons seção. Qualquer item de menu, botão ou outro elemento que um usuário clica para executar um comando único é considerado um botão. Alguns tipos de botão também podem incluir a funcionalidade de lista. Botões têm o mesmo necessária e os atributos opcionais que têm de menus e também pode ter um Elemento de ícone que especifica o GUID e a identificação do bitmap que representa o botão no IDE. Para obter mais informações sobre botões e seus atributos, consulte a Elemento de botões documentação.

O botão no exemplo a seguir é um filho do grupo no exemplo anterior e apareceria no IDE, como um item de menu no menu pai desse grupo.

<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

Combos são definidos na Combos seção. Cada Combo elemento representa uma caixa de listagem drop-down no IDE. A caixa de listagem pode ou não ser gravável por usuários, dependendo do valor da type atributo da combinação. Combos tem os mesmos elementos e têm comportamento botões e também pode ter os seguintes atributos adicionais:

  • A defaultWidth atributo que especifica a largura de pixel.

  • Um idCommandList atributo que especifica uma lista que contém os itens que são exibidos na caixa de listagem. A lista de comandos deve ser declarada na mesma GuidSymbol o nó que contém a combinação.

O exemplo a seguir define um elemento de combinação.

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

Bitmaps

Comandos que serão exibidos em conjunto com um ícone devem incluir um Icon elemento que se refere a um bitmap usando seu GUID e ID. Cada bitmap é definido como um Elemento de bitmap na Bitmaps seção. A única necessária atributos para um Bitmap definição são guid e href, que aponta para o arquivo de origem. Se o arquivo de origem é uma faixa de recursos, um usedList atributo também é necessário, para listar as imagens disponíveis na faixa do. Para mais informações, consulte a documentação do Elemento de bitmap.

Domínio pai

As regras a seguir controlam como um item pode chamar outro item pai.

Elemento

Definidos nesta seção da tabela de comandos

Podem estar contidos (como um pai, ou pelo posicionamento na CommandPlacements seção, ou ambos)

Pode conter (conhecido como um pai)

Group

Elemento de grupos, o IDE, outros VSPackages

Um menu, um grupo, o item propriamente dito

Comandos de menus e grupos

Menu

Elemento de menus, o IDE, outros VSPackages

1 para n grupos

0 a n grupos

Toolbar

Elemento de menus, o IDE, outros VSPackages

O item propriamente dito

0 a n grupos

Menu Item

Elemento de botões, o IDE, outros VSPackages

1 para n groups, o item propriamente dito

-0 para n grupos

Button

Elemento de botões, o IDE, outros VSPackages

1 para n groups, o item propriamente dito

Combinação

Elemento combos, o IDE, outros VSPackages

1 para n groups, o item propriamente dito

Um menu, o grupo ou o comando pode aparecer em mais de um local no IDE. Para um item seja exibido em vários locais, ele deve ser adicionado para o CommandPlacements seção como um Elemento de CommandPlacement. Qualquer menu, o grupo ou o comando pode ser adicionado como um posicionamento de comando. No entanto, as barras de ferramentas não podem ser posicionadas dessa maneira porque eles não podem aparecer em vários locais sensível ao contexto.

Comando colocações tem guid, id, e priority atributos. GUID e ID devem corresponder do item que está posicionado. O priority atributo administra o posicionamento do item com relação aos outros itens. Quando o IDE mescla dois ou mais itens que têm a mesma prioridade, suas colocações são indefinidas, porque o IDE não garante que recursos do pacote são lidos na mesma ordem, toda vez que o pacote é construído.

Se um menu ou um grupo é exibido em vários locais, todos os filhos do menu ou grupo será exibido em cada instância.

Contexto e a visibilidade de comando

Quando vários VSPackages são instalados, uma profusão de menus, itens de menu e barras de ferramentas pode truncar o IDE. Para evitar esse problema, você pode controlar a visibilidade dos elementos individuais da interface do usuário usando restrições de visibilidade e sinalizadores de comando.

Restrições de visibilidade

Uma restrição de visibilidade será definida como um Elemento de VisibilityItem na VisibilityConstraints seção. Uma restrição de visibilidade define contextos específicos de interface do usuário na qual o item de destino está visível. Um menu ou comando que está incluído nesta seção é visível somente quando um dos contextos definidos está ativo. Se um menu ou comando não é mencionado nesta seção, é sempre visível por padrão. Esta seção não se aplica a grupos.

VisibilityItemelementos devem ter os três atributos, como segue: o guid e id do elemento de interface do usuário de destino, e context. O context atributo especifica quando o item de destino será visível e leva a qualquer contexto válido da interface do usuário como seu valor. As constantes de contexto de interface do usuário para Visual Studio são membros do VSConstants classe. Cada VisibilityItem elemento pode ter o valor de apenas um contexto. Para aplicar a um contexto de segundo, crie uma segunda VisibilityItem elemento que aponta para o mesmo item, conforme mostrado no exemplo a seguir.

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

Sinalizadores de comando

Os seguintes sinalizadores de comando podem afetar a visibilidade dos menus e comandos que elas se aplicam ao.

  • AlwaysCreate
    Menu é criado, mesmo que ela tenha nenhum grupo ou os botões.

    Válido para:Menu

  • CommandWellOnly
    Aplique esse sinalizador se o comando não aparecer no menu de nível superior e você desejar torná-lo disponível para personalização adicional do shell, por exemplo, vinculá-la a uma chave. Depois que o VSPackage é instalado, o usuário pode personalizar esses comandos, abrindo o Opções caixa de diálogo e editando o posicionamento de comando sob o Teclado ambiente categoria. Não afeta a posição nos menus de atalho, barras de ferramentas, os controladores de menu ou submenus.

    Válido para: Button,Combo

  • DefaultDisabled
    Por padrão, o comando está desabilitado se o VSPackage que implementa o comando não está carregado ou não foi chamado o método QueryStatus.

    Válido para: Button,Combo

  • DefaultInvisible
    Por padrão, o comando é invisível, se o VSPackage que implementa o comando não está carregado ou não foi chamado o método QueryStatus.

    Deve ser combinado com o DynamicVisibility sinalizador.

    Valid for: Button, Combo,Menu

  • DynamicVisibility
    A visibilidade do comando pode ser alterada usando o método QueryStatus ou um GUID que é incluído do contexto do VisibilityConstraints seção.

    Aplica-se aos comandos que aparecem nos menus, não nas barras de ferramentas. Itens de nível superior da barra de ferramentas podem ser desativados, mas não ocultos, quando o sinalizador OLECMDF_INVISIBLE é retornado do método QueryStatus.

    Em um menu, esse sinalizador também indica que ele deve ser oculta automaticamente quando seus membros estão ocultos. Esse sinalizador é geralmente atribuído aos submenus, porque os menus de nível superior já tem esse comportamento.

    Deve ser combinado com o DefaultInvisible sinalizador.

    Valid for: Button, Combo,Menu

  • NoShowOnMenuController
    Se um comando que tenha esse sinalizador é posicionado em um controlador de menu, o comando não aparecer na lista suspensa.

    Válido para:Button

Para obter mais informações sobre sinalizadores de comando, consulte a Elemento de sinalizador de comando documentação.

Requisitos gerais

O comando deve passar a série de testes a seguir antes de serem exibido e ativado:

  • O comando está posicionado corretamente.

  • O DefaultInvisible sinalizador não está definido.

  • O menu pai ou a barra de ferramentas está visível.

  • O comando não é invisível devido uma entrada de contexto a Elemento de VisibilityConstraints seção.

  • Código de VSPackage que implementa o IOleCommandTarget interface exibe e permite que o seu comando. Nenhum código de interface interceptou e agir sobre ele.

  • Quando um usuário clica em seu comando, ele fica sujeito ao procedimento descrito no Algoritmo de roteamento de comando.

Comandos de chamada predefinidos

O Elemento de UsedCommands permite que os VSPackages para acessar comandos que são fornecidos por outros VSPackages ou pelo IDE. Para fazer isso, crie um Elemento de UsedCommand que tem o GUID e a identificação do comando para usar. Isso garante que o comando será carregado por Visual Studio, mesmo que ele não é parte da configuração atual do Visual Studio. Para obter mais informações, consulte Elemento de UsedCommand.

Aparência do elemento de interface

Considerações sobre a seleção e o posicionamento de elementos de comando é:

  • Visual Studiooferece muitos elementos de interface do usuário que aparecem de forma diferente dependendo do posicionamento.

  • Um elemento de interface do usuário é definido usando o DefaultInvisible sinalizador não serão exibidos no IDE, exceto se for uma exibida por sua implementação VSPackage da QueryStatus método, ou associado a um determinado contexto de interface do usuário na VisibilityConstraints seção.

  • Até mesmo um comando com êxito posicionado pode não ser exibido. Isso é porque o IDE automaticamente oculta ou exibe alguns comandos, dependendo das interfaces que o VSPackage tem (ou não) implementado. Por exemplo, a implementação do VSPackage de alguns crie interfaces causas itens de menu relacionado à compilação a ser mostrado automaticamente.

  • Aplicando o CommandWellOnly sinalizador na definição do elemento de interface do usuário significa que o comando pode ser adicionado apenas pela personalização.

  • Comandos podem estar disponíveis somente em determinados contextos de interface do usuário, por exemplo, somente quando uma caixa de diálogo é exibida quando o IDE no modo design.

  • Para fazer com que certos elementos de interface do usuário a ser exibido no IDE, você deve implementar uma ou mais interfaces ou escrever algum código.

Consulte também

Conceitos

Making Commands Available

Outros recursos

Tarefas comuns com comandos, Menus e barras de ferramentas

Command Table Configuration (.ctc) Files

Command Table Format Reference

Command Routing in VSPackages