Introducción al modelo de objetos de la cinta de herramientas

El entorno de ejecución de Visual Studio Tools para Office expone un modelo de objetos con tipado fuerte que puede usar para obtener y establecer las propiedades de los controles de la cinta de opciones en tiempo de ejecución. Por ejemplo, puede rellenar dinámicamente controles de menú o mostrar y ocultar controles contextualmente. También puede agregar pestañas, grupos y controles a una cinta de opciones, pero solo antes de que la aplicación de Office cargue la cinta de opciones. Para obtener información, vea Establecer propiedades que se convierten en de solo lectura.

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.

Este modelo de objetos de la cinta consta principalmente de la clase Ribbon, los eventos Ribbon y las clases de control de cinta.

Clase Ribbon

Al agregar un nuevo elemento Ribbon (Diseñador visual) a un proyecto, Visual Studio agrega una clase Ribbon a su proyecto. La clase Ribbon hereda de la RibbonBase clase .

Esta clase aparece como una clase parcial que se divide entre el archivo de código de Ribbon y el archivo de código del Diseñador de Ribbon.

Eventos de la cinta de opciones

La clase Ribbon contiene los tres eventos siguientes:

Controles de la cinta de opciones

El Microsoft.Office.Tools.Ribbon espacio de nombres contiene un tipo para cada control que ve en el grupo Controles de cinta de Office del cuadro de herramientas.

En la tabla siguiente se muestra el tipo de cada Ribbon control. Para obtener una descripción de cada control, consulte Visión general de la cinta de opciones.

El Microsoft.Office.Tools.Ribbon espacio de nombres usa el prefijo "Ribbon" para estos tipos para evitar una colisión de nombres con los nombres de las clases de control en el System.Windows.Forms espacio de nombres.

Al agregar un control al Diseñador de cintas, el Diseñador de cintas declara la clase para ese control como un campo en el archivo de código del Diseñador de cintas.

Tareas comunes que usan las propiedades de los controles de la cinta de opciones

Cada Ribbon control contiene propiedades que se pueden usar para realizar diversas tareas, como asignar una etiqueta a un control o ocultar y mostrar controles.

En algunos casos, las propiedades se convierten en de solo lectura después de que la cinta de opciones se cargue o después de agregar un control a un menú dinámico. Para obtener más información, consulte Establecimiento de propiedades que se convierten en de solo lectura.

En la tabla siguiente se describen algunas de las tareas que puede realizar mediante Ribbon propiedades de control.

Configurar propiedades que se vuelven de solo lectura

Algunas propiedades solo se pueden establecer antes de que se cargue la cinta de opciones. Hay tres lugares para establecer estas propiedades:

• En la ventana Propiedades de Visual Studio.

• En el constructor de la clase Ribbon .

• En el método CreateRibbonExtensibilityObject de la clase ThisAddin, ThisWorkbook o ThisDocument de tu proyecto.

  Los menús dinámicos proporcionan algunas excepciones. Puede crear nuevos controles, establecer sus propiedades y, a continuación, agregarlos a un menú dinámico en tiempo de ejecución, incluso después de cargar la cinta de opciones que contiene el menú.

  Las propiedades de los controles que se agregan a un menú dinámico se pueden establecer en cualquier momento.

  Para obtener más información, vea Propiedades que se convierten en de solo lectura.

Establecer propiedades en el constructor de la barra de herramientas

Puede establecer las propiedades de un Ribbon control en el constructor de la clase Ribbon . Este código debe aparecer después de la llamada al InitializeComponent método . En el ejemplo siguiente se agrega un botón nuevo a un grupo si la hora actual es 17:00 Hora del Pacífico (UTC-8) o posterior.

Agregue el código siguiente.

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

En los proyectos de Visual C# que actualizó desde Visual Studio 2008, el constructor aparece en el archivo de código de Ribbon.

En proyectos de Visual Basic o en proyectos de Visual C# creados en Visual Studio 2013, el constructor aparece en el archivo de código del Diseñador de Ribbon. Este archivo se denomina YourRibbonItem. Designer.cs o YourRibbonItem. Designer.vb. Para ver este archivo en proyectos de Visual Basic, primero debe hacer clic en el botón Mostrar todos los archivos en el Explorador de soluciones.

Establecer propiedades en el método CreateRibbonExtensibilityObject

Puede establecer las propiedades de un Ribbon control al sobrescribir el método CreateRibbonExtensibilityObject en la clase ThisAddin, ThisWorkbook o ThisDocument de su proyecto. Para obtener más información sobre el CreateRibbonExtensibilityObject método, consulte Información general de la cinta de opciones.

En el siguiente ejemplo, se establecen las propiedades de la cinta de opciones en el método CreateRibbonExtensibilityObject de la clase ThisWorkbook de un proyecto de libro de Excel.

Agregue el código siguiente.

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = false;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager( 
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[]
             { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { tempRibbon });
    }
}

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    End If
End Function

Propiedades que pasan a ser de solo lectura

En la tabla siguiente se muestran las propiedades que solo se pueden establecer antes de que se cargue la cinta de opciones.

Establecer propiedades para las cintas de opciones que aparecen en los inspectores de Outlook

Se crea una nueva instancia de la cinta cada vez que un usuario abre un Inspector en el que aparece la cinta. Sin embargo, puede establecer las propiedades enumeradas anteriormente en la tabla solo antes de crear la primera instancia de la cinta. Una vez creada la primera instancia, estas propiedades se convierten en de solo lectura porque la primera instancia define el archivo XML que Outlook usa para cargar la cinta de opciones.

Si tiene lógica condicional que establece cualquiera de estas propiedades en un valor diferente cuando se crean otras instancias de la cinta de opciones, este código no tendrá ningún efecto.

Eventos de control de la cinta de opciones

Cada clase de control contiene uno o varios eventos. En la tabla siguiente se describen estos eventos.

Los controladores de eventos de estos eventos tienen los dos parámetros siguientes.

Contenido relacionado

• Acceder a la cinta de opciones en tiempo de ejecución
• Descripción general de la cinta de opciones
• Cómo: Introducción a la personalización de la cinta
• Diseñador de cintas
• Guía paso a paso: Creación de una pestaña personalizada mediante el Diseñador de la cinta
• Tutorial: Actualizar los controles de una cinta durante la ejecución
• Personalizar la cinta de opciones en Outlook
• Cómo: Personalizar una pestaña integrada
• Cómo: Agregar controles a la vista Backstage
• Exportar una cinta de opciones del Diseñador de cintas a XML de la cinta de opciones
• Cómo: Mostrar errores de la interfaz de usuario del complemento