Compartir a través de


Información general sobre el modelo de objetos para la cinta de opciones

Runtime de Microsoft Visual Studio Tools para Office expone un modelo de objetos fuertemente tipados que puede utilizar para obtener y establecer las propiedades de la cinta de opciones en tiempo de ejecución.Por ejemplo, puede rellenar controles de menú de forma dinámica o bien mostrar y ocultar controles contextualmente.También puede agregar pestañas, grupos, y controles a una cinta de opciones, pero antes de la cinta se cargue la aplicación de Office.Para obtener información, vea Establecer propiedades que pasan a ser de solo lectura.

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 2013 y Excel 2010; InfoPath 2013 e InfoPath 2010; Outlook 2013 y Outlook 2010; PowerPoint 2013 y PowerPoint 2010; Project 2013 y Project 2010; Visio 2013 y Visio 2010; Word 2013 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

Este modelo de objetos para la cinta de opciones se compone principalmente de la clase Ribbon, eventos Ribbon y clases de controles de la cinta de opciones.

Clase Ribbon

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

Esta clase aparece como 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 la cinta de opciones.

Eventos Ribbon

La clase Ribbon contiene los tres eventos siguientes:

Evento

Descripción

RibbonBase.Load

Se provoca cuando la aplicación de Office carga la personalización de la cinta de opciones.Agrega el controlador de eventos Load automáticamente al archivo de código de la cinta de opciones.Utilice este controlador de eventos para ejecutar código personalizado cuando se cargue la cinta de opciones.

RibbonBase.LoadImage

Permite almacenar en caché las imágenes de la personalización de la cinta cuando se cargue la cinta de opciones.Puede obtener una ligera mejora del rendimiento si escribe código para almacenar en caché las imágenes de la cinta en este controlador de eventos.Para obtener más información, vea LoadImage.

RibbonBase.Close

Se produce cuando se cierra la instancia de la cinta de opciones.

Controles de la cinta de opciones

El espacio de nombres Microsoft.Office.Tools.Ribbon contiene un tipo para cada control que aparece en el grupo Controles de la cinta de opciones de Office del Cuadro de herramientas.

La tabla siguiente se muestra el tipo de cada control Ribbon .Para obtener una descripción de cada control, vea Información general sobre la cinta de opciones.

Nombre del control

Nombre de la clase

Box

RibbonBox

Button

RibbonButton

ButtonGroup

RibbonButtonGroup

CheckBox

RibbonCheckBox

ComboBox

RibbonComboBox

DropDown

RibbonDropDown

EditBox

RibbonEditBox

Gallery

RibbonGallery

Grupo

RibbonGroup

Etiqueta

RibbonLabel

Menu

RibbonMenu

Separator

RibbonSeparator

SplitButton

RibbonSplitButton

Tab

RibbonTab

ToggleButton

RibbonToggleButton

El espacio de nombres Microsoft.Office.Tools.Ribbon utiliza el prefijo "Ribbon" para estos tipos a fin de evitar conflictos con los nombres de clases de control del espacio de nombres System.Windows.Forms.

Al agregar un control al diseñador de la cinta de opciones, dicho diseñador declara la clase de ese control como un campo en el archivo de código del diseñador de la cinta de opciones.

Bb608623.collapse_all(es-es,VS.110).gifTareas comunes con las propiedades de los controles de la cinta de opciones

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

En algunos casos, las propiedades pasan a ser de sólo lectura una vez cargada la cinta de opciones o tras agregar un control a un menú dinámico.Para obtener más información, vea Establecer propiedades que pasan a ser de solo lectura.

La tabla siguiente se describen algunas de las tareas que puede realizar con propiedades de control Ribbon .

En esta tarea:

Haga lo siguiente:

Ocultar o mostrar un control.

Utilice la propiedad Visible.

Habilitar o deshabilitar un control.

Utilice la propiedad Enabled.

Establecer el tamaño de un control.

Utilice la propiedad ControlSize.

Obtener la imagen que aparece en un control.

Utilice la propiedad Image.

Cambiar la etiqueta de un control.

Utilice la propiedad Label.

Agregar datos definidos por el usuario a un control.

Utilice la propiedad Tag.

Obtener los elementos de un control RibbonBox, RibbonDropDown, RibbonGallery o

RibbonSplitButton.

Utilice la propiedad Items.

Agregar elementos a un control RibbonComboBox, RibbonDropDown o RibbonGallery.

Utilice la propiedad Items.

Agregar controles a RibbonMenu.

Utilice la propiedad Items.

Para agregar controles a RibbonMenu después de la cinta de opciones en la aplicación de Office, debe establecer la propiedad Dynamic a true antes de la cinta de opciones en la aplicación de Office.Para obtener información, vea Establecer propiedades que pasan a ser de solo lectura.

Obtener el elemento seleccionado en RibbonComboBox,

RibbonDropDown o RibbonGallery.

Utilice la propiedad SelectedItem.Para RibbonComboBox, utilice la propiedad Text.

Obtener los grupos de una RibbonTab.

Utilice la propiedad Groups.

Especificar el número de filas y columnas que aparecen en RibbonGallery.

Utilice las propiedades RowCount y ColumnCount.

Establecer propiedades que pasan a ser de solo lectura

Algunas propiedades solo se pueden establecer antes de que se cargue la cinta de opciones.Estas propiedades se establecen en tres lugares:

  • 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 del proyecto.

Los menús dinámicos presentan algunas excepciones.Puede crear nuevos controles, establezca sus propiedades, y después agregarlas a un menú dinámico en tiempo de ejecución, incluso la cinta que contiene el menú se carga.

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 pasan a ser de solo lectura.

Bb608623.collapse_all(es-es,VS.110).gifEstablecer propiedades en el constructor de la cinta de opciones

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

Agregue el código siguiente:

<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
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);
    }
}

En Visual c# actualizados de Visual Studio 2008, el constructor aparece en el archivo de código de la cinta de opciones.

En los proyectos de Visual Basic, o en proyectos de Visual c# creados en Visual Studio 2012, el constructor aparece en el archivo de código del diseñador de la cinta de opciones.Este archivo se denomina suElementoDeCinta.Designer.cs o suElementoDeCinta.Designer.vb.Para ver este archivo en los proyectos de Visual Basic, primero debe hacer clic en el botón Mostrar todos los archivos en el Explorador de soluciones.

Bb608623.collapse_all(es-es,VS.110).gifEstablecer propiedades en el método CreateRibbonExtensibilityObject

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

El ejemplo siguiente se establecen las propiedades de la cinta del método CreateRibbonExtensibilityObject de la clase ThisWorkbook de un proyecto de libro de Excel.

Agregue el código siguiente:

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
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 });
    }
}

Bb608623.collapse_all(es-es,VS.110).gifPropiedades que pasan a ser de solo lectura

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

[!NOTA]

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

Propiedad

Clase de control de la cinta de opciones

BoxStyle

RibbonBox

ButtonType

RibbonSplitButton

ColumnCount

RibbonGallery

ControlId

RibbonTab

DialogLauncher

RibbonGroup

Dinámico

RibbonMenu

Global

OfficeRibbon

Groups

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

Tabulaciones

OfficeRibbon

Título

RibbonSeparator

Bb608623.collapse_all(es-es,VS.110).gifEstablecer propiedades para las cintas de opciones que aparecen en inspectores de Outlook

Una nueva instancia de la cinta de opciones se crea cada vez que un usuario abre un inspector en el que aparece la cinta de opciones.Sin embargo, puede establecer las propiedades enumeradas en la tabla anterior antes de la primera instancia de la cinta de opciones se crea.Después de crear la primera instancia, estas propiedades pasan a ser de solo lectura porque la primera instancia define el archivo XML que utiliza Outlook para cargar la cinta de opciones.

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

[!NOTA]

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

Eventos de controles 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

Click

Se produce al hacer clic en un control.

TextChanged

Se produce cuando se cambia el texto de un cuadro de edición o cuadro combinado.

ItemsLoading

Se produce cuando Office solicita la colección Items del control.Office almacena la colección Items en memoria caché hasta que el código cambia las propiedades del control o se llama al método IRibbonUI.InvalidateControl.

ButtonClick

Se produce al hacer clic en un botón de RibbonGallery o RibbonDropDown.

SelectionChanged

Se produce cuando cambia la selección de RibbonDropDown o RibbonGallery.

DialogLauncherClick

Se produce al hacer clic en el icono que inicia un cuadro de diálogo situado en la esquina inferior derecha de un grupo.

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

Parámetro

Descripción

sender

Objeto Object que representa el control que provocó el evento.

e

Un objeto RibbonControlEventArgs que contiene un control Microsoft.Office.Core.IRibbonControl.Use este control para tener acceso a cualquier propiedad que no esté disponible en el modelo de objetos para la cinta de opciones que proporciona Runtime de Microsoft Visual Studio Tools para Office.

Vea también

Tareas

Cómo: Iniciarse en la personalización de la cinta de opciones

Tutorial: Crear una pestaña personalizada usando el diseñador de la cinta de opciones

Tutorial: Actualizar los controles de una cinta de opciones en tiempo de ejecución

Cómo: Personalizar una pestaña integrada

Cómo: Agregar controles en la vista Backstage

Cómo: Exportar una cinta de opciones del diseñador de la cinta de opciones a XML de la cinta de opciones

Cómo: Mostrar errores de la interfaz de usuario

Referencia

Microsoft.Office.Tools.Ribbon

Conceptos

Obtener acceso a la cinta de opciones en tiempo de ejecución

Diseñador de la cinta de opciones

Personalizar una cinta de opciones para Outlook

Otros recursos

Información general sobre la cinta de opciones