Construindo um Task Pane Customizado em VSTO

Este post foi originalmente publicado em http://officevbavsto.blogspot.com/2013/03/vsto-construindo-um-task-pane.html

Neste artigo eu vou ensiná-lo a criar um Task Pane Customizado. Mas, o que é um Task Pane?

O que é um Task Pane (Painel de Tarefas)?

A função dos Task Panes nos aplicativos do Office é mostrar informação adicional ou oferecer aos usuários funcionalidade adicional. Um exemplo de um Task Pane no Microsoft Word é o Task Pane Pesquisar ou Dicionário de Sinônimos (Figura 1). Se você clicar na Guia Revisão no Microsoft Word e clicar no ícone Dicionário de Sinônimos, um Task Pane é aberto ao lado[1].

Task Panes customizados lhe fornecem um meio de criar seu próprio Task Pane e providenciar aos usuários uma interface familiar para acessar os recursos da sua solução. Por exemplo, a interface pode conter controles que executem código para modificar documentos ou mostrar dados de uma fonte de dados (Ex.: ODBC Data Source, SQL Server, Oracle e etc.) [2].

Criando seu primeiro Task Pane Customizado

Para criar um Task Pane, você precisa criar um Projeto do tipo Office Add-in. Criar um Task Pane é o mesmo que criar um controle Windows Forms comum [1].

Abra o Visual Studio 2010 e execute os seguintes passos para criar um Projeto do Tipo Office Add-in:

1. File – New Project;
2. Na janela “New Project”, selecione o template “Word 2010 Add-in” através do seguinte caminho “Visual Basic” – Office – 2010 (Figura 3);
3. No campo Name, digite “WordTaskPane”, clique em OK;
   Na Solution Explorer, clique com o botão direito sobre o nome do Projeto e escolha Add – User Control;
4. Digite MyTaskPane na caixa de texto Name;
5. Clique em Add;

A caixa de diálogo fechara, e o arquivo MyTaskPane.vb aparecerá na Solution Explorer.

Adicionando controles ao Task Pane

Agora, vamos adicionar duas Caixas de Texto e um Botão ao nosso Task Pane. Para adicionar os controles:

1. Abre o Design View do User Control “MyTaskPane.vb” através de duplo clique sobre este arquivo ou clique com o botão direito sobre “MyTaskPane.vb” – View Designer;
2. Exiba a Janela de Ferramentas (View – Toobox);
3. Na Janela de Ferramentas, expanda o nó “Commom Controls”;
4. Arraste dois controles TextBox para o nosso Task Pane;
5. Arraste dois controles Label para o nosso Task Pane;
6. Arraste um controle Button para o nosso Task Pane;
7. Configure as propriedades dos controles conforme Figura 5 (abaixo).

Se você pressionar F5 (Debug – Start Debugging) para iniciar o Microsoft Word e executar o Add-in, nada de especial acontece. O Task Pane que você criou não aparece no Microsoft Word porque está faltando o código que dirá ao Add-in e ao Microsoft Word quando exibir o Task Pane. Veremos isso a seguir.

Exibindo o Task Pane Customizado no Microsoft Word

Com o objetivo de simplificar, nós mostraremos o Task Pane assim que o Microsoft Word iniciar. Para isso, precisamos adicionar algumas linhas de código no arquivo ThisAddIn.vb.

Para ser mais específico, seu código deverá estar dentro do método ThisAddIn_Startup dentro da classe ThisAddIn no arquivo ThisAddIn.vb.

Para adicionar código ao seu Task Pane:

Na Solution Explorer, localize o arquivo ThisAddIn.vb;

Adicione a seguinte linha de código ao método ThisAddIn_Startup:

Public Class ThisAddIn 
	Private  Sub ThisAddIn_Startup() Handles Me.Startup 
		Dim myCustomTaskPane As Microsoft.Office.Tools.CustomTaskPane 
		myCustomTaskPane = Me.CustomTaskPanes.Add(New MyTaskPane(), "My Task Pane") 
		myCustomTaskPane.Visible = True 
	End Sub 
	Private Sub ThisAddIn_Shutdown() Handles Me.Shutdown 
	End Sub 
End Class

Depois que você criar um User Control que contém a interface de um Task Pane Customizado, você tem que instanciar um CustomTaskPane (Dim myCustomTaskPane As Microsoft.Office.Tools.CustomTaskPane). Para fazer isto, você passar o User Control à coleção CustomTaskPaneCollection em seu Add-in através da chamada ao método Add (myCustomTaskPane = Me.CustomTaskPanes.Add(New MyTaskPane(), "My Task Pane")). Esta coleção é exposta como um campo CustomTaskPanes na classe ThisAddIn [2] (Me.CustomTaskPanes).

Outra coisa importante é que apenas adicionando o User Control à coleção de Task Panes Customizados - Me.CustomTaskPanes.Add(New MyTaskPane(), "My Task Pane") = não faz com que seu Task Pane Customizado seja exibido quando o Add-in iniciar, então você atribui o valor True à propriedade Visible [1].

Adicionando funcionalidade ao Task Pane Customizado

Apesar de o Task Pane aparecer no Microsoft Word, ele precisa de mais funcionalidade para ser mais útil. Agora, você pode digitar seu nome na caixa de Texto Nome no seu Task Pane Customizado e clicar em Inserir. O que acontece? Nada!

Para adicionar código que permita o usuário inserir o nome que ele digita no seu Task Pane Customizado, siga os passos a seguir:

• Exiba o arquivo “MyTaskPane.vb” no modo Design: duplo clique sobre o arquivo “MyTaskPane.vb” ou clique com o botão direito – View Designer (Shift – F7);
• Dê um duplo clique sobre o controle Botão “Inserir”;
• Adicione o código a seguir no método Click do botão “Inserir”:

Public Class MyTaskPane
	Private Sub btnInserir_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnInserir.Click
		Dim range As Word.Range
		range = Globals.ThisAddIn.Application.ActiveDocument.Range(Start:=0, End:=0)
		range.Text = txtNome.Text & " " & txtSobreNome.Text
	End Sub
End Class

Na segunda linha do método btnInserir_Click você está basicamente navegando pela hierarquia de objetos do Microsoft Word através começando da classe Globals e então até o Add-in - ThisAddIn -, depois para o aplicativo Word (Application), para o documento ativo (ActiveDocument) que está carregado no Microsoft Word e finalmente ao objeto Range [1].

Se você quer automatizar a aplicação através do User Control, você pode acessar diretamente o modelo de objeto do Microsoft Word usando Globals.ThisAddIn.Application no seu código. A Classe Stática Globals provê o acesso ao Objeto ThisAddIn. O campo Application deste objeto é o ponto de entrada para o modelo de objeto da aplicação (Word, Excel e etc.) [2].
Note que o código é muito semelhante ao VBA. Por exemplo, no caso do Microsoft Excel, você poderia escreve um valor na célula através do seguinte código:

Globals.ThisAddIn.Application.ThisWorkbook.Worksheets(1).Cells(1,1).Value = "Hello World"

Conclusão

Neste artigo vimos como adicionar Task Panes Customizados e exibi-los em sua aplicação do Microsoft Office e como inserir controles no seu Task Pane Customizado e adicionar funcionalidades aos mesmos.

Recomendo você tentar o mesmo código em um Template Project “Excel Add-in 2010” e inclusive tentar o código que descrevo na Tabela 3 no tópico anterior.

Créditos

Photo by Gabby K from Pexels

Referência Bibliográfica

• Bill Sempf and Peter Jausovec. VSTO for Dummies, 1st Edition. Indianopolis, Indiana (USA). Wiley Publishing Inc. 2011;