Demonstra Passo a passo: Adicionar controles a um documento em tempo de execução em um suplemento VSTO

Você pode adicionar controles a qualquer documento aberto do Microsoft Office Word usando um suplemento VSTO. Este passo a passo demonstra como usar a faixa de opções para permitir que os usuários adicionem um ou um a um Button RichTextContentControl documento.

Aplica-se a: As informações neste tópico se aplicam a projetos de suplemento VSTO para Word 2010. Para obter mais informações, confira Features Available by Office Application and Project Type (Funcionalidades disponibilizadas pelo aplicativo do Office e pelo tipo de projeto).

Este passo a passo ilustra as seguintes tarefas:

• Criando um novo projeto de suplemento VSTO do Word.

• Fornecendo uma interface do usuário (UI) para adicionar controles ao documento.

• Adicionando controles ao documento em tempo de execução.

• Removendo controles do documento.

  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.

Pré-requisitos

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

• Uma edição do Visual Studio que inclui o Microsoft Office Developer Tools. Para obter mais informações, consulte Configurar um computador para desenvolver soluções do Office.

• Word 2013 ou Word 2010 .

Criar um novo projeto de suplemento do Word

Comece criando um projeto de suplemento VSTO do Word.

Para criar um novo projeto de suplemento VSTO do Word

1. Crie um projeto de suplemento VSTO para o Word com o nome WordDynamicControls. Para obter mais informações, consulte Como: Criar projetos do Office no Visual Studio.

2. Adicione uma referência ao assembly Microsoft.Office.Tools.Word.v4.0.Utilities.dll Essa referência é necessária para adicionar programaticamente um controle do Windows Forms ao documento posteriormente nesta explicação passo a passo.

Fornecer uma interface do usuário para adicionar controles a um documento

Adicione uma guia personalizada à Faixa de Opções no Word. Os usuários podem marcar caixas de seleção na guia para adicionar controles a um documento.

Para fornecer uma interface do usuário para adicionar controles a um documento

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 Minha Faixa de Opções e clique em Adicionar.

   O arquivo MyRibbon.cs ou MyRibbon.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 no grupo group1 .

5. Na janela Propriedades, altere a propriedade Label de group1 para Adicionar controles.

6. Na guia Controles da Faixa de Opções do Office da Caixa de Ferramentas, arraste um controle CheckBox para group1.

7. Clique em CheckBox1 para selecioná-lo.

8. Na janela Propriedades, altere as seguintes propriedades.

   Propriedade	Valor
   Nome	addButtonCheckBox
   Rótulo	Botão Adicionar

9. Adicione uma segunda caixa de seleção ao group1 e altere as propriedades a seguir.

   Propriedade	Valor
   Nome	addRichTextCheckBox
   Rótulo	Adicionar controle de rich text

10. No Designer da Faixa de Opções, clique duas vezes em Adicionar Botão.

    O Click manipulador de eventos da caixa de seleção Adicionar botão é aberto no Editor de códigos .

11. Retorne ao Designer da Faixa de Opções e clique duas vezes em Adicionar Controle Rich Text.

    O Click manipulador de eventos da caixa de seleção Adicionar controle de rich text é aberto no Editor de códigos.

    Mais adiante nesta explicação passo a passo, você adicionará código a esses manipuladores de eventos para adicionar e remover controles no documento ativo.

Adicionar e remover controles no documento ativo

No código do suplemento VSTO, você deve converter o documento ativo em um item de host antes de adicionar um Documentcontrole. Nas soluções do Office, os controles gerenciados podem ser adicionados somente aos itens do host, que atuam como contêineres para os controles. Em projetos de suplemento VSTO, os itens de host podem ser criados em tempo de execução usando o GetVstoObject método.

Adicione métodos à ThisAddIn classe que podem ser chamados para adicionar ou remover um Button ou RichTextContentControl no documento ativo. Mais adiante nesta explicação passo a passo, você chamará esses métodos dos Click manipuladores de eventos das caixas de seleção na Faixa de Opções.

Para adicionar e remover controles no documento ativo

1. No Gerenciador de Soluções, clique duas vezes em ThisAddIn.cs ou ThisAddIn.vb para abrir o arquivo no Editor de Códigos.

2. Adicione o código a seguir à classe ThisAddIn . Esse código declara Button e RichTextContentControl objetos que representam os controles que serão adicionados ao documento.

   C#

   private Microsoft.Office.Tools.Word.Controls.Button button = null;
   private RichTextContentControl richTextControl = null;
   

   VB

   Private button As Microsoft.Office.Tools.Word.Controls.Button = Nothing
   Private richTextControl As RichTextContentControl = Nothing
   

3. Adicione o método a seguir à classe ThisAddIn. Quando o usuário clica na caixa de seleção Adicionar Botão na Faixa de Opções, esse método adiciona um Button à seleção atual no documento se a caixa de seleção estiver marcada ou remove a se a Button caixa de seleção estiver desmarcada.

   C#

   internal void ToggleButtonOnDocument()
   {
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
   
       string name = "MyButton";
   
       if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
       {
           Word.Selection selection = this.Application.Selection;
           if (selection != null && selection.Range != null)
           {
               button = vstoDocument.Controls.AddButton(
                   selection.Range, 100, 30, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

   VB

   Friend Sub ToggleButtonOnDocument()
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       Dim name As String = "MyButton"
   
       If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
           Dim selection = Me.Application.Selection
           If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
               button = vstoDocument.Controls.AddButton( _
                   selection.Range, 100, 30, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

4. Adicione o método a seguir à classe ThisAddIn. Quando o usuário clica na caixa de seleção Adicionar Controle de Rich Text na Faixa de Opções, esse método adiciona um RichTextContentControl à seleção atual no documento se a caixa de seleção estiver marcada ou remove a se a RichTextContentControl caixa de seleção estiver desmarcada.

   C#

   internal void ToggleRichTextControlOnDocument()
   {
   
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
   
       string name = "MyRichTextBoxControl";
   
       if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
       {
           Word.Selection selection = this.Application.Selection;
           if (selection != null && selection.Range != null)
           {
               richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                   selection.Range, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

   VB

   Friend Sub ToggleRichTextControlOnDocument()
   
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       Dim name As String = "MyRichTextBoxControl"
   
       If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
           Dim selection = Me.Application.Selection
           If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
               richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                       selection.Range, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

Remova o controle Button quando o documento for salvo

Os controles do Windows Forms não são persistentes quando o documento é salvo e, em seguida, fechado. No entanto, um wrapper ActiveX para cada controle permanece no documento, e a borda desse wrapper pode ser vista pelos usuários finais quando o documento é reaberto. Há várias maneiras de limpar controles do Windows Forms criados dinamicamente em suplementos VSTO. Neste passo a passo, você remove programaticamente o controle quando o Button documento é salvo.

Para remover o controle Button quando o documento é salvo

1. No arquivo de código ThisAddIn.cs ou ThisAddIn.vb , adicione o seguinte método à ThisAddIn classe. Esse método é um manipulador de eventos para o DocumentBeforeSave evento. Se o documento salvo tiver um item de Document host associado a ele, o manipulador de eventos obterá o item de host e removerá o Button controle, se ele existir.

   C#

   private void Application_DocumentBeforeSave(Word.Document Doc, 
       ref bool SaveAsUI, ref bool Cancel)
   {
       bool isExtended = Globals.Factory.HasVstoObject(Doc);
   
   
       if (isExtended)
       {
   
           Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);
   
           if (vstoDocument.Controls.Contains(button))
           {
               vstoDocument.Controls.Remove(button);
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
           }
       }
   }
   

   VB

   Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
       ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
   
       Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)
   
   
       If isExtended Then
           Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)
   
   
           If vstoDocument.Controls.Contains(button) Then
               vstoDocument.Controls.Remove(button)
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
           End If
       End If
   End Sub
   

2. Em C#, adicione o seguinte código ao manipulador de ThisAddIn_Startup eventos. Esse código é necessário em C# para conectar o manipulador de eventos com o Application_DocumentBeforeSave DocumentBeforeSave evento.

   this.Application.DocumentBeforeSave += 
       new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
       Application_DocumentBeforeSave);
   

Adicionar e remover controles quando o usuário clica nas caixas de seleção na faixa de opções

Finalmente, modifique os Click manipuladores de eventos das caixas de seleção adicionadas à faixa de opções para adicionar ou remover controles no documento.

Para adicionar ou remover controles quando o usuário clica nas caixas de seleção na faixa de opções

1. No arquivo de código MyRibbon.cs ou MyRibbon.vb, substitua os manipuladores de eventos e gerados addButtonCheckBox_Click addRichTextCheckBox_Click pelo código a seguir. Esse código redefine esses manipuladores de eventos para chamar os ToggleButtonOnDocument métodos e ToggleRichTextControlOnDocument que você adicionou à classe anteriormente nesta explicação passo a ThisAddIn passo.

   C#

   private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
   {
       Globals.ThisAddIn.ToggleButtonOnDocument();
   }
   
   private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
   {
       Globals.ThisAddIn.ToggleRichTextControlOnDocument();
   }
   

   VB

   Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _
       ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click
       Globals.ThisAddIn.ToggleButtonOnDocument()
   End Sub
   
   Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _
       ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click
       Globals.ThisAddIn.ToggleRichTextControlOnDocument()
   End Sub
   

Testar a solução

Adicione controles a um documento selecionando-os na guia personalizada da Faixa de Opções. Quando você salva o documento, o Button controle é removido.

Para testar a solução.

1. Pressione F5 para executar o projeto.

2. No documento ativo, pressione Enter várias vezes para adicionar novos parágrafos vazios ao documento.

3. Selecione o primeiro parágrafo.

4. Clique na guia Suplementos .

5. No grupo Adicionar Controles, clique em Adicionar Botão.

   Um botão aparece no primeiro parágrafo.

6. Selecione o último parágrafo.

7. No grupo Adicionar Controles, clique em Adicionar Controle Rich Text.

   Um controle de conteúdo rich text é adicionado ao último parágrafo.

8. Salve o documento.

   O botão é removido do documento.

Próximas etapas

Você pode saber mais sobre controles em Suplementos VSTO a partir destes tópicos:

• Para obter um exemplo que demonstra como adicionar muitos outros tipos de controles a um documento em tempo de execução e recriar os controles quando o documento é reaberto, consulte o Exemplo de controles dinâmicos de suplemento do Word em Exemplos de desenvolvimento e instruções passo a passo do Office.

• Para obter uma explicação passo a passo que demonstra como adicionar controles a uma planilha usando um suplemento VSTO para Excel, consulte Demonstra Passo a passo: Adicionar controles a uma planilha em tempo de execução no projeto de suplemento VSTO.

Conteúdo relacionado

• Soluções do Word
• Adicionar controles a documentos do Office em tempo de execução
• Persistir controles dinâmicos em documentos do Office
• Como: Adicionar controles do Windows Forms a documentos do Office
• Como: Adicionar controles de conteúdo a documentos do Word
• Estender documentos do Word e pastas de trabalho do Excel em suplementos do VSTO em tempo de execução