Passo a passo: Exibir painéis de tarefas personalizados com mensagens de email no Outlook

  • Artigo

Este passo a passo demonstra como exibir uma instância exclusiva de um painel de tarefas personalizado com cada mensagem de email criada ou aberta. Os usuários podem exibir ou ocultar o painel de tarefas personalizado usando um botão na Faixa de Opções de cada mensagem de email.

Aplica-se a: As informações neste tópico se aplicam a projetos de suplemento VSTO para Outlook. Para obter mais informações, consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

Para exibir um painel de tarefas personalizado com várias janelas do Explorer ou do Inspetor, você deve criar uma instância do painel de tarefas personalizado para cada janela aberta. Para obter mais informações sobre o comportamento de painéis de tarefas personalizados em janelas do Outlook, consulte Painéis de tarefas personalizados.

Observação

Este passo a passo apresenta o código do suplemento VSTO em pequenas seções para facilitar a discussão da lógica por trás do código.

Este passo a passo ilustra as seguintes tarefas:

  • Criando a interface do usuário (UI) do painel de tarefas personalizado.

  • Criando uma interface do usuário personalizada da Faixa de Opções.

  • Exibindo a interface do usuário personalizada da Faixa de Opções com mensagens de email.

  • Criando uma classe para gerenciar janelas do Inspetor e painéis de tarefas personalizados.

  • Inicializando e limpando recursos usados pelo suplemento VSTO.

  • Sincronizar o botão de alternância da Faixa de Opções com o painel de tarefas personalizado.

Observação

Seu computador pode mostrar diferentes nomes ou locais para alguns dos elementos de interface do usuário do Visual Studio nas instruções a seguir. A edição do Visual Studio que você possui e as configurações que você usa determinam esses elementos. Para obter mais informações, confira Personalizar o IDE do Visual Studio.

Pré-requisitos

Você precisará dos seguintes componentes para concluir este passo a passo:

Criar o projeto

Os painéis de tarefas personalizados são implementados em Suplementos VSTO. Comece criando um projeto de suplemento VSTO para Outlook.

Criar um novo projeto

  1. Crie um projeto de suplemento do Outlook com o nome OutlookMailItemTaskPane. Use o modelo de projeto Suplemento do Outlook. Para obter mais informações, consulte Como: Criar projetos do Office no Visual Studio.

    O Visual Studio abre o arquivo de código ThisAddIn.cs ou ThisAddIn.vb e adiciona o projeto OutlookMailItemTaskPane ao Gerenciador de Soluções.

Criar a interface do usuário do painel de tarefas personalizado

Não há nenhum designer visual para painéis de tarefas personalizados, mas você pode criar um controle de usuário com a interface do usuário desejada. O painel de tarefas personalizado neste suplemento VSTO tem uma interface do usuário simples que contém um TextBox controle. Mais adiante neste passo a passo, você adicionará o controle de usuário ao painel de tarefas personalizado.

Para projetar a interface do usuário do painel de tarefas personalizado

  1. No Gerenciador de Soluções, clique no projeto OutlookMailItemTaskPane .

  2. No menu Project , clique em Adicionar controle de usuário .

  3. Na caixa de diálogo Adicionar Novo Item, altere o nome do controle de usuário para TaskPaneControl e clique em Adicionar.

    O controle de usuário será aberto no designer.

  4. Na guia Controles comuns da caixa de ferramentas, arraste um controle TextBox para o controle de usuário.

Projetar a interface do usuário da faixa de opções

Um dos objetivos deste Suplemento VSTO é oferecer aos usuários uma maneira de ocultar ou exibir o painel de tarefas personalizado da Faixa de Opções de cada mensagem de email. Para fornecer a interface do usuário, crie uma interface do usuário personalizada da Faixa de Opções que exiba um botão de alternância no qual os usuários podem clicar para exibir ou ocultar o painel de tarefas personalizado.

Para criar uma interface do usuário personalizada da Faixa de Opções

  1. No menu Projeto , clique em Adicionar Novo Item.

  2. Na caixa de diálogo Adicionar Novo Item, selecione Faixa de Opções (Visual Designer).

  3. Altere o nome da nova Faixa de Opções para ManageTaskPaneRibbon e clique em Adicionar.

    O arquivo ManageTaskPaneRibbon.cs ou ManageTaskPaneRibbon.vb é aberto no Designer da Faixa de Opções e exibe uma guia e um grupo padrão.

  4. No Designer da Faixa de Opções, clique em group1.

  5. Na janela Propriedades, defina a propriedade Label como Gerenciador do Painel de Tarefas.

  6. Na guia Controles da Faixa de Opções do Office da Caixa de Ferramentas, arraste um controle ToggleButton para o grupo Gerenciador do Painel de Tarefas.

  7. Clique em toggleButton1.

  8. Na janela Propriedades, defina a propriedade Label como Mostrar Painel de Tarefas.

Exibir a interface de usuário personalizada da Faixa de Opções com mensagens de email

O painel de tarefas personalizado que você cria nesta explicação passo a passo foi projetado para aparecer somente com as janelas do Inspetor que contêm mensagens de email. Portanto, defina as propriedades para exibir sua interface do usuário personalizada da Faixa de Opções somente com essas janelas.

Para exibir a interface do usuário personalizada da Faixa de Opções com mensagens de email

  1. No Designer da Faixa de Opções, clique na Faixa de Opções ManageTaskPaneRibbon .

  2. Na janela Propriedades, clique na lista suspensa ao lado de RibbonType e selecione Microsoft.Outlook.Mail.Compose e Microsoft.Outlook.Mail.Read.

Criar uma classe para gerenciar janelas do inspetor e painéis de tarefas personalizados

Há vários casos em que o Suplemento VSTO deve identificar qual painel de tarefas personalizado está associado a uma mensagem de email específica. Esses casos incluem o seguinte:

  • Quando o usuário fecha uma mensagem de email. Nesse caso, o Suplemento VSTO deve remover o painel de tarefas personalizado correspondente para garantir que os recursos usados pelo Suplemento VSTO sejam limpos corretamente.

  • Quando o usuário fecha o painel de tarefas personalizado. Nesse caso, o suplemento VSTO deve atualizar o estado do botão de alternância na faixa de opções da mensagem de email.

  • Quando o usuário clica no botão de alternância na faixa de opções. Nesse caso, o suplemento VSTO deve ocultar ou exibir o painel de tarefas correspondente.

    Para habilitar o Suplemento VSTO para controlar qual painel de tarefas personalizado está associado a cada mensagem de email aberta, crie uma classe personalizada que encapsula pares de Inspector e CustomTaskPane objetos. Essa classe cria um novo objeto de painel de tarefas personalizado para cada mensagem de email e exclui o painel de tarefas personalizado quando a mensagem de email correspondente é fechada.

Para criar uma classe para gerenciar janelas do inspetor e painéis de tarefas personalizados

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo ThisAddIn.cs ou ThisAddIn.vb e clique em Exibir Código.

  2. Adicione as seguintes instruções à parte superior do arquivo.

    using Microsoft.Office.Tools;

  3. Adicione o seguinte código ao arquivo ThisAddIn.cs ou ThisAddIn.vb , fora da ThisAddIn classe (para Visual C#, adicione esse código dentro do OutlookMailItemTaskPane namespace). A InspectorWrapper classe gerencia um par de Inspector e CustomTaskPane objetos. Você concluirá a definição dessa classe nas etapas a seguir.

    public class InspectorWrapper
{
    private Outlook.Inspector inspector;
    private CustomTaskPane taskPane;

  4. Adicione o seguinte construtor após o código que você adicionou na etapa anterior. Este construtor cria e inicializa um novo painel de tarefas personalizado que está associado ao Inspector objeto que é passado. Em C#, o construtor também anexa manipuladores de eventos ao evento do Inspector objeto e ao Close VisibleChanged evento do CustomTaskPane objeto.

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

  5. Adicione o seguinte método após o código que você adicionou na etapa anterior. Esse método é um manipulador de eventos para o VisibleChanged evento do CustomTaskPane objeto contido na InspectorWrapper classe. Esse código atualiza o estado do botão de alternância sempre que o usuário abre ou fecha o painel de tarefas personalizado.

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

  6. Adicione o seguinte método após o código que você adicionou na etapa anterior. Esse método é um manipulador de eventos para o Close evento do objeto que contém a Inspector mensagem de email atual. O manipulador de eventos libera recursos quando a mensagem de email é fechada. O manipulador de eventos também remove o painel de tarefas personalizado atual da CustomTaskPanes coleção. Isso ajuda a evitar várias instâncias do painel de tarefas personalizado quando a próxima mensagem de email é aberta.

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

  7. Adicione o seguinte código após o código que você adicionou na etapa anterior. Mais adiante nesta explicação passo a passo, você chamará essa propriedade de um método na interface do usuário personalizada da Faixa de Opções para exibir ou ocultar o painel de tarefas personalizado.

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

Inicializar e limpar recursos usados pelo suplemento

Adicione código à ThisAddIn classe para inicializar o suplemento VSTO quando ele é carregado e para limpar os recursos usados pelo suplemento VSTO quando ele é descarregado. Você inicializa o suplemento VSTO configurando um manipulador de eventos para o NewInspector evento e passando todas as mensagens de email existentes para esse manipulador de eventos. Quando o suplemento VSTO for descarregado, desanexe o manipulador de eventos e limpe os objetos usados pelo suplemento VSTO.

Para inicializar e limpar recursos usados pelo suplemento VSTO

  1. No arquivo ThisAddIn.cs ou ThisAddIn.vb, localize a ThisAddIn definição da classe.

  2. Adicione as seguintes declarações à ThisAddIn classe:

    • O inspectorWrappersValue campo contém todos os Inspector objetos e InspectorWrapper que são gerenciados pelo suplemento VSTO.

    • O inspectors campo mantém uma referência à coleção de janelas do Inspetor na instância atual do Outlook. Essa referência impede que o coletor de lixo libere a memória que contém o manipulador de eventos para o NewInspector evento, que você declarará na próxima etapa.

      private Dictionary<Outlook.Inspector, InspectorWrapper> inspectorWrappersValue =
    new Dictionary<Outlook.Inspector, InspectorWrapper>();
private Outlook.Inspectors inspectors;

  3. Substitua o método ThisAddIn_Startup pelo seguinte código. Esse código anexa um manipulador de eventos ao evento e passa cada objeto existente Inspector para o manipulador de NewInspector eventos. Se o usuário carregar o suplemento VSTO depois que o Outlook já estiver em execução, o suplemento VSTO usará essas informações para criar painéis de tarefas personalizados para todas as mensagens de email que já estão abertas.

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

  4. Substitua o método ThisAddIn_ShutDown pelo seguinte código. Esse código desanexa o NewInspector manipulador de eventos e limpa objetos usados pelo suplemento VSTO.

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

  5. Adicione o seguinte NewInspector manipulador de eventos à ThisAddIn classe. Se um novo contiver uma mensagem de email, o método criará uma instância de um novo Inspector InspectorWrapper objeto para gerenciar a relação entre a mensagem de email e o painel de tarefas correspondente.

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

  6. Adicione a seguinte propriedade à ThisAddIn classe. Essa propriedade expõe o campo privado inspectorWrappersValue ao código fora da ThisAddIn classe.

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

Ponto de verificação

Crie seu projeto para garantir que ele seja compilado sem erros.

Para criar o projeto

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto OutlookMailItemTaskPane e clique em Compilar. Verifique se o projeto é compilado sem erros.

Sincronizar o botão de alternância da Faixa de Opções com o painel de tarefas personalizado

O botão de alternância parecerá ser pressionado quando o painel de tarefas estiver visível e parecerá não estar pressionado quando o painel de tarefas estiver oculto. Para sincronizar o estado do botão com o painel de tarefas personalizado, modifique o Click manipulador de eventos do botão de alternância.

Para sincronizar o painel de tarefas personalizado com o botão de alternância

  1. No Designer da Faixa de Opções, clique duas vezes no botão de alternância Mostrar Painel de Tarefas.

    O Visual Studio gera automaticamente um manipulador de eventos chamado toggleButton1_Click, que manipula o Click evento do botão de alternância. O Visual Studio também abre o arquivo ManageTaskPaneRibbon.cs ou ManageTaskPaneRibbon.vb no Editor de Códigos.

  2. Adicione as instruções a seguir à parte superior do arquivo ManageTaskPaneRibbon.cs ou ManageTaskPaneRibbon.vb arquivo.

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

  3. Substitua o toggleButton1_Click manipulador de eventos pelo código a seguir. Quando o usuário clica no botão de alternância, esse método oculta ou exibe o painel de tarefas personalizado associado à janela atual do Inspetor.

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

Testar o projeto

Quando você começa a depurar o projeto, o Outlook é aberto e o suplemento VSTO é carregado. O suplemento VSTO exibe uma instância exclusiva do painel de tarefas personalizado com cada mensagem de email aberta. Crie várias novas mensagens de email para testar o código.

Para testar o suplemento VSTO

  1. Pressione F5.

  2. No Outlook, clique em Novo para criar uma nova mensagem de email.

  3. Na faixa de opções da mensagem de email, clique na guia Suplementos e clique no botão Mostrar Painel de Tarefas.

    Verifique se um painel de tarefas com o título Meu painel de tarefas é exibido com a mensagem de email.

  4. No painel de tarefas, digite Primeiro painel de tarefas na caixa de texto.

  5. Feche o painel de tarefas.

    Verifique se o estado do botão Mostrar Painel de Tarefas é alterado para que ele não seja mais pressionado.

  6. Clique no botão Mostrar Painel de Tarefas novamente.

    Verifique se o painel de tarefas é aberto e se a caixa de texto ainda contém a cadeia de caracteres Primeiro painel de tarefas.

  7. No Outlook, clique em Novo para criar uma segunda mensagem de email.

  8. Na faixa de opções da mensagem de email, clique na guia Suplementos e clique no botão Mostrar Painel de Tarefas.

    Verifique se um painel de tarefas com o título Meu painel de tarefas é exibido com a mensagem de email e se a caixa de texto neste painel de tarefas está vazia.

  9. No painel de tarefas, digite Segundo painel de tarefas na caixa de texto.

  10. Altere o foco para a primeira mensagem de email.

    Verifique se o painel de tarefas associado a esta mensagem de email ainda exibe Primeiro painel de tarefas na caixa de texto.

    Este suplemento VSTO também lida com cenários mais avançados que você pode tentar. Por exemplo, você pode testar o comportamento ao exibir emails usando os botões Próximo Item e Item Anterior . Você também pode testar o comportamento ao descarregar o suplemento VSTO, abrir várias mensagens de email e, em seguida, recarregar o suplemento VSTO.

Próximas etapas

Você pode saber mais sobre como criar painéis de tarefas personalizados a partir destes tópicos:

Conteúdo relacionado