Información general sobre recuadros de acciones

Artículo
08/10/2011

Un panel de acciones es un panel de tareas Acciones de documentos que se puede personalizar y que está asociado a un documento de Microsoft Office Word o a un libro de Microsoft Office Excel específicos. Está hospedado en el panel de tareas de Office junto con otros paneles de tareas integrados, como Origen XML en Excel o Estilos y formato en Word. Puede utilizar los controles de formularios Windows Forms o los controles de WPF para diseñar la interfaz de usuario del panel de acciones.

Se aplica a: la información de este tema se aplica a los proyectos de nivel de documento para las siguientes aplicaciones: Excel 2007 y Excel 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.

Puede crear un panel de acciones sólo en una personalización de nivel de documento para Word o Excel. No puede crear un panel de acciones en un complemento de nivel de aplicación. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

Nota

El panel de acciones se diferencia de los paneles de tareas personalizados. Los paneles de tareas personalizados están asociados con la aplicación, no con un documento específico. Puede crear paneles de tareas personalizados para los complementos de nivel de aplicación de algunas aplicaciones de Microsoft Office. Para obtener más información, vea Información general sobre los paneles de tareas personalizados.

vínculo a vídeo Dispone de una demostración en vídeo en How Do I: Use WPF Controls Inside an Excel Actions Pane?.

Mostrar el panel de acciones

El panel de acciones se representa mediante la clase ActionsPane. Al crear un proyecto en el nivel del documento, hay una instancia de esta clase disponible para el código mediante el campo ActionsPane de la clase ThisWorkbook (para Excel) o ThisDocument (para Word) en el proyecto. Para mostrar el panel de acciones, agregue un control de Windows Forms a la propiedad Controls del campo ActionsPane. En el ejemplo de código siguiente se agrega un control denominado actions al panel de acciones.

Me.ActionsPane.Controls.Add(actions)

this.ActionsPane.Controls.Add(actions);

El panel de acciones se vuelve visible en tiempo de ejecución tan pronto como se le agrega explícitamente un control. Una vez mostrado el panel de acciones, puede agregar o quitar dinámicamente controles en respuesta a las acciones del usuario. Normalmente, agregará el código para mostrar el panel de acciones en el controlador de eventos Startup de ThisDocument o de ThisWorkbook, de manera que el panel de acciones esté visible cuando el usuario abra el documento por primera vez. Sin embargo, puede que desee mostrar el panel de acciones en respuesta a la acción de un usuario en el documento. Por ejemplo, puede agregar el código al evento Click de un control del documento.

Agregar varios controles al panel de acciones

Cuando agregue varios controles al panel de acciones, en la mayoría de los casos es conveniente agrupar los controles en un control de usuario y, a continuación, agregar el control de usuario a la propiedad Controls. Este proceso incluye los pasos siguientes:

Cree la interfaz de usuario del panel de acciones agregando un elemento Control del panel de acciones o Control de usuario al proyecto. Ambos elementos incluyen una clase UserControl de Windows Forms personalizada. Los elementos Control del panel de acciones y Control de usuario son equivalentes; la única diferencia es su nombre.
Agregue los controles de Windows Forms a UserControl utilizando el diseñador o escribiendo el código.

Nota

También puede agregar controles de WPF al panel de acciones agregando un System.Windows.Controls.UserControl de WPF al control UserControl de Windows Forms. Para obtener más información, vea Usar controles de WPF en soluciones de Office.
Agregue una instancia del control de usuario personalizado a los controles contenidos en el campo ActionsPane de la clase ThisWorkbook (para Excel) ThisDocument (para Word) del proyecto.

Para obtener ejemplos que muestran con más detalle este proceso, vea Cómo: Agregar un recuadro de acciones a un documento de Word y Cómo: Agregar un recuadro de acciones a un libro de Excel.

Ocultar el panel de acciones

Aunque la clase ActionsPane cuenta con un método Hide y con una propiedad Visible, no se puede quitar el panel de acciones de la interfaz de usuario utilizando los miembros de la propia clase ActionsPane. Cuando se llama al método Hide o se establece la propiedad Visible en false, sólo se ocultan los controles del panel de acciones, pero no se oculta el panel de tareas.

Para ocultar el panel de tareas en la solución, tiene varias opciones:

Para Word, establezca en false la propiedad Visible del objeto TaskPane que representa el panel de tareas Acciones de documentos. El ejemplo de código siguiente está pensado para ejecutarse desde la clase ThisDocument del proyecto.
```
Me.Application.TaskPanes(Word.WdTaskPanes.wdTaskPaneDocumentActions).Visible = False
```
```
this.Application.TaskPanes[Word.WdTaskPanes.wdTaskPaneDocumentActions].Visible = false;
```
Para Excel, establezca en false la propiedad DisplayDocumentActionTaskPane del objeto Application. El ejemplo de código siguiente está pensado para ejecutarse desde la clase ThisWorkbook del proyecto.
```
Me.Application.DisplayDocumentActionTaskPane = False
```
```
this.Application.DisplayDocumentActionTaskPane = false;
```
Si lo prefiere, para Word o Excel, puede establecer en false la propiedad CommandBar.Visible de la barra de comandos que representa el panel de tareas. El ejemplo de código siguiente está pensado para ejecutarse desde la clase ThisDocument o ThisWorkbook del proyecto.
```
Me.Application.CommandBars("Task Pane").Visible = False
```
```
this.Application.CommandBars["Task Pane"].Visible = false;
```

Borrar el panel de acciones al abrir el documento

Si el usuario guarda el documento mientras el panel de acciones está visible, dicho panel estará visible cada vez que se abra el documento, independientemente de que contenga algún control. Si desea controlar el momento en que va a aparecer, llame al método Clear del campo ActionsPane en el controlador de eventos Startup de ThisDocument o ThisWorkbook para asegurarse de que el panel de acciones no esté visible cuando se abra un documento.

Determinar cuándo está cerrado el panel de acciones

Al cerrar el panel de acciones no se provoca ningún evento. Aunque la clase ActionsPane tiene un evento VisibleChanged, éste no se provoca cuando el usuario final cierra el panel de acciones. En cambio, se provoca este evento cuando se ocultan los controles del panel de acciones llamando al método Hide o estableciendo la propiedad Visible en false.

Si el usuario final cierra el panel de acciones, el usuario puede mostrarlo de nuevo realizando uno de los procedimientos siguientes en la interfaz de usuario de la aplicación.

Para mostrar el panel de acciones mediante la interfaz de usuario de Word o Excel

En la cinta de opciones, haga clic en la ficha Ver.
En el grupo Mostrar u ocultar, haga clic en el botón de alternancia Acciones de documentos.

Programar eventos del panel de acciones

Puede agregar varios controles de usuario al panel de acciones y, a continuación, escribir código para responder a los eventos del documento mostrando y ocultando los controles de usuario. Si asigna elementos de esquema XML a su documento, puede mostrar determinados controles de usuario en el panel de acciones cada vez que se coloca el punto de inserción dentro de uno de los elementos XML. Para obtener más información, vea Tutorial: Cambiar el recuadro de acciones de acuerdo con el contexto del usuario, Cómo: Asignar esquemas a documentos de Word en Visual Studio y Cómo: Asignar esquemas a hojas de cálculo en Visual Studio.

También puede escribir código para responder a los eventos de cualquier objeto, incluso a eventos de controles host, aplicaciones o documentos. Para obtener más información, vea Tutorial: Programar basándose en los eventos de un control NamedRange.

Enlazar datos a controles en un panel de acciones.

Los controles del panel de acciones tienen las mismas capacidades de enlace de datos que los controles de los formularios Windows Forms. Puede enlazar los controles a orígenes de datos como conjuntos de datos, conjuntos de datos con tipo y XML. Para obtener más información, vea Enlace de datos y formularios Windows Forms.

Puede enlazar los controles del panel de acciones y los controles del documento al mismo conjunto de datos. Por ejemplo, puede crear una relación principal-detalle entre los controles del panel de acciones y los controles de la hoja de cálculo. Para obtener más información, vea Tutorial: Enlazar datos a controles en un recuadro de acciones de Excel.

Validar datos de controles de paneles de acciones

Si se muestra un cuadro de mensaje en el controlador de eventos Validating de un control del panel de acciones, el evento podría iniciarse una segunda vez al desplazar el foco del control al cuadro de mensaje. Para evitar este problema, use un control ErrorProvider para mostrar los mensajes de error de validación.

Orden de pila de los controles de usuario

Si está utilizando varios controles de usuario, puede escribir código para apilar correctamente los controles de usuario en el panel de acciones, ya esté acoplado verticalmente u horizontalmente. Puede establecer el orden de pila de los controles de usuario del panel de acciones utilizando la enumeración StackStyle de la propiedad StackOrder. Para obtener más información, vea Cómo: Administrar el diseño de controles en recuadros de acciones.

La propiedad StackOrder puede tomar los siguientes valores de la enumeración StackStyle.

Estilo de pila	Definición
FromBottom	Apilar desde la parte inferior del panel de acciones.
FromLeft	Apilar desde la parte izquierda del panel de acciones.
FromRight	Apilar desde la parte derecha del panel de acciones.
FromTop	Apilar desde la parte superior del panel de acciones.
None	Ningún orden de apilamiento definido; el desarrollador controla el orden.

El código siguiente establece la propiedad StackOrder para apilar los controles de usuario desde la parte superior del panel de acciones.

Me.ActionsPane.StackOrder = Microsoft.Office.Tools.StackStyle.FromTop

this.ActionsPane.StackOrder = Microsoft.Office.Tools.StackStyle.FromTop;

Acoplar controles

Si el usuario cambia el tamaño del panel de acciones en tiempo de ejecución, los controles pueden cambiar su tamaño junto con el panel de acciones. Puede utilizar la propiedad Anchor de un control de formulario Windows Forms para acoplar los controles al panel de acciones. También puede acoplar de la misma manera los controles de formulario Windows Forms al control de usuario. Para obtener más información, vea Cómo: Delimitar controles en formularios Windows Forms.

Cambiar el tamaño del panel de acciones

No se puede cambiar directamente el tamaño de un ActionsPane porque el ActionsPane está incrustado en el panel de tareas. Sin embargo, se puede cambiar mediante programación el ancho del panel de tareas estableciendo la propiedad Width de la CommandBar que representa el panel de tareas. El alto del panel de tareas se puede cambiar si está acoplado horizontalmente o está flotando.

Por lo general, no se recomienda cambiar el tamaño del panel de tareas mediante programación porque el usuario debe poder elegir el tamaño del panel de tareas que mejor se ajuste a sus necesidades. Sin embargo, si tiene que cambiar el ancho del panel de tareas, podrá utilizar el siguiente código.

Me.CommandBars("Task Pane").Width = 200

this.CommandBars["Task Pane"].Width = 200;

Cambiar de posición el panel de acciones

No se puede cambiar directamente la posición del ActionsPane porque está incrustado en el panel de tareas. Sin embargo, se puede mover el panel de tareas mediante programación estableciendo la propiedad Position de la CommandBar que representa el panel de tareas.

Por lo general, no se recomienda cambiar de posición el panel de tareas mediante programación porque el usuario debería poder elegir la posición del panel en la pantalla que mejor se ajuste a sus necesidades. Sin embargo, en caso de que deba moverse el panel de tareas a una posición determinada, el usuario podría utilizar el código siguiente para lograrlo.

Me.CommandBars("Task Pane").Position = _
    Microsoft.Office.Core.MsoBarPosition.msoBarLeft

this.CommandBars["Task Pane"].Position =
    Microsoft.Office.Core.MsoBarPosition.msoBarLeft;

Nota

Los usuarios finales pueden cambiar de posición manualmente el panel de tareas en cualquier momento. No existe ninguna manera de garantizar que el panel de tareas permanecerá bloqueado en la posición que se indique mediante programación. No obstante, puede comprobar los cambios de orientación y asegurarse de que los controles del panel de acciones estén apilados en el sentido correcto. Para obtener más información, vea Cómo: Administrar el diseño de controles en recuadros de acciones.

El establecimiento de las propiedades Top y Left de ActionsPane no cambia la posición en cuestión porque el objeto ActionsPane está incrustado en el panel de tareas.

Si el panel de tareas no está acoplado, es posible establecer las propiedades Top y Left de CommandBar que representa el panel de tareas. El siguiente código desplaza un panel de tareas desacoplado a la esquina superior izquierda del documento.

If Me.CommandBars("Task Pane").Position = _
    Microsoft.Office.Core.MsoBarPosition.msoBarFloating Then

    Me.CommandBars("Task Pane").Top = 0
    Me.CommandBars("Task Pane").Left = 0

End If

if (this.CommandBars["Task Pane"].Position == 
    Microsoft.Office.Core.MsoBarPosition.msoBarFloating)
{
    this.CommandBars["Task Pane"].Top = 0;
    this.CommandBars["Task Pane"].Left = 0;
}

Vea también