Cómo VSPackages agrega elementos de la interfaz de usuario al IDE

Un Paquete puede agregar los elementos (UI) de la interfaz de usuario, por ejemplo, menús, barras de herramientas, y ventanas de herramientas, el entorno de desarrollo integrado de Visual (IDE) Studio.

principios arquitectónicos

Se llama al conjunto de reglas y estructuras que permiten a un VSPackage para personalizar la interfaz de usuario la arquitectura de la tabla de comandos. La arquitectura de la tabla de comando se basa en los principios de diseño siguientes:

• La interfaz de usuario no debe ser forma desordenada o confusa.

• La interfaz de usuario deben ser dinámica, no estática.

• La interfaz de usuario deben ser personalizable.

• La interfaz de usuario deben ser útil.

La interfaz de usuario No Debe es Cluttered o Confusing

• Varios VSPackages se puede instalar en la sesión de Visual Studio que hospeda el paquete VSPackage. Cuando el paquete VSPackage agrega comandos, no debe interrumpir VSPackages previamente instalado, sino que también debe colocar sus características a disposición del otro VSPackages y permitirles contribuir características a cambios.

• Cada menú, si se tiene acceso mediante la barra de menú principal, un submenú, o un menú contextual, puede contener elementos de menú que son contribuidos por otro VSPackages. Por consiguiente, tenga cuidado de no atestar de la interfaz de usuario. Si muestran demasiados comandos al mismo tiempo, la interfaz de usuario puede confundir a los usuarios.

La interfaz de usuario deben ser dinámica, no estática

• Los comandos pueden mostrar u ocultar en cualquier momento, dependiendo del estado de los datos subyacentes y la actividad del usuario actual.

• Un Paquete se debe habilitar para cambiar la etiqueta de un elemento de la interfaz de usuario, y también el contenido de los cuadros combinados o menús.

• Los elementos de la interfaz de usuario pueden tener que agregar o quitar cuando se utiliza el Paquete.

• Los elementos de la interfaz de usuario pueden requerir llamadas adicionales a VSPackage rellenar sus valores o detectar su estado actual. Ejemplos de estas listas de inclusión de los elementos de archivos, cuadros combinados, y de selectores más-reciente-utilizados (MRU) para color o textura.

• Puede mejorar la experiencia del usuario para agregar el comando a los menús en otro VSPackages. Por ejemplo, si el comando que se proporciona se parece a Copiar, puede colocar el comando en cada paquete VSPackage donde aparece Copiar .

La interfaz de usuario deben ser personalizable

• En cualquier momento, un usuario puede personalizar los elementos de la interfaz de usuario en el paquete VSPackage, por ejemplo, si agrega un botón a una ventana de herramientas o reorganizando un menú. Sin embargo, en algunos casos, puede que desee deshabilitar la personalización.

• Algunos comandos están disponibles solo mediante personalización; es decir, un comando podría no estar disponible en un menú o una barra de herramientas hasta que el usuario agregue mediante el cuadro de diálogo Personalizar .

• En cualquier momento, un usuario puede personalizar los métodos abreviados de teclado para los comandos, así como los métodos abreviados de teclado de comandos que vengan de Visual Studio y otros VSPackages.

• Los comandos pueden ejecutarse utilizando la ventana del comando. Por consiguiente, el IDE tiene que saber que el comando corresponde a una etiqueta determinada del comando. El IDE consigue mediante un proceso conocido como canonización, donde los espacios se quitan para comprimir un nombre de comando en una palabra única. Por ejemplo, la canonización “Abrir &File” es “FileOpen”.

La interfaz de usuario deben ser útil

• La mayoría de los elementos de la interfaz de usuario deben tener información sobre herramientas.

• Para mejorar el rendimiento, el Paquete debe cargar sólo cuando una de sus funciones se invoca. Esto se conoce como “carga retrasada.”

• Las adiciones al IDE solicita un VSPackage deben estar localizables.

• Puede utilizar los mapas de bits incluidas en Visual Studio o puede proporcionar dispone.

La arquitectura de la tabla de comandos de Visual Studio

Como se ha mencionado anteriormente, la arquitectura de la tabla de comandos admite los principios arquitectónicos anteriores. Los principios básicos de abstracciones, las estructuras de datos, y las herramientas de la arquitectura de la tabla de comandos son las siguientes:

• hay tres clases básicas 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 los procedimientos que el usuario puede ejecutar en el IDE, y pueden ser expuestos como elementos de menú, botones, cuadros de lista, u otro control. Los grupos son contenedores de los menús y comandos.

• Cada elemento es especificado por una definición que describe el elemento, la prioridad relativa a otros elementos, y marcadores que modifican su comportamiento.

• Cada elemento tiene una posición que describe el elemento primario del elemento. Un elemento puede tener elementos primarios múltiples, de modo que pueda aparecer en varias ubicaciones de la interfaz de usuario.

  Cada comando debe tener un grupo como su elemento primario, aunque es el único en ese grupo. Cada menú estándar también debe tener un grupo primario. Las barras de herramientas y las ventanas de herramientas actuar como sus propios elementos primarios. un grupo puede tener como su elemento primario la barra de menús principal de Visual Studio, o cualquier menú, barra de herramientas, o ventana de herramientas.

Cómo los elementos se definen

. Los archivos de Vsct se da formato en XML. Un archivo de .vsct define los elementos de la interfaz de usuario para un paquete y determina dónde esos elementos aparecen en el IDE. Asignan cada menú, grupo, o comando en el paquete primero un GUID y un identificador en la sección de Symbols . En el resto del archivo de .vsct, cada menú, comando, y grupo identifica la combinación de GUID y ID. El ejemplo siguiente muestra una sección típica de Symbols que se genera en la plantilla de paquete de Visual Studio cuando Comando de menú está seleccionado 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 sección de Symbols es GuidSymbol (Elemento). nombres de mapa de elementos deGuidSymbol a GUID utilizados por el IDE para identificar los paquetes y sus elementos.

El primer elemento de GuidSymbol , paquete “de guid [PackageName]”, es el GUID del paquete en sí. El es un GUID que usa Visual Studio para cargar el paquete. Normalmente, no tiene elementos secundarios.

De convención, agrupar los menús y comandos en un elemento de GuidSymbol de segundo, “guid [PackageName] CmdSet”, y los mapas de bits están sujetos a un elemento de GuidSymbol de otros fabricantes, “guidImages”. No tiene que seguir esta convención, pero cada menú, grupo, comando, y mapa de bits deben ser un elemento secundario de un elemento de GuidSymbol .

En el segundo elemento de GuidSymbol , que representa el conjunto de comandos del paquete, hay varios elementos de IDSymbol . Cada IDSymbol (Elemento) asigna un nombre a un valor numérico, y puede representar un menú, un grupo, o un comando que forma parte del comando. los elementos de IDSymbol en el tercer elemento de GuidSymbol representan los mapas de bits que se pueden utilizar como iconos para los comandos. Dado que los pares de GUID/ID deben ser únicos en una aplicación, no hay dos elementos secundarios del mismo elemento de GuidSymbol pueden 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 la interfaz de usuario debe tener los siguientes aspectos:

• Un atributo de guid que coincida con el nombre del elemento de GuidSymbol que el elemento de la interfaz de usuario se define en.

• Un atributo de id que coincida con el nombre del elemento asociado de IDSymbol .

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

• Un atributo de priority que determina la posición del elemento de la interfaz de usuario del menú principal o grupo.

• Parent (Elemento) que tiene guid y atributos de id que especifican la firma del menú o grupo primario.

Menús

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

• Un atributo de type que especifica si el menú debe aparecer en el IDE como clase de menú o una barra de herramientas.

• Strings (Elemento) que contiene ButtonText (Elemento), que especifica el título del menú del IDE, y CommandName (Elemento), que especifica el nombre que se utiliza en la ventana de comandos para tener acceso al menú.

• Marcas opcionales. CommandFlag (Elemento) puede aparecer en una definición de menú para cambiar su apariencia y comportamiento del IDE.

Cada elemento de Menu debe tener un grupo como su 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 valores para el atributo de type , vea la documentación de Menu (Elemento) .

El ejemplo siguiente se muestra un menú que aparece en la barra de menús de Visual Studio, junto al menú de 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>

Groups

Un grupo es un elemento que se define en la sección de Groups del archivo de .vsct. Los grupos simplemente son contenedores. No aparecen en el IDE excepto como línea de división de un menú. Por consiguiente, Group (Elemento) se define sólo por su firma, prioridad, y elemento primario.

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

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

Dado que forma parte de un menú, este grupo contendría normalmente comandos. Sin embargo, también podría contener otros menús. Así es cómo los submenús son definido, 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 Button (Elemento) o Combo (Elemento). Aparezca en un menú o una barra de herramientas, el comando debe tener un grupo como su elemento primario.

Botones

Los botones se definen en la sección de Buttons . El cualquier elemento de menú, el botón, u otro elemento que un usuario haga clic en para ejecutar un comando único se considera un botón. Algunos tipos de botón también pueden incluir funcionalidad de la lista. Los botones tienen los atributos necesarios y opcionales igual que los menús tienen, y también pueden tener Elemento Icon que especifica 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, vea la documentación de Buttons (Elemento) .

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

combinaciones

Las combinaciones se definen en la sección de Combos . Cada elemento de Combo representa un cuadro de lista desplegable en el IDE. El cuadro de lista puede o no puede ser programable por los usuarios, según el valor del atributo de type de combinación. Las combinaciones tienen los mismos elementos y comportamiento que los botones tienen, y también pueden tener atributos adicionales siguientes:

• Un atributo de defaultWidth que especifica el ancho en píxeles.

• Un atributo de idCommandList que especifica una lista que contiene los elementos que se muestran en el cuadro de lista. la lista de comando se debe declarar en el mismo nodo de GuidSymbol que contiene la combinación.

el ejemplo siguiente 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 muestran junto con un icono deben incluir un elemento de Icon que hace referencia a un mapa de bits utilizando su GUID e identificador Cada mapa de bits se define como Bitmap (Elemento) en la sección de Bitmaps . Los únicos atributos requeridos para una definición de Bitmap son guid y href, que señala al archivo de código fuente. Si el archivo de código fuente es una franja de recursos, un atributo de usedList también se requiere, enumerar las imágenes disponible en la curva spline. Para obtener más información, consulte la documentación de Bitmap (Elemento).

Relación jerárquica

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

Menú, comando, y posición de grupo

Un menú, un grupo, o un comando pueden aparecer en más de una ubicación en el IDE. Para que un elemento aparece en varias ubicaciones, debe agregar a la sección de CommandPlacements como CommandPlacement (Elemento). Cualquier menú, grupo, o comando se pueden agregar como posición del comando. Sin embargo, las barras de herramientas no pueden incluirse de esta manera porque no pueden aparecer en ubicaciones contextuales.

Las posiciones de comando tienen guid, id, y atributos de priority . El GUID y el identificador deben coincidir con los del elemento se coloca que. El atributo de priority controla la posición del elemento con respecto a otros elementos. Si el IDE combina dos o más elementos que tienen la misma prioridad, sus posiciones son indefinidas porque el IDE no garantiza que leen los recursos del paquete en el mismo orden cada vez que el paquete está compilado.

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

comando Visibility y contexto

Cuando VSPackages múltiple está instalado, una profusión de menús, elementos de menú, y barras de herramientas puede llenar el IDE. Para evitar este problema, puede controlar la visibilidad de los elementos individuales de la interfaz de usuario utilizando los marcadores de restricciones y el comando de visibilidad .

Restricciones de visibilidad

Una restricción de visibilidad se establece como VisibilityItem (elemento) en la sección de VisibilityConstraints . Una restricción de visibilidad define los contextos concretos de la interfaz de usuario en los que el elemento de destino está visible. Un menú o un comando que se incluyen en esta sección solo es visible cuando uno de los contextos definido está activa. Si no hacen referencia a un menú o un comando en esta sección, siempre es visible de forma predeterminada. Esta sección no se aplica a los grupos.

los elementos deVisibilityItem deben tener tres atributos, como sigue: guid y id de elementos de la interfaz de usuario de destino, y context. El atributo de context especifica cuando el elemento de destino estará visible, y toma cualquier contexto válido de la interfaz de usuario como su valor. Las constantes de contexto de la interfaz de usuario de Visual Studio son miembros de la clase de VSConstants . Cada elemento de VisibilityItem sólo puede tomar un valor de contexto. Para aplicar un segundo contexto, cree un elemento de VisibilityItem del segundo que señala 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 comando

Los siguientes indicadores de comando pueden afectar a la visibilidad de los menús y los comandos que se aplican a.

• AlwaysCreate
  Se crea el menú aunque no tiene grupos ni botón.

  válido para: Menu

• CommandWellOnly
  Aplica este marcador si el comando no aparece en el menú de nivel superior y desea que quede disponible para la personalización adicional de shell, por ejemplo, enlazándolo a una clave. Después de que el Paquete está instalado, un usuario puede personalizar estos comandos abriendo el cuadro de diálogo de Opciones y después de la posición del comando bajo la categoría de Entorno de teclado . No afecta a la posición en menús contextuales, barras de herramientas, controladores de menú, o submenús.

  válido para: Button, Combo

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

  válido para: Button, Combo

• DefaultInvisible
  De forma predeterminada, el comando no es visible si el Paquete que implementa el comando no se carga o el método QueryStatus no se ha llamado.

  Se debe combinar con DynamicVisibility el marcador.

  válido para: Button, Combo, Menu

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

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

  En un menú, este marcador también indica que debe automáticamente ocultar a ocultar sus miembros. Este marcador se suele asignar a los submenús porque los menús de nivel superior ya tienen este comportamiento.

  Se debe combinar con DefaultInvisible el marcador.

  válido para: Button, Combo, Menu

• NoShowOnMenuController
  Si colocan un comando que tiene este marcador 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 comando, vea la documentación de CommandFlag (Elemento) .

requisitos generales

El comando debe pasar la serie siguiente de pruebas antes de poder mostrar y habilitarse:

• Colocan el comando correctamente.

• El indicador de DefaultInvisible no está establecida.

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

• El comando no es invisible debido a una entrada de contexto en la sección de VisibilityConstraints (Elemento) .

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

• Cuando un usuario hace clic en el comando, se convierte en el procedimiento que se describe en Algoritmo de enrutamiento de comandos.

Llamar a comandos predefinidos

UsedCommands (Elemento) permite a VSPackages para tener acceso a los comandos proporcionados por el otro VSPackages o por el IDE. Para hacer el, cree UsedCommand (Elemento) con el GUID y el identificador de comando de utilizar. Esto garantiza que el comando esté cargado por Visual Studio, aunque no forma parte de la configuración actual de Visual Studio. Para obtener más información, vea UsedCommand (Elemento).

Apariencia del elemento de la interfaz

Consideraciones para los elementos de la selección y el comando de posición son como sigue:

• Visual Studio proporciona muchos elementos de la interfaz de usuario que aparezca distinto en función de la posición.

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

• Incluso un comando correctamente colocado no puede mostrar. Esto es porque oculta del IDE automáticamente o muestra algunos comandos, dependiendo de las interfaces que el paquete VSPackage (o no tiene) ha implementado. Por ejemplo, la implementación de un Paquete de algunas interfaces de compilación produce los elementos de menú generación-relacionados automáticamente que se mostrarán.

• Al aplicar el indicador de CommandWellOnly en la definición del elemento de la interfaz de usuario significa que el comando se puede agregar únicamente la personalización.

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

• Para provocar ciertos elementos de la interfaz de usuario que se mostrarán en el IDE, debe implementar una o más interfaces o escribir código.

Vea también

Conceptos

Making Commands Available

Otros recursos

Tareas comunes con los comandos, menús, barras de herramientas y

Command Table Configuration (.ctc) Files

Command Table Format Reference

Command Routing in VSPackages