XML de la cinta de opciones

Artículo
08/10/2011

El elemento Cinta (XML) permite personalizar una cinta de opciones utilizando XML. Utilice el elemento Cinta (XML) si desea personalizar la cinta de opciones de una forma no compatible con el elemento Cinta (diseñador visual). Para obtener una comparación de las tareas que puede realizar con cada elemento, vea Información general sobre la cinta de opciones.

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

Agregar un elemento Cinta (XML) a un proyecto

Puede agregar un elemento Cinta (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 cinta de opciones. Este archivo define la interfaz de usuario de la cinta de opciones. Utilice este archivo para agregar elementos de interfaz de usuario como fichas, grupos y controles. Para obtener información detallada, vea más adelante el apartado Referencia del archivo XML de cinta de opciones de este tema.
Un archivo de código de cinta de opciones. Este archivo contiene la clase Ribbon. Esta clase tiene el nombre que haya especificado para el elemento Cinta (XML) en el cuadro de diálogo Agregar nuevo elemento. Las aplicaciones de Microsoft Office utilizan una instancia de esta clase para cargar la cinta de opciones personalizada. Para obtener información detallada, vea más adelante el apartado Referencia de la clase Ribbon de este tema.

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

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

Después de agregar un elemento Cinta (XML) al proyecto, debe agregar código a la clase ThisAddin, ThisWorkbook o ThisDocument que invalide el método CreateRibbonExtensibilityObject y devuelva la clase Ribbon XML a la aplicación de Office.

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

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

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

Definir el comportamiento de la cinta de opciones personalizada

Para responder a acciones del usuario, como hacer clic en un botón de la cinta de opciones, cree métodos de devolución de llamada. Los métodos de devolución de llamada recuerdan a los eventos de los controles de formularios Windows Forms, pero se identifican con un atributo en el código XML del elemento de interfaz de usuario. Cuando escribe métodos en la clase Ribbon, un control llama al método que tiene el mismo nombre que el valor de atributo. Por ejemplo, puede crear un método de devolución de llamada al que se llama cuando un usuario hace clic en un botón en la cinta de opciones. Es necesario realizar dos pasos para crear un método de devolución de llamada:

Asigne a un control del archivo XML de cinta de opciones un atributo que identifique un método de devolución de llamada en el código.
Defina el método de devolución de llamada en la clase Ribbon.

Nota

Outlook requiere un paso adicional. Para obtener más información, vea Personalizar una cinta de opciones para Outlook.

Para realizar un tutorial que demuestra cómo automatizar una aplicación desde la cinta de opciones, vea Tutorial: Crear una pestaña personalizada usando 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 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 alternar 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 con un control determinado. Por ejemplo, se llama al método de devolución de llamada onAction de un botón de alternar 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 cinta de opciones.

Hay muchos tipos diferentes de métodos de devolución de llamada que puede asignar a los controles de cinta de opciones. Para obtener una lista completa de los métodos de devolución de llamada disponibles para cada control, vea el artículo técnico Customizing the Office (2007) Ribbon User Interface for Developers (Part 3 of 3).

Definir métodos de devolución de llamada

Defina los métodos de devolución de llamada en la clase Ribbon del archivo de código de la cinta de opciones. 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 asignado a un control en el archivo XML de cinta de opciones.
Su firma debe coincidir con la de un tipo de método de devolución de llamada que esté disponible para el control de cinta asociado.

Para obtener una lista completa de las firmas de los métodos de devolución de llamada de los controles Ribbon, vea el artículo técnico Customizing the Office (2007) Ribbon User Interface for Developers (Part 3 of 3). Visual Studio no proporciona compatibilidad con IntelliSense para los métodos de devolución de llamada que se crean en el archivo de código de la cinta de opciones. Si crea un método de devolución de llamada que no coincide con una firma válida, se compilará el código, pero no ocurrirá nada cuando el usuario haga clic en el control.

Todos los métodos de devolución de llamada tienen un parámetro Microsoft.Office.Core.IRibbonControl que representa el control que llamó al método. Puede utilizar este parámetro para reutilizar el mismo método de devolución de llamada en varios controles. El siguiente ejemplo de código muestra un método de devolución de llamada onAction que realiza diferentes tareas según el control en el que el usuario hace clic.

Public Sub OnActionCallback(ByVal control As Office.IRibbonControl, _
    ByVal isPressed As Boolean)

    If (control.Id = "checkBox1") Then
        MessageBox.Show("You clicked " + control.Id)
    Else
        MessageBox.Show("You clicked a different control.")
    End If

End Sub

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 del archivo XML de cinta de opciones

Para definir la cinta de opciones personalizada, agregue elementos y atributos al archivo XML de cinta de opciones. De forma predeterminada, el archivo XML de cinta de opciones contiene el siguiente código XML.

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="https://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 en el archivo XML de cinta de opciones.

Elemento	Descripción
customUI	Representa la cinta de opciones personalizada en el proyecto de complemento.
ribbon	Representa la cinta de opciones.
tabs	Representa un conjunto de fichas de cinta de opciones.
tab	Representa una sola ficha de cinta de opciones.
group	Representa un grupo de controles en la ficha Cinta.

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

Atributo	Elemento primario	Descripción
onLoad	customUI	Identifica un método al que se llama cuando la aplicación carga la cinta de opciones.
idMso	tab	Identifica una ficha integrada que se va a mostrar en la cinta de opciones.
id	group	Identifica el grupo.
label	group	Especifica el texto que aparece en el grupo.

Los elementos y atributos predeterminados del archivo XML de 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, vea el artículo técnico Customizing the Office (2007) Ribbon User Interface for Developers (Part 2 of 3).

Referencia de la clase Ribbon

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

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

Método	Descripción
GetCustomUI	Devuelve el contenido del archivo XML de cinta de opciones. Las aplicaciones de Microsoft Office llaman a este método para obtener una cadena XML que define la interfaz de usuario de la cinta personalizada. Este método implementa el método IRibbonExtensibility.GetCustomUI(String). Nota GetCustomUI sólo debe implementarse para devolver el contenido del archivo XML de cinta de opciones; no se debe utilizar para inicializar el complemento.En particular, no debería intentar mostrar cuadros de diálogo u otras ventanas en la implementación de GetCustomUI.De lo contrario, puede que el comportamiento de la cinta de opciones personalizada no sea correcto.Si tiene que ejecutar código que inicialice el complemento, agréguelo al controlador de eventos ThisAddIn_Startup.
OnLoad	Asigne el parámetro Microsoft.Office.Core.IRibbonControl al campo ribbon. Las aplicaciones de Microsoft Office llaman a este método cuando cargan la cinta de opciones personalizada. Puede utilizar este campo para actualizar dinámicamente la cinta personalizada. Para obtener más información, consulte el artículo técnico Customizing the Office (2007) Ribbon User Interface for Developers (Part 1 of 3).
GetResourceText	Lo llama el método GetCustomUI para obtener el contenido del archivo XML de cinta de opciones.