Tutorial: Mostrar paneles de tareas personalizados con mensajes de correo electrónico en Outlook

Artículo
04/28/2010

Actualización: noviembre 2007

Se aplica a
La información de este tema sólo se aplica a los proyectos especificados de Visual Studio Tools para Office y a las aplicaciones de Microsoft Office. Tipo de proyecto Proyectos de nivel de aplicación Aplicación de Microsoft Office Outlook 2007 Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

La información de este tema sólo se aplica a los proyectos especificados de Visual Studio Tools para Office y a las aplicaciones de Microsoft Office.

Tipo de proyecto

Proyectos de nivel de aplicación

Aplicación de Microsoft Office

Outlook 2007

Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

En este tutorial se explica cómo se muestra una única instancia de un panel de tareas personalizado con cada mensaje de correo electrónico que se crea o se abre. Los usuarios pueden mostrar u ocultar el panel de tareas personalizado utilizando el botón de la cinta de opciones de cada mensaje de correo electrónico.

Para mostrar un panel de tareas personalizado con varias ventanas de explorador o inspector, debe crear una instancia del panel de tareas personalizado para cada ventana que se abra. Para obtener más información sobre el comportamiento de los paneles de tareas personalizados en las ventanas de Outlook, vea Información general sobre los paneles de tareas personalizados.

Nota:
En este tutorial se presenta el código del complemento en pequeñas secciones para que resulte más fácil explicar la lógica que subyace al código. Para ver el contenido completo de todos los archivos que edite en este tutorial, vea Cómo: Mostrar paneles de tareas personalizados con mensajes de correo electrónico en Outlook.

Este tutorial ilustra las tareas siguientes:

Diseñar la interfaz de usuario del panel de tareas personalizado
Crear una interfaz de usuario de cinta de opciones personalizada
Mostrar la interfaz de usuario de la cinta de opciones personalizada en mensajes de correo electrónico.
Crear una clase para administrar ventanas de inspector y paneles de tareas personalizados.
Inicializar y limpiar los recursos utilizados por el complemento.
Sincronizar el botón de alternar de la cinta de opciones con el panel de tareas personalizado.

Nota:
Es posible que su equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio en las siguientes instrucciones. La edición de Visual Studio que tenga y la configuración que esté utilizando determinan estos elementos. Para obtener más información, vea Valores de configuración de Visual Studio.

Requisitos previos

Necesita los componentes siguientes para completar este tutorial:

Visual Studio Tools para Office (componente opcional de Visual Studio 2008 Professional y Visual Studio Team System).
Microsoft Office Outlook 2007.

Visual Studio Tools para Office se instala, de forma predeterminada, con las versiones que se enumeran de Visual Studio. Para comprobar si está instalado, vea Instalar Visual Studio Tools para Office.

Creación del proyecto

Los paneles de tareas personalizados se implementan en complementos de nivel de aplicación. Empiece por crear un proyecto de complemento para Outlook 2007.

Para crear un nuevo proyecto

Cree un proyecto Complemento de Outlook con el nombre OutlookMailItemTaskPane. Utilice la plantilla de proyecto Complemento de Outlook de Microsoft Office System 2007. Para obtener más información, vea Cómo: Crear proyectos de Visual Studio para Office.

Visual Studio abre el archivo de código ThisAddIn.cs o ThisAddIn.vb y agrega el proyecto OutlookMailItemTaskPane al Explorador de soluciones.

Diseñar la interfaz de usuario del panel de tareas personalizado

No existe ningún diseñador visual para los paneles de tareas personalizados, pero puede diseñar un control de usuario con la interfaz de usuario que desee. El panel de tareas personalizado de este complemento tiene una interfaz de usuario sencilla que contiene un control TextBox. Más adelante en este tutorial, agregará el control de usuario al panel de tareas personalizado.

Para diseñar la interfaz de usuario del panel de tareas personalizado

En el Explorador de soluciones, haga clic con en el proyecto OutlookMailItemTaskPane.
En el menú Proyecto, haga clic en Agregar control de usuario.
En el cuadro de diálogo Agregar nuevo elemento, cambie el nombre del control de usuario por TaskPaneControl y haga clic en Agregar.

Se abre el control de usuario en el diseñador.
En la ficha Controles comunes del Cuadro de herramientas, arrastre un control TextBox hasta el control de usuario.

Diseñar la interfaz de usuario de la cinta de opciones

Uno de los objetivos de este complemento es proporcionar a los usuarios un mecanismo para ocultar o mostrar el panel de tareas personalizado en la cinta de opciones de cada mensaje de correo electrónico. Para proporcionar la interfaz de usuario, cree una interfaz de usuario de cinta de opciones personalizada donde aparezca un botón de alternar en el que los usuarios puedan hacer clic para mostrar u ocultar el panel de tareas personalizado.

Para crear una interfaz de usuario la cinta de opciones personalizada

En el menú Proyecto, haga clic en Agregar nuevo elemento.
En el cuadro de diálogo Agregar nuevo elemento, seleccione Cinta (diseñador visual).
Cambie el nombre de la nueva cinta de opciones por ManageTaskPaneRibbon y haga clic en Agregar.

El archivo ManageTaskPaneRibbon.cs o ManageTaskPaneRibbon.vb se abre en el diseñador de la cinta de opciones y muestra una ficha y un grupo predeterminados.
En el diseñador de la cinta de opciones, haga clic en group1.
En la ventana Propiedades , establezca la propiedad Label en Administrador del panel de tareas.
En la ficha Controles de la cinta de opciones de Office del Cuadro de herramientas, arrastre el control ToggleButton al grupo Administrador del panel de tareas.
Haga clic en toggleButton1.
En la ventana Propiedades, establezca la propiedad Label en Mostrar panel de tareas.

Mostrar la interfaz de usuario de la cinta de opciones personalizada con los mensajes de correo electrónico

El panel de tareas personalizado que va a crear en este tutorial se ha diseñado para que aparezca únicamente con las ventanas de inspector que contienen mensajes de correo electrónico. Por consiguiente, debe definir las propiedades de forma que la interfaz de usuario de la cinta de opciones personalizada sólo aparezca con estas ventanas.

Para mostrar la interfaz de usuario de la cinta de opciones personalizada con mensajes de correo electrónico

En el diseñador de la cinta de opciones, haga clic en la cinta ManageTaskPaneRibbon.
En la ventana Propiedades, haga clic en la lista desplegable situada junto a RibbonType y seleccione Microsoft.Outlook.Mail.Compose y Microsoft.Outlook.Mail.Read.

Crear una clase para administrar ventanas de inspector y paneles de tareas personalizados

Hay varios casos en los que el complemento debe identificar el panel de tareas personalizado que está asociado con un mensaje de correo electrónico concreto. Entre estos casos se incluyen los siguientes:

Cuando el usuario cierra un mensaje de correo electrónico. En este caso, el complemento debe quitar el panel de tareas personalizado correspondiente para garantizar que los recursos utilizados por el complemento se limpian correctamente.
Cuando el usuario cierra el panel de tareas personalizado. En este caso, el complemento debe actualizar el estado del botón de alternar de la cinta de opciones del mensaje de correo electrónico.
Cuando el usuario hace clic en el botón de alternar de la cinta de opciones. En este caso, el complemento debe ocultar o mostrar el panel de tareas correspondiente.

Para permitir que el complemento haga un seguimiento de qué panel de tareas personalizado está asociado con cada mensaje de correo electrónico abierto, cree una clase personalizada que contenga pares de objetos Inspector y CustomTaskPane. Esta clase crea un nuevo objeto de panel de tareas personalizado para cada mensaje de correo electrónico y elimina el panel de tareas personalizado cuando se cierra el mensaje de correo electrónico correspondiente.

Para crear una clase destinada a la administración de ventanas de inspector y paneles de tareas personalizados

En el Explorador de soluciones, haga clic con el botón secundario del mouse en el archivo ThisAddIn.cs o ThisAddIn.vb y, a continuación, haga clic en Ver código.

Agregue las siguientes instrucciones al comienzo del archivo:

Imports System.Collections.Generic
Imports Microsoft.Office.Tools
Imports Office = Microsoft.Office.Core
Imports Outlook = Microsoft.Office.Interop.Outlook

using Microsoft.Office.Tools;

Agregue el código siguiente al archivo ThisAddIn.cs o ThisAddIn.vb, fuera de la clase (en Visual C#, agregue este código dentro del espacio de nombres OutlookMailItemTaskPane ) ThisAddIn. La clase InspectorWrapper administra un par de objetos Inspector y CustomTaskPane. Completará la definición de esta clase en los pasos siguientes.
```
Public Class InspectorWrapper
    Private inspector As Outlook.Inspector
    Private WithEvents inspectorEvents As Outlook.InspectorEvents_Event
    Private WithEvents taskPane As CustomTaskPane
```
```
public class InspectorWrapper
{
    private Outlook.Inspector inspector;
    private CustomTaskPane taskPane;
```

Agregue el constructor siguiente después del código que agregó en el paso anterior. Este constructor crea e inicializa un nuevo panel de tareas personalizado que está asociado al objeto Inspector que se pasa. En C#, el constructor asocia también los controladores de eventos al evento Close del objeto Inspector y al evento VisibleChanged del objeto CustomTaskPane.

Public Sub New(ByVal Inspector As Outlook.Inspector)
    Me.inspector = Inspector
    inspectorEvents = TryCast(Me.inspector, Outlook.InspectorEvents_Event)
    taskPane = Globals.ThisAddIn.CustomTaskPanes.Add(New TaskPaneControl(), _
        "My task pane", Inspector)
End Sub

public InspectorWrapper(Outlook.Inspector Inspector)
{
    inspector = Inspector;
    ((Outlook.InspectorEvents_Event)inspector).Close +=
        new Outlook.InspectorEvents_CloseEventHandler(InspectorWrapper_Close);

    taskPane = Globals.ThisAddIn.CustomTaskPanes.Add(
        new TaskPaneControl(), "My task pane", inspector);
    taskPane.VisibleChanged += new EventHandler(TaskPane_VisibleChanged);
}

Agregue el método siguiente después del código que agregó en el paso anterior. Este método es un controlador de eventos del evento VisibleChanged del objeto CustomTaskPane incluido en la clase InspectorWrapper. Este código actualiza el estado del botón de alternar cada vez que el usuario abre o cierra el panel de tareas personalizado.

Private Sub TaskPane_VisibleChanged(ByVal sender As Object, ByVal e As EventArgs) _
    Handles taskPane.VisibleChanged
    Globals.Ribbons(inspector).ManageTaskPaneRibbon.ToggleButton1.Checked = taskPane.Visible
End Sub

void TaskPane_VisibleChanged(object sender, EventArgs e)
{
    Globals.Ribbons[inspector].ManageTaskPaneRibbon.toggleButton1.Checked = 
        taskPane.Visible;
}

Agregue el método siguiente después del código que agregó en el paso anterior. Este método es un controlador de eventos del evento Close del objeto Inspector que contiene el mensaje de correo electrónico actual. El controlador de eventos libera los recursos cuando se cierra el mensaje de correo electrónico. El controlador de eventos también quita el panel de tareas personalizado actual de la colección CustomTaskPanes. De este modo, se impide que haya varias instancias del panel de tareas personalizado cuando se abre el mensaje de correo electrónico siguiente.

Sub InspectorWrapper_Close() Handles inspectorEvents.Close
    If Not (taskPane Is Nothing) Then
        Globals.ThisAddIn.CustomTaskPanes.Remove(taskPane)
    End If

    taskPane = Nothing
    Globals.ThisAddIn.InspectorWrappers.Remove(inspector)
    RemoveHandler inspectorEvents.Close, AddressOf InspectorWrapper_Close
    inspector = Nothing
End Sub

void InspectorWrapper_Close()
{
    if (taskPane != null)
    {
        Globals.ThisAddIn.CustomTaskPanes.Remove(taskPane);
    }

    taskPane = null;
    Globals.ThisAddIn.InspectorWrappers.Remove(inspector);
    ((Outlook.InspectorEvents_Event)inspector).Close -=
        new Outlook.InspectorEvents_CloseEventHandler(InspectorWrapper_Close);
    inspector = null;
}

Agregue el código siguiente después del código que agregó en el paso anterior. Más adelante en este tutorial, llamará a esta propiedad desde un método de la interfaz de usuario de la cinta de opciones para mostrar u ocultar el panel de tareas personalizado.

    Public ReadOnly Property CustomTaskPane() As CustomTaskPane
        Get
            Return taskPane
        End Get
    End Property
End Class

    public CustomTaskPane CustomTaskPane
    {
        get
        {
            return taskPane;
        }
    }
}

Inicializar y limpiar los recursos utilizados por el complemento

Agregue código a la clase ThisAddIn para inicializar el complemento cuando éste se cargue y para limpiar los recursos cuando el complemento se descargue. Para inicializar el complemento, configure un controlador de eventos para el evento NewInspector y pase todos los mensajes de correo electrónico existentes a este controlador de eventos. Una vez que se descargue el complemento, desasocie el controlador de eventos y limpie los objetos utilizados por el complemento.

Para inicializar y limpiar los recursos utilizados por el complemento

En el archivo ThisAddIn.cs o ThisAddIn.vb, busque la definición de la clase ThisAddIn.
Agregue las declaraciones siguientes a la clase ThisAddIn:
- El campo inspectorWrappersValue contiene todos los objetos Inspector e InspectorWrapper que administra el complemento.
- El campo inspectors mantiene una referencia a la colección de ventanas de inspector en la instancia de Outlook actual. Esta referencia impide que el recolector de elementos no utilizados libere la memoria que contiene el controlador del evento NewInspector, que declarará en el paso siguiente.
```
Private inspectorWrappersValue As New Dictionary(Of Outlook.Inspector, InspectorWrapper)
Private WithEvents inspectors As Outlook.Inspectors
```
```
private Dictionary<Outlook.Inspector, InspectorWrapper> inspectorWrappersValue =
    new Dictionary<Outlook.Inspector, InspectorWrapper>();
private Outlook.Inspectors inspectors;
```

Reemplace el método ThisAddIn_Startup con el código siguiente. Este código asocia un controlador de eventos al evento NewInspector y pasa cada objeto Inspector existente al controlador de eventos. Si el usuario carga el complemento una vez que se está ejecutando Outlook, el complemento utiliza esta información para crear paneles de tareas personalizados para todos los mensajes de correo electrónico que ya están abiertos.

Private Sub ThisAddIn_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Startup

    inspectors = Me.Application.Inspectors
    Dim inspector As Outlook.Inspector
    For Each inspector In inspectors
        Inspectors_NewInspector(inspector)
    Next inspector
End Sub

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    inspectors = this.Application.Inspectors;
    inspectors.NewInspector +=
        new Outlook.InspectorsEvents_NewInspectorEventHandler(
        Inspectors_NewInspector);

    foreach (Outlook.Inspector inspector in inspectors)
    {
        Inspectors_NewInspector(inspector);
    }
}

Reemplace el método ThisAddIn_ShutDown con el código siguiente. Este código desasocia el controlador de eventos NewInspector y limpia los objetos utilizados por el complemento.

Private Sub ThisAddIn_Shutdown(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Shutdown

    RemoveHandler inspectors.NewInspector, AddressOf Inspectors_NewInspector
    inspectors = Nothing
    inspectorWrappersValue = Nothing
End Sub

private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
{
    inspectors.NewInspector -=
        new Outlook.InspectorsEvents_NewInspectorEventHandler(
        Inspectors_NewInspector);
    inspectors = null;
    inspectorWrappersValue = null;
}

Agregue el controlador de eventos siguiente a la clase NewInspectorThisAddIn. Si un nuevo objeto Inspector contiene un mensaje de correo electrónico, el método crea una instancia de un nuevo objeto InspectorWrapper para administrar la relación entre el mensaje de correo electrónico y el panel de tareas correspondiente.

Sub Inspectors_NewInspector(ByVal Inspector As Outlook.Inspector) _
    Handles inspectors.NewInspector

    If TypeOf Inspector.CurrentItem Is Outlook.MailItem Then
        inspectorWrappersValue.Add(Inspector, New InspectorWrapper(Inspector))
    End If
End Sub

void Inspectors_NewInspector(Outlook.Inspector Inspector)
{
    if (Inspector.CurrentItem is Outlook.MailItem)
    {
        inspectorWrappersValue.Add(Inspector, new InspectorWrapper(Inspector));
    }
}

Agregue la siguiente propiedad a la clase ThisAddIn. Esta propiedad expone el campo inspectorWrappersValue privado al código que está fuera de la clase ThisAddIn.

Public ReadOnly Property InspectorWrappers() As Dictionary(Of Outlook.Inspector, InspectorWrapper)
    Get
        Return inspectorWrappersValue
    End Get
End Property

public Dictionary<Outlook.Inspector, InspectorWrapper> InspectorWrappers
{
    get
    {
        return inspectorWrappersValue;
    }
}

Punto de control

Genere el proyecto para asegurarse de que lo hace sin errores.

Para generar el proyecto

En el Explorador de soluciones, haga clic con el botón secundario del mouse en el proyecto OutlookMailItemTaskPane y, a continuación, haga clic en Generar. Compruebe si el proyecto se genera sin errores.

Sincronizar el botón de alternar de la cinta de opciones con el panel de tareas personalizado

Cuando el panel de tareas esté visible, el botón de alternar aparecerá presionado y cuando el panel de tareas esté oculto, aparecerá sin presionar. Para sincronizar el estado del botón con el panel de tareas personalizado, modifique el controlador de eventos Click del botón de alternar.

Para sincronizar el panel de tareas personalizado con el botón de alternar

En el diseñador de la cinta de opciones, haga doble clic en el botón de alternar Mostrar panel de tareas.

Visual Studio Tools para Office genera automáticamente un controlador de eventos denominado toggleButton1_Click, que controla el evento Click del botón de alternancia. Visual Studio Tools para Office también abre el archivo ManageTaskPaneRibbon.cs o ManageTaskPaneRibbon.vb en el Editor de código.

Agregue las instrucciones siguientes al comienzo del archivo ManageTaskPaneRibbon.cs o ManageTaskPaneRibbon.vb.

Imports Microsoft.Office.Tools.Ribbon
Imports Outlook = Microsoft.Office.Interop.Outlook
Imports Microsoft.Office.Tools

using Outlook = Microsoft.Office.Interop.Outlook;
using Microsoft.Office.Tools;

Reemplace el controlador de evento toggleButton1_Click con el código siguiente. Cuando el usuario hace clic en el botón de alternar, este método oculta o muestra el panel de tareas personalizado que está asociado con la ventana de inspector actual.

Private Sub ToggleButton1_Click(ByVal sender As System.Object, _
    ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
    Handles ToggleButton1.Click

    Dim inspector As Outlook.Inspector = e.Control.Context
    Dim inspectorWrapper As InspectorWrapper = Globals.ThisAddIn.InspectorWrappers(inspector)
    Dim taskPane As CustomTaskPane = inspectorWrapper.CustomTaskPane
    If Not (taskPane Is Nothing) Then
        taskPane.Visible = TryCast(sender, RibbonToggleButton).Checked
    End If
End Sub

private void toggleButton1_Click(object sender, RibbonControlEventArgs e)
{
    Outlook.Inspector inspector = (Outlook.Inspector)e.Control.Context;
    InspectorWrapper inspectorWrapper = Globals.ThisAddIn.InspectorWrappers[inspector];
    CustomTaskPane taskPane = inspectorWrapper.CustomTaskPane;
    if (taskPane != null)
    {
        taskPane.Visible = ((RibbonToggleButton)sender).Checked;
    }
}

Probar el proyecto

Cuando empiece a depurar el proyecto, se abrirá Outlook y se cargará el complemento. El complemento muestra una única instancia del panel de tareas personalizado con cada mensaje de correo electrónico que se abre. Cree varios mensajes de correo electrónico nuevos para probar el código.

Para probar el complemento

Presione F5.
En Outlook, haga clic en Nuevo para crear un nuevo mensaje de correo electrónico.
En la cinta de opciones del mensaje de correo electrónico, haga clic en la ficha Complementos y, a continuación, haga clic en el botón Mostrar panel de tareas.

Compruebe que un panel de tareas con el nombre Mi panel de tareas se muestra con el mensaje de correo electrónico.
En el panel de tareas, escriba Primer panel de tareas en el cuadro de texto.
Cierre el panel de tareas.

Compruebe que el estado del botón Mostrar panel de tareas cambia y ya no aparece presionado.
Haga clic de nuevo en el botón Mostrar panel de tareas.

Compruebe que el panel de tareas se abre y que el cuadro de texto todavía contiene la cadena Primer panel de tareas.
En Outlook, haga clic en Nuevo para crear un segundo mensaje de correo electrónico.
En la cinta de opciones del mensaje de correo electrónico, haga clic en la ficha Complementos y, a continuación, haga clic en el botón Mostrar panel de tareas.

Compruebe que se muestra un panel de tareas con el nombre Mi panel de tareas con el mensaje de correo electrónico y que el cuadro de texto de este panel de tareas está vacío.
En el panel de tareas, escriba Segundo panel de tareas en el cuadro de texto.
Cambie el foco al primer mensaje de correo electrónico.

Compruebe que en el panel de tareas que está asociado a este mensaje de correo electrónico aún aparece Primer panel de tareas en el cuadro de texto.

Este complemento también administra escenarios más avanzados que puede probar. Por ejemplo, puede probar el comportamiento cuando se ven mensajes de correo electrónico utilizando los botones Elemento siguiente y Elemento anterior. También puede probar el comportamiento cuando se descarga el complemento, se abren varios mensajes de correo electrónico y, a continuación, se vuelve a cargar el complemento.

Pasos siguientes

Puede obtener más información sobre cómo crear paneles de tareas personalizados en estos temas:

Crear un panel de tareas personalizado en un complemento de una aplicación diferente Para obtener más información sobre las aplicaciones que admiten paneles de tareas personalizados, vea Información general sobre los paneles de tareas personalizados.
Automatizar una aplicación de Microsoft Office utilizando un panel de tareas personalizado. Para obtener más información, vea Tutorial: Automatizar una aplicación desde un panel de tareas personalizado.
Crear un botón de cinta de opciones en Excel que se pueda utilizar para ocultar o mostrar un panel de tareas personalizado. Para obtener más información, vea Tutorial: Sincronizar un panel de tareas personalizado con un botón de la cinta de opciones.