Cómo VSPackages agrega elementos de la interfaz de usuario

Un VSPackage puede agregar elementos de interfaz de usuario (UI), por ejemplo, menús, barras de herramientas y ventanas de herramientas, a Visual Studio mediante el archivo .vsct .

Puede encontrar instrucciones de diseño para los elementos de la interfaz de usuario en Las directrices de experiencia del usuario de Visual Studio.

Arquitectura de la tabla de comandos de Visual Studio

Como se indicó, la arquitectura de la tabla de comandos admite los principios arquitectónicos anteriores. Los principios subyacentes a las abstracciones, estructuras de datos y herramientas de la arquitectura de la tabla de comandos son los siguientes:

• Hay tres tipos básicos de elementos: menús, comandos y grupos. Los menús se pueden exponer en la interfaz de usuario como menús, submenús, barras de herramientas o ventanas de herramientas. Los comandos son procedimientos que el usuario puede ejecutar en el IDE y se pueden exponer como elementos de menú, botones, cuadros de lista u otros controles. Los grupos son contenedores para los menús y comandos.

• Cada elemento se especifica mediante una definición que describe el elemento, su prioridad relativa a otros elementos y las marcas que modifican su comportamiento.

• Cada elemento tiene una ubicación que describe el elemento primario del elemento. Un elemento puede tener varios elementos primarios para que pueda aparecer en varias ubicaciones de la interfaz de usuario.

Cada comando debe tener un grupo como elemento primario, incluso si es el único elemento secundario de ese grupo. Todos los menús estándar también deben tener un grupo primario. Las barras de herramientas y las ventanas de herramientas actúan como sus propios padres. Un grupo puede tener como elemento primario la barra de menús principal de Visual Studio o cualquier menú, barra de herramientas o ventana de herramientas.

Cómo se definen los elementos

Un archivo .vsct tiene el formato XML. Define los elementos de la interfaz de usuario de un paquete y determina dónde aparecen esos elementos en el IDE. En primer lugar, a cada menú, grupo o comando del paquete se le asigna un GUID y un identificador en la Symbols sección. A lo largo del resto del archivo .vsct , cada menú, comando y grupo se identifica mediante su combinación guid e id. En el ejemplo siguiente se muestra una sección típica Symbols generada por la plantilla de paquete de Visual Studio cuando se selecciona un comando de menú en la plantilla.

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

El elemento de nivel superior de la Symbols sección es el elemento GuidSymbol. GuidSymbol los elementos asignan nombres a GUID que usa el IDE para identificar paquetes y sus partes de componente.

Nota:

La plantilla de paquete de Visual Studio genera automáticamente los GUID. También puede crear un GUID único haciendo clic en Crear GUID en el menú Herramientas .

El primer GuidSymbol elemento, guid<PackageName>Pkg, es el GUID del propio paquete. Este es el GUID que usa Visual Studio para cargar el paquete. Normalmente, no tiene elementos secundarios.

Por convención, los menús y comandos se agrupan en un segundo GuidSymbol elemento, guid<PackageName>CmdSet, y los mapas de bits se encuentran en un tercer GuidSymbol elemento, guidImages. No es necesario seguir esta convención, pero cada menú, grupo, comando y mapa de bits debe ser un elemento secundario de un GuidSymbol elemento.

En el segundo GuidSymbol elemento, que representa el conjunto de comandos del paquete, son varios IDSymbol elementos. Cada elemento IDSymbol asigna un nombre a un valor numérico y puede representar un menú, grupo o comando que forma parte del conjunto de comandos. Los IDSymbol elementos del tercer GuidSymbol elemento representan mapas de bits que se pueden usar como iconos para los comandos. Dado que los pares GUID/ID deben ser únicos en una aplicación, ningún elemento secundario del mismo GuidSymbol elemento puede tener el mismo valor.

Menús, grupos y comandos

Cuando un menú, un grupo o un comando tiene un GUID y un identificador, se puede agregar al IDE. Cada elemento de interfaz de usuario debe tener lo siguiente:

• Atributo guid que coincide con el nombre del elemento en el GuidSymbol que se define el elemento de interfaz de usuario.

• Atributo id que coincide con el nombre del elemento asociado IDSymbol .

Juntos, los guid atributos y id componen la firma del elemento de interfaz de usuario.

• Atributo priority que determina la ubicación del elemento de la interfaz de usuario en su menú o grupo primarios.

• Elemento Primario que tiene guid atributos y id que especifican la firma del menú o grupo primarios.

Menús

Cada menú se define como un elemento Menu en la Menus sección . Los menús deben tener guidatributos , idy , y priority un Parent elemento , y también los siguientes atributos y elementos secundarios adicionales:

• Atributo type que especifica si el menú debe aparecer en el IDE como un tipo de menú o como una barra de herramientas.

• Elemento Strings que contiene un elemento ButtonText, que especifica el título del menú en el IDE y un elemento CommandName, que especifica el nombre que se usa en la ventana Comandos para tener acceso al menú.

• Marcas opcionales. Un elemento CommandFlag puede aparecer en una definición de menú para cambiar su apariencia o comportamiento en el IDE.

Cada Menu elemento debe tener un grupo como elemento primario, a menos que sea un elemento acoplable como una barra de herramientas. Un menú acoplable es su propio elemento primario. Para obtener más información sobre los menús y los valores del type atributo, consulte la documentación del elemento Menu.

En el ejemplo siguiente se muestra un menú que aparece en la barra de menús de Visual Studio, junto al menú Herramientas .

<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

Un grupo es un elemento que se define en la Groups sección del archivo .vsct . Los grupos son solo contenedores. No aparecen en el IDE, excepto como una línea divisoria en un menú. Por lo tanto, un elemento Group solo se define mediante su firma, prioridad y elemento primario.

Un grupo puede tener un menú, otro grupo o sí mismo como primario. Sin embargo, el elemento primario suele ser un menú o una barra de herramientas. El menú del ejemplo anterior es un elemento secundario del IDG_VS_MM_TOOLSADDINS grupo y ese grupo es un elemento secundario de la barra de menús de Visual Studio. El grupo del ejemplo siguiente es un elemento secundario del menú del ejemplo anterior.

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

Dado que forma parte de un menú, este grupo normalmente contendrá comandos. Sin embargo, también podría contener otros menús. Así es como se definen los submenús, como se muestra en el ejemplo siguiente.

<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

Un comando que se proporciona al IDE se define como un elemento Button o un elemento Combo. Para que aparezca en un menú o una barra de herramientas, el comando debe tener un grupo como elemento primario.

Botones

Los botones se definen en la Buttons sección . Cualquier elemento de menú, botón u otro elemento en el que un usuario haga clic para ejecutar un único comando se considera un botón. Algunos tipos de botón también pueden incluir funcionalidad de lista. Los botones tienen los mismos atributos obligatorios y opcionales que tienen los menús, y también pueden tener un elemento Icon que especifique el GUID y el identificador del mapa de bits que representa el botón en el IDE. Para obtener más información sobre los botones y sus atributos, consulte la documentación del elemento Buttons.

El botón del ejemplo siguiente es un elemento secundario del grupo en el ejemplo anterior y aparecería en el IDE como un elemento de menú en el menú primario de ese 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

Los combos se definen en la Combos sección . Cada Combo elemento representa un cuadro de lista desplegable en el IDE. Los usuarios pueden escribir o no el cuadro de lista, dependiendo del valor del type atributo del combo. Los combos tienen los mismos elementos y comportamientos que tienen los botones y también pueden tener los siguientes atributos adicionales:

• Atributo defaultWidth que especifica el ancho de píxel.

• Atributo idCommandList que especifica una lista que contiene los elementos que se muestran en el cuadro de lista. La lista de comandos debe declararse en el mismo GuidSymbol nodo que contiene el combo.

En el ejemplo siguiente se define un elemento combinado.

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

Mapas de bits

Los comandos que se mostrarán junto con un icono deben incluir un Icon elemento que haga referencia a un mapa de bits mediante su GUID e identificador. Cada mapa de bits se define como un elemento Bitmap en la Bitmaps sección . Los únicos atributos necesarios para una Bitmap definición son guid y href, que apunta al archivo de origen. Si el archivo de origen es una franja de recursos, también se requiere un atributo usedList para enumerar las imágenes disponibles en la franja. Para obtener más información, consulte la documentación del elemento Bitmap.

Relación jerárquica

Las reglas siguientes rigen cómo un elemento puede llamar a otro elemento como elemento primario.

Elemento	Definido en esta sección de la tabla de comandos	Se puede contener (como elemento primario o colocación en la CommandPlacements sección, o ambos)	Puede contener (lo que se conoce como elemento primario)
Group (Grupo)	Elemento Groups, el IDE, otros VSPackages	Un menú, un grupo, el propio elemento	Menús, grupos y comandos
Menu	Elemento Menus, el IDE, otros VSPackages	1 a n grupos	De 0 a n grupos
Barra de herramientas	Elemento Menus, el IDE, otros VSPackages	El propio elemento	De 0 a n grupos
Elemento de menú	Elemento Buttons, el IDE, otros VSPackages	De 1 a n grupos, el propio elemento	-0 a n grupos
Button	Elemento Buttons, el IDE, otros VSPackages	De 1 a n grupos, el propio elemento
Combinado	Elemento Combos, el IDE, otros VSPackages	De 1 a n grupos, el propio elemento

Selección de ubicación de menús, comandos y grupos

Un menú, grupo o comando puede aparecer en más de una ubicación del IDE. Para que un elemento aparezca en varias ubicaciones, debe agregarse a la CommandPlacements sección como un elemento CommandPlacement. Cualquier menú, grupo o comando se puede agregar como ubicación de comandos. Sin embargo, las barras de herramientas no se pueden colocar de esta manera porque no pueden aparecer en varias ubicaciones contextuales.

Las ubicaciones de comandos tienen guidatributos , idy priority . El GUID y el identificador deben coincidir con los del elemento que está colocado. El priority atributo rige la colocación del elemento con respecto a otros elementos. Cuando el IDE combina dos o más elementos que tienen la misma prioridad, sus ubicaciones no están definidas porque el IDE no garantiza que los recursos del paquete se lean en el mismo orden cada vez que se compila el paquete.

Si un menú o grupo aparece en varias ubicaciones, todos los elementos secundarios de ese menú o grupo aparecerán en cada instancia.

Visibilidad y contexto de comandos

Cuando se instalan varios VSPackages, una profusión de menús, elementos de menú y barras de herramientas puede desordenar el IDE. Para evitar este problema, puede controlar la visibilidad de los elementos individuales de la interfaz de usuario mediante restricciones de visibilidad y marcas de comandos.

Restricciones de visibilidad

Una restricción de visibilidad se establece como un elemento VisibilityItem en la VisibilityConstraints sección . Una restricción de visibilidad define contextos de interfaz de usuario específicos en los que el elemento de destino está visible. Un menú o comando que se incluye en esta sección solo es visible cuando uno de los contextos definidos está activo. Si no se hace referencia a un menú o comando en esta sección, siempre es visible de forma predeterminada. Esta sección no se aplica a los grupos.

VisibilityItem Los elementos deben tener tres atributos, como se indica a continuación: y guidid del elemento de interfaz de usuario de destino y context. El context atributo especifica cuándo estará visible el elemento de destino y toma cualquier contexto de interfaz de usuario válido como su valor. Las constantes de contexto de la interfaz de usuario para Visual Studio son miembros de la VSConstants clase . Cada VisibilityItem elemento solo puede tomar un valor de contexto. Para aplicar un segundo contexto, cree un segundo VisibilityItem elemento que apunte al mismo elemento, como se muestra en el ejemplo siguiente.

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

Marcas de comandos

Las marcas de comandos siguientes pueden afectar a la visibilidad de los menús y comandos a los que se aplican.

AlwaysCreate El menú se crea incluso si no tiene grupos ni botones.

Válido para: Menu

CommandWellOnly Aplique esta marca si el comando no aparece en el menú de nivel superior y desea que esté disponible para la personalización adicional del shell, por ejemplo, enlazarlo a una clave. Después de instalar VSPackage, un usuario puede personalizar estos comandos abriendo el cuadro de diálogo Opciones y editando la ubicación del comando en la categoría Entorno de teclado. No afecta a la colocación en menús contextuales, barras de herramientas, controladores de menús o submenús.

Válido para: Button, Combo

DefaultDisabled De forma predeterminada, el comando está deshabilitado si no se carga el vsPackage que implementa el comando o no se ha llamado al método QueryStatus.

Válido para: Button, Combo

DefaultInvisible De forma predeterminada, el comando es invisible si no se carga el vsPackage que implementa el comando o no se ha llamado al método QueryStatus.

Debe combinarse con la DynamicVisibility marca .

Válido para: Button, , ComboMenu

DynamicVisibility La visibilidad del comando se puede cambiar mediante el QueryStatus método o un GUID de contexto que se incluye en la VisibilityConstraints sección .

Se aplica a los comandos que aparecen en los menús, no en las barras de herramientas. Los elementos de la barra de herramientas de nivel superior se pueden deshabilitar, pero no ocultar, cuando se devuelve la OLECMDF_INVISIBLE marca del QueryStatus método .

En un menú, esta marca también indica que debe ocultarse automáticamente cuando sus miembros están ocultos. Esta marca normalmente se asigna a submenús porque los menús de nivel superior ya tienen este comportamiento.

Debe combinarse con la DefaultInvisible marca .

Válido para: Button, , ComboMenu

NoShowOnMenuController Si un comando que tiene esta marca se coloca en un controlador de menú, el comando no aparece en la lista desplegable.

Válido para: Button

Para obtener más información sobre las marcas de comandos, consulte la documentación del elemento CommandFlag.

Requisitos generales

El comando debe pasar la siguiente serie de pruebas antes de que se pueda mostrar y habilitar:

• El comando se coloca correctamente.

• La DefaultInvisible marca no está establecida.

• El menú primario o la barra de herramientas están visibles.

• El comando no es invisible debido a una entrada de contexto en la sección del elemento VisibilityConstraints.

• El código VSPackage que implementa la IOleCommandTarget interfaz muestra y habilita el comando. Ningún código de interfaz lo interceptó y actuó en él.

• Cuando un usuario hace clic en el comando, queda sujeto al procedimiento que se describe en Algoritmo de enrutamiento.

Llamar a comandos predefinidos

El elemento UsedCommands permite a VSPackages tener acceso a los comandos proporcionados por otros VSPackages o por el IDE. Para ello, cree un elemento UsedCommand que tenga el GUID y el identificador del comando que se va a usar. Esto garantiza que Visual Studio cargará el comando, incluso si no forma parte de la configuración actual de Visual Studio. Para obtener más información, vea Elemento UsedCommand.

Apariencia del elemento interface

Las consideraciones para seleccionar y colocar elementos de comando son las siguientes:

• Visual Studio ofrece muchos elementos de interfaz de usuario que aparecen de forma diferente en función de la ubicación.

• Un elemento de interfaz de usuario definido mediante la DefaultInvisible marca no se mostrará en el IDE a menos que se muestre mediante su implementación de VSPackage del QueryStatus método o asociado a un contexto de interfaz de usuario determinado en la VisibilityConstraints sección.

• Incluso es posible que no se muestre un comando colocado correctamente. Esto se debe a que el IDE oculta o muestra automáticamente algunos comandos, en función de las interfaces que el VSPackage tiene (o no) implementado. Por ejemplo, la implementación de VSPackage de algunas interfaces de compilación hace que los elementos de menú relacionados con la compilación se muestren automáticamente.

• Aplicar la CommandWellOnly marca en la definición del elemento de interfaz de usuario significa que el comando solo se puede agregar mediante la personalización.

• Los comandos solo pueden estar disponibles en determinados contextos de interfaz de usuario, por ejemplo, solo cuando se muestra un cuadro de diálogo cuando el IDE está en la vista de diseño.

• Para que determinados elementos de la interfaz de usuario se muestren en el IDE, debe implementar una o varias interfaces o escribir código.

Contenido relacionado

• Extender menús y comandos