Información general sobre el modelo de objetos para la cinta de opciones
Actualización: Julio de 2008
Se aplica a |
---|
La información de este tema solo se aplica a los proyectos y versiones especificados de Visual Studio Tools para Office de Microsoft Office. Tipo de proyecto
Versión de Microsoft Office
Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto. |
Visual Studio Tools para Office expone un modelo de objetos con establecimiento inflexible de tipos que se puede utilizar para obtener y establecer las propiedades de los controles 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 fichas, grupos y controles a una cinta de opciones, pero solo antes de que la aplicación de Office cargue dicha cinta. Para obtener información, vea Establecer propiedades que pasan a ser de solo lectura.
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
Cuando se agrega un nuevo elemento Cinta (diseñador visual) a un proyecto, Visual Studio Tools para Office agrega una clase al proyecto que hereda de la clase OfficeRibbon.
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 OfficeRibbon contiene los tres eventos siguientes:
El evento Load se provoca cuando la aplicación de Office carga la personalización de la cinta de opciones. El controlador de eventos Load se agrega automáticamente al archivo de código de la cinta de opciones. Utilice este controlador de eventos para ejecutar código personalizado cuando se carga la cinta de opciones.
El evento LoadImage permite almacenar en caché las imágenes de la personalización de la cinta de opciones al cargar dicha cinta. 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.
El evento Close se provoca cuando se cierra la instancia de la cinta de opciones.
Clases de controles de la cinta de opciones
El espacio de nombres Microsoft.Office.Tools.Ribbon contiene una clase Ribbon para cada control que aparece en el grupo Controles de la cinta de opciones de Office del Cuadro de herramientas.
En la tabla siguiente se muestra la clase de cada control de la cinta de opciones. 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 |
|
Button |
|
ButtonGroup |
|
CheckBox |
|
ComboBox |
|
DropDown |
|
EditBox |
|
Gallery |
|
Group |
|
Label |
|
Menu |
|
Separator |
|
SplitButton |
|
Tab |
|
ToggleButton |
El espacio de nombres Microsoft.Office.Tools.Ribbon utiliza el prefijo "Ribbon" para estas clases a fin de evitar una colisión 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.
Tareas comunes utilizando las propiedades de las clases de controles de la cinta de opciones
Cada clase de control de la cinta de opciones contiene propiedades que se pueden utilizar 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 solo lectura una vez cargada la cinta 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.
En la tabla siguiente se describen algunas de las tareas que se pueden realizar utilizando propiedades de los controles de la cinta de opciones.
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 |
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 una vez cargada la cinta de opciones en la aplicación de Office, debe establecer la propiedad Dynamic en true antes de que se cargue la cinta en dicha aplicación. Para obtener información, vea Establecer propiedades que pasan a ser de solo lectura. |
Obtener el elemento seleccionado en RibbonComboBox, |
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 del proyecto.
Los menús dinámicos presentan algunas excepciones. Puede crear nuevos controles, establecer sus propiedades y después agregarlas a un menú dinámico en tiempo de ejecución, incluso una vez cargada la cinta que contiene el menú.
A partir de Visual Studio 2008 Service Pack 1 (SP1), se pueden establecer las propiedades de los controles que se agregan a un menú dinámico en cualquier momento. Sin embargo, si no ha instalado el SP1, algunas propiedades pasan a ser de solo lectura una vez agregado al menú el control.
Para obtener más información, vea Propiedades que pasan a ser de solo lectura.
Establecer propiedades en el constructor de la cinta de opciones
Puede establecer las propiedades de un control de cinta de opciones 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.
<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
MyBase.New()
'This call is required by the Component Designer.
InitializeComponent()
If DateTime.Now.Hour > 16 Then
Group1.Items.Add(New RibbonButton())
CType(Group1.Items.Last(), RibbonButton).Label = "New Button"
End If
End Sub
public Ribbon1()
{
InitializeComponent();
if (DateTime.Now.Hour > 16)
{
group1.Items.Add(new RibbonButton());
((RibbonButton)group1.Items.Last()).Label = "New Button";
}
}
Establecer propiedades en el método CreateRibbonExtensibilityObject
Puede establecerlas propiedades de un control de la cinta de opciones al invalidar el método CreateRibbonExtensibilityObject en la clase ThisAddin, ThisWorkbook o ThisDocument del proyecto. Para obtener más información sobre el método CreateRibbonExtensibilityObject, vea Información general sobre la cinta de opciones.
En el ejemplo siguiente se establecen propiedades Ribbon en el método CreateRibbonExtensibilityObject de la clase ThisWorkbook de un proyecto de libro de Excel 2007.
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 New Microsoft.Office.Tools.Ribbon.RibbonManager _
(New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
Else
Dim tempRibbon As New Ribbon2()
tempRibbon.Tab1.ControlId.ControlIdType = _
Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
(New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
End If
End Function
protected override Microsoft.Office.Core.IRibbonExtensibility
CreateRibbonExtensibilityObject()
{
bool myCondition = true;
if (myCondition == true)
{
Ribbon1 tempRibbon = new Ribbon1();
tempRibbon.tab1.ControlId.ControlIdType =
Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
tempRibbon.tab1.ControlId.OfficeId = "TabHome";
return new Microsoft.Office.Tools.Ribbon.RibbonManager(
new Microsoft.Office.Tools.Ribbon.OfficeRibbon[]
{ tempRibbon });
}
else
{
Ribbon2 tempRibbon = new Ribbon2();
tempRibbon.tab1.ControlId.ControlIdType =
Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
return new Microsoft.Office.Tools.Ribbon.RibbonManager(
new Microsoft.Office.Tools.Ribbon.OfficeRibbon[]
{ tempRibbon });
}
}
Propiedades 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.
![]() |
---|
Si instala el SP1, puede establecer en cualquier momento las propiedades de los controles en menús dinámicos. Esta tabla no se aplica en ese caso. |
Propiedad |
Clase de control de la cinta de opciones |
---|---|
BoxStyle |
|
ButtonType |
|
ColumnCount |
|
ControlId |
|
DialogLauncher |
|
Dynamic |
|
Global |
|
Groups |
|
ImageName |
|
ItemSize |
|
MaxLength |
|
Name |
|
Position |
|
RibbonType |
|
RowCount |
|
ShowItemImage |
|
ShowItemLabel |
|
ShowItemSelection |
|
SizeString |
|
StartFromScratch |
|
Tabs |
|
Title |
Establecer propiedades para las cintas de opciones que aparecen en inspectores de Outlook
Cada vez que un usuario abre un inspector en el que aparece la cinta de opciones, se crea una nueva instancia de la cinta. Sin embargo, puede establecer las propiedades que se enumeran en la tabla anterior antes de que se cree la primera instancia de la cinta de opciones. Una vez creada 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.
Si tiene una lógica condicional que establece cualquiera de estas propiedades en un valor distinto cuando se crean otras instancias de la cinta, este código no tendrá ningún efecto.
![]() |
---|
Asegúrese de que la propiedad Name 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 Microsoft.Office.Core.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 |
Objeto RibbonControlEventArgs que contiene un Microsoft.Office.Core.IRibbonControl. Utilice este control para tener acceso a cualquier propiedad que no está disponible en el modelo de objetos para la cinta de opciones de Visual Studio Tools para Office. |
Vea también
Tareas
Cómo: Iniciarse en la personalización de la cinta de opciones
Tutorial: Crear una ficha 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 ficha integrada
Cómo: Personalizar el menú de Microsoft Office
Cómo: Mostrar errores de la interfaz de usuario
Conceptos
Acceso a la cinta de opciones en tiempo de ejecución
Información general sobre la cinta de opciones
diseñador de la cinta de opciones
Personalizar una Cinta de opciones para Outlook
Referencia
Historial de cambios
Fecha |
Historial |
Motivo |
---|---|---|
Julio de 2008 |
Información revisada sobre cómo establecer propiedades de controles en menús dinámicos después de instalar SP1. |
Cambio de características de SP1. |