XML de la cinta de opciones

El elemento Cinta de opciones (XML) permite personalizar una cinta mediante XML. Use el elemento Ribbon (XML) si desea personalizar la cinta de opciones de una manera que no sea compatible con el elemento Ribbon (Visual Designer). Para obtener una comparación de lo que puede hacer con cada elemento, consulte Información general de la cinta de opciones.

Se aplica a: La información de este tema se aplica a proyectos de nivel de documento y proyectos de complementos de VSTO para las siguientes aplicaciones: Excel; InfoPath 2013 e InfoPath 2010; Outlook; PowerPoint; Project; Visio; Word. Para obtener más información, vea Características disponibles por aplicación de Office y tipo de proyecto.

Agregar un elemento de cinta de opciones (XML) a un proyecto

Puede agregar un elemento de cinta de opciones (XML) a cualquier proyecto de Office desde el cuadro de diálogo Agregar nuevo elemento . Visual Studio agrega automáticamente los siguientes archivos al proyecto:

• Un archivo XML de la cinta de opciones. Este archivo define la interfaz de usuario (UI) de la cinta de opciones. Use este archivo para agregar elementos de la interfaz de usuario, como pestañas, grupos y controles. Para obtener más información, consulte Referencia del archivo XML de Ribbon más adelante en este tema.

• Un archivo de código de la cinta de opciones. Este archivo contiene la clase Ribbon. Esta clase tiene el nombre que especificó para el elemento ribbon (XML) en el cuadro de diálogo Agregar nuevo elemento . Las aplicaciones de Microsoft Office usan una instancia de esta clase para cargar la cinta de opciones personalizada. Para obtener más información, consulte Referencia de clase Ribbon más adelante en este tema.

  De forma predeterminada, estos archivos agregan un grupo personalizado a la pestaña Complementos de la cinta de opciones.

Mostrar la cinta de opciones personalizada en una aplicación de Microsoft Office

Después de agregar un elemento de cinta de opciones (XML) al proyecto, debe agregar código a la clase ThisAddin, ThisWorkbook o ThisDocument que invalida el CreateRibbonExtensibilityObject método y devuelve la clase XML ribbon a la aplicación de Office.

En el ejemplo de código siguiente se invalida el CreateRibbonExtensibilityObject método y se devuelve una clase XML de cinta denominada MyRibbon.

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

Protected Overrides Function CreateRibbonExtensibilityObject() As  _
Microsoft.Office.Core.IRibbonExtensibility
    Return New MyRibbon()
End Function

Definir el comportamiento de la cinta de opciones personalizada

Puede responder a acciones de usuario, como hacer clic en un botón de la cinta de opciones, creando métodos de devolución de llamada. Los métodos de devolución de llamada se asemejan a los eventos de los controles de Windows Forms, pero se identifican mediante un atributo en el XML del elemento de interfaz de usuario. Los métodos se escriben en la clase Ribbon y un control llama al método que tiene el mismo nombre que el valor del atributo. Por ejemplo, puede crear un método callback que se ejecuta cuando un usuario hace clic en un botón de la cinta. Se requieren dos pasos para crear un método de devolución de llamada:

• Asigne un atributo a un control en el archivo XML de la cinta de opciones que identifica un método callback en su código.

• Defina el método callback en la clase Ribbon.

Para ver un tutorial que muestra cómo automatizar una aplicación desde la cinta de opciones, consulte Tutorial: Creación de una pestaña personalizada mediante XML de la cinta de opciones.

Asignar métodos de devolución de llamada a controles

Para asignar un método de devolución de llamada a un control en el archivo XML de la cinta de opciones, agregue un atributo que especifique el tipo del método de devolución de llamada y el nombre del método. Por ejemplo, el siguiente elemento define un botón de alternancia que tiene un método de devolución de llamada onAction denominado OnToggleButton1.

<toggleButton id="toggleButton1" onAction="OnToggleButton1" />

Se llama a onAction cuando el usuario realiza la tarea principal asociada a un control determinado. Por ejemplo, se llama al método de devolución de llamada onAction de un botón de alternancia cuando el usuario hace clic en el botón.

El método que especifique en el atributo puede tener cualquier nombre. Sin embargo, debe coincidir con el nombre del método que defina en el archivo de código de la cinta de opciones.

Hay muchos tipos diferentes de métodos de devolución de llamada que puede asignar a los controles de la cinta de opciones. Para obtener una lista completa de los métodos de callback disponibles para cada control, consulte el artículo técnico Personalizar la interfaz de usuario del Ribbon de Office (2007) para desarrolladores (parte 3 de 3).

Definición de métodos de devolución de llamada

Defina sus métodos de devolución de llamada en la clase Ribbon en el archivo de código Ribbon. Un método de devolución de llamada tiene varios requisitos:

• Debe declararse como público.

• Su nombre debe coincidir con el nombre de un método de devolución de llamada que ha asignado a un control en el archivo XML del Ribbon.

• Su firma debe coincidir con la firma de un tipo de método de devolución de llamada que esté disponible para el control de Ribbon asociado.

  Para obtener una lista completa de las firmas de método de devolución de llamada para los controles de la cinta de opciones, consulte el artículo técnico Personalizar la interfaz de usuario de la cinta de opciones de Office (2007) para desarrolladores (parte 3 de 3). Visual Studio no proporciona compatibilidad con IntelliSense para los métodos callback que creas en el archivo de código del Ribbon. Si crea un método de devolución de llamada que no coincide con una firma válida, el código se compilará, pero no se producirá nada cuando el usuario haga clic en el control.

  Todos los métodos de callback tienen un parámetro IRibbonControl que representa el control que llamó al método. Puede usar este parámetro para reutilizar el mismo método de devolución de llamada para varios controles. En el ejemplo de código siguiente se muestra un método de devolución de llamada onAction que realiza diferentes tareas en función del control en el que el usuario haga clic.

  • C#
  • VB

  public void OnActionCallback(Office.IRibbonControl control, bool isPressed)
  {
      if (control.Id == "checkBox1")
      {
          MessageBox.Show("You clicked " + control.Id);
      }
      else
      {
          MessageBox.Show("You clicked a different control.");
      }
  }
  

Referencia de archivo XML de Ribbon

Puede definir su cinta personalizada agregando elementos y atributos al archivo XML del Ribbon. De forma predeterminada, el archivo XML de la cinta de opciones contiene el siguiente XML.

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">
  <ribbon>
    <tabs>
      <tab idMso="TabAddIns">
        <group id="MyGroup"
               label="My Group">
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

En la tabla siguiente se describen los elementos predeterminados del archivo XML de la cinta de opciones.

Estos elementos tienen atributos que especifican la apariencia y el comportamiento de la cinta personalizada. En la tabla siguiente se describen los atributos predeterminados del archivo XML de la cinta de opciones.

Los elementos y atributos predeterminados del archivo XML de la cinta de opciones son un pequeño subconjunto de los elementos y atributos que están disponibles. Para obtener una lista completa de los elementos y atributos disponibles, consulte el artículo técnico Personalizar la interfaz de usuario de la cinta de opciones de Office (2007) para desarrolladores (parte 2 de 3).

Referencia de la clase Ribbon

Visual Studio genera la clase Ribbon en el archivo de código Ribbon. Agregue a esta clase los métodos de devolución de llamada para los controles de la cinta de opciones. Esta clase implementa la interfaz IRibbonExtensibility.

En la tabla siguiente se describen los métodos predeterminados de esta clase.

Contenido relacionado

• Descripción general de la cinta de opciones
• Guía paso a paso: Crear una pestaña personalizada utilizando Ribbon XML
• Personalización de la interfaz de usuario de Office