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

Artículo
10/10/2023

El entorno de ejecución de Visual Studio Tools para Office expone un modelo de objetos fuertemente tipado que puede usar para obtener y establecer las propiedades de los controles de la cinta 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 lication 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; Proyecto; Visio; Palabra. Para obtener más información, consulte Características disponibles por aplicación de Office lication y tipo de proyecto.

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

Clase ribbon

Al agregar un nuevo elemento de cinta de opciones (Diseñador visual) a un proyecto, Visual Studio agrega una clase Ribbon al 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 la cinta de opciones y el archivo de código del Diseñador de cintas.

Eventos de la cinta de opciones

La clase Ribbon contiene los tres eventos siguientes:

Evento	Descripción
Load	Se genera cuando la aplicación de Office lication carga la personalización de la cinta de opciones. El Load controlador de eventos se agrega automáticamente al archivo de código de la cinta de opciones. Use este controlador de eventos para ejecutar código personalizado cuando se cargue la cinta de opciones.
LoadImage	Permite almacenar en caché imágenes en la personalización de la cinta de opciones cuando se carga la cinta. Puede obtener un ligero aumento de rendimiento si escribe código para almacenar en caché las imágenes de la cinta de opciones en este controlador de eventos. Para obtener más información, vea LoadImage.
Close	Se genera cuando se cierra la instancia de la cinta de opciones.

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 Introducción a la cinta de opciones.

Nombre del control	Nombre de la clase
Box	RibbonBox
Botón	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Galería	RibbonGallery
Grupo	RibbonGroup
Label	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Tab	RibbonTab
ToggleButton	RibbonToggleButton

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 de opciones, 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.

Para efectuar esta tarea:	Haga esto:
Oculte o muestre un control.	Use la propiedad Visible.
Habilite o deshabilite un control.	Use la propiedad Enabled.
Establezca el tamaño de un control.	Use la propiedad ControlSize.
Obtenga la imagen que aparece en un control .	Utilice la propiedad Image.
Cambie la etiqueta de un control.	Use la propiedad Label.
Agregue datos definidos por el usuario a un control .	Use la propiedad Tag.
Obtener los elementos de , RibbonBox RibbonDropDown, RibbonGalleryo RibbonSplitButton Control.	Utilice la propiedad Items.
Agregue elementos a un RibbonComboBoxcontrol , RibbonDropDowno RibbonGallery .	Utilice la propiedad Items.
Agregue controles a .RibbonMenu	Utilice la propiedad Items. Para agregar controles a RibbonMenu después de cargar la cinta de opciones en la aplicación de Office lication, debe establecer la Dynamic propiedad en true antes de que la cinta de opciones se cargue en la aplicación de Office lication. Para obtener información, vea Establecer propiedades que se convierten en de solo lectura.
Obtener el elemento seleccionado de ,RibbonComboBox RibbonDropDown o RibbonGallery.	Utilice la propiedad SelectedItem. Para , RibbonComboBoxuse la Text propiedad .
Obtenga los grupos en un RibbonTab.	Utilice la propiedad Groups.
Especifique el número de filas y columnas que aparecen en .RibbonGallery	Use las propiedades RowCount y ColumnCount.

Establecimiento de propiedades que se convierten en 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 CreateRibbonExtensibilityObject método de la ThisAddinclase , ThisWorkbooko ThisDocument del 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 cinta de opciones

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 la cinta de opciones.

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 cintas. 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 Explorador de soluciones.

Establecer propiedades en el método CreateRibbonExtensibilityObject

Puede establecer las propiedades de un Ribbon control al invalidar el CreateRibbonExtensibilityObject método en la ThisAddinclase , ThisWorkbooko ThisDocument del proyecto. Para obtener más información sobre el método , vea Información general de la CreateRibbonExtensibilityObject cinta de opciones.

En el ejemplo siguiente se establecen las propiedades de la cinta de opciones en el CreateRibbonExtensibilityObject método de la ThisWorkbook clase 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 se convierten en 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.

Nota:

Puede establecer las propiedades de los controles en menús dinámicos en cualquier momento. Esta tabla no se aplica en ese caso.

Propiedad	Clase de control ribbon
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
Cuadro de diálogo Selector	RibbonGroup
Dinámica	RibbonMenu
Operaciones	OfficeRibbon
Grupos	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Nombre	RibbonComponent
Posición	RibbonButton RibbonCheckBox RibbonGallery RibbonGroup RibbonMenu RibbonSeparator RibbonSplitButton RibbonTab RibbonToggleButton
RibbonType	OfficeRibbon
Rowcount	RibbonGallery
ShowItemImage	RibbonComboBox RibbonDropDown RibbonGallery
ShowItemLabel	RibbonDropDown RibbonGallery
ShowItemSelection	RibbonGallery
SizeString	RibbonComboBox RibbonDropDown RibbonEditBox
StartFromScratch	OfficeRibbon
Pestañas	OfficeRibbon
Título	RibbonSeparator

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 en la tabla anterior solo antes de crear la primera instancia de la cinta de opciones. 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.

Nota:

Asegúrese de que la propiedad Name está establecida para cada control que agregue a una cinta de Outlook. Si agrega un control a una cinta de Outlook en tiempo de ejecución, debe establecer esta propiedad en el código. Si agrega un control a una cinta de Outlook en tiempo de diseño, la propiedad Name se establece automáticamente.

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.

Evento	Descripción
Haga clic en	Se produce cuando se hace clic en un control.
TextChanged	Se produce cuando se cambia el texto de un cuadro de edición o un cuadro combinado.
ItemsLoading	Se produce cuando Office solicita la colección Items del control. Office almacena en caché la colección Items hasta que el código cambia las propiedades del control o llama al InvalidateControl método .
ButtonClick	Se produce cuando se hace clic en un RibbonGallery botón de o RibbonDropDown .
SelectionChanged	Se produce cuando cambia la selección de o RibbonDropDown RibbonGallery .
Cuadro de diálogo Selector Click	Se produce cuando se hace clic en el icono del iniciador de diálogos en la esquina inferior derecha de un grupo.

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

Parámetro	Descripción
Remitente	que Object representa el control que generó el evento.
e	que RibbonControlEventArgs contiene un IRibbonControlobjeto . Use este control para acceder a cualquier propiedad que no esté disponible en el modelo de objetos de la cinta proporcionado por el entorno de ejecución de Visual Studio Tools para Office .