Procedura dettagliata: aggiunta di controlli a un documento in fase di esecuzione in un componente aggiuntivo a livello di applicazione

È possibile aggiungere i controlli a qualsiasi documento di Microsoft Office Word aperto tramite un componente aggiuntivo a livello di applicazione. In questa procedura dettagliata viene illustrato come utilizzare la barra multifunzione per consentire agli utenti l'aggiunta di un oggetto Button o RichTextContentControl a un documento.

Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di applicazione per Word 2007 e Word 2010. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

In questa procedura dettagliata vengono illustrate le seguenti attività:

• Creazione di un nuovo progetto componente aggiuntivo per Word.

• Creazione di un'interfaccia utente per l'aggiunta di controlli al documento.

• Aggiunta di controlli al documento in fase di esecuzione.

• Rimozione di controlli dal documento.

Prerequisiti

Per completare la procedura dettagliata, è necessario disporre dei componenti seguenti:

-

Una versione di Visual Studio 2010 che include gli strumenti per sviluppatori di Microsoft Office. Per ulteriori informazioni, vedere [Configurazione di un computer per sviluppare soluzioni Office](bb398242\(v=vs.100\).md).

• Word 2007 o Word 2010.

Creazione di un nuovo progetto componente aggiuntivo per Word

Creare innanzitutto un progetto relativo al componente aggiuntivo per Word.

Per creare un nuovo progetto componente aggiuntivo per Word

1. Creare un progetto relativo al componente aggiuntivo a livello di applicazione per Word denominato WordDynamicControls. Per ulteriori informazioni, vedere Procedura: creare progetti di Office in Visual Studio.

2. Se il progetto è destinato a .NET Framework 4, aggiungere un riferimento all'assembly Microsoft.Office.Tools.Word.v4.0.Utilities.dll. Tale riferimento è necessario per aggiungere a livello di codice un controllo Windows Form al documento più avanti nella procedura dettagliata.

Creazione di un'interfaccia utente per l'aggiunta di controlli a un documento

Aggiungere una scheda personalizzata alla barra multifunzione in Word. Gli utenti possono selezionare caselle di controllo nella scheda per aggiungere i controlli a un documento.

Per creare un'interfaccia utente per l'aggiunta di controlli a un documento

1. Scegliere Aggiungi nuovo elemento dal menu Progetto.

2. Nella finestra di dialogo Aggiungi nuovo elemento selezionare Barra multifunzione (finestra di progettazione visiva).

3. Modificare il nome dell'elemento in MyRibbon, quindi fare clic su Aggiungi.

   Nella finestra di progettazione della barra multifunzione viene aperto un file MyRibbon.cs o MyRibbon.vb, che visualizza una scheda e un gruppo predefiniti.

4. Scegliere group1 nella finestra di progettazione della barra multifunzione.

5. Nella finestra Proprietà modificare la proprietà Label per group1 in Aggiungi controlli.

6. Dalla scheda Controlli barra multifunzione di Office della Casella degli strumenti, trascinare un controllo CheckBox in group1.

7. Fare clic su CheckBox1 per selezionarlo.

8. Nella finestra Proprietà modificare le proprietà riportate di seguito.

   Proprietà	Valore
   Nome	addButtonCheckBox
   Etichetta	Pulsante Aggiungi

9. Aggiungere una seconda casella di controllo a group1 e modificare le seguenti proprietà.

   Proprietà	Valore
   Nome	addRichTextCheckBox
   Etichetta	Aggiungi controllo RTF

10. Nella finestra di progettazione della barra multifunzione, fare doppio clic su Pulsante Aggiungi.

    Il gestore eventi Click della casella di controllo Pulsante Aggiungi viene aperto nell'editor del codice.

11. Tornare alla finestra di progettazione della barra multifunzione e fare doppio clic su Aggiungi controllo RTF.

    Il gestore eventi Click della casella di controllo Aggiungi controllo RTF viene aperto nell'editor del codice.

Più avanti nella procedura dettagliata verrà aggiunto il codice a questi gestori eventi per aggiungere e rimuovere controlli sul documento attivo.

Aggiunta e rimozione di controlli sul documento attivo

Nel codice del componente aggiuntivo, è necessario convertire il documento attivo in un elemento host Microsoft.Office.Tools.Word.Document prima che sia possibile aggiungere un controllo. Nelle soluzioni Visual Studio Tools per Office, è possibile aggiungere i controlli gestiti solo a elementi host che sono utilizzati come contenitori per i controlli. Nei progetti componente aggiuntivo a livello di applicazione, gli elementi host possono essere creati in fase di esecuzione mediante il metodo GetVstoObject.

Aggiungere metodi alla classe ThisAddIn che può essere chiamata per aggiungere o rimuovere un oggetto Button o RichTextContentControl nel documento attivo. Più avanti nella procedura dettagliata questi metodi verranno chiamati dai gestori eventi Click delle caselle di controllo sulla barra multifunzione.

Per aggiungere e rimuovere controlli sul documento attivo

1. In Esplora soluzioni, fare doppio clic su ThisAddIn.cs o su ThisAddIn.vb per aprire il file nell'editor di codice.

2. Aggiungere il codice seguente alla classe ThisAddIn. Questo codice dichiara gli oggetti Button e RichTextContentControl che rappresentano i controlli che verranno aggiunti al documento.

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

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

3. Aggiungere il seguente metodo alla classe ThisAddIn. Quando l'utente seleziona la casella di controllo Pulsante Aggiungi sulla barra multifunzione, questo metodo consente di aggiungere un oggetto Button alla selezione corrente nel documento se viene selezionata la casella di controllo o di rimuovere l'oggetto Button se la casella di controllo viene deselezionata.

   Friend Sub ToggleButtonOnDocument()
       ' Use the following line of code in projects that target the .NET Framework 4.
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       ' In projects that target the .NET Framework 3.5, use the following line of code.
       ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
   
       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
   

   internal void ToggleButtonOnDocument()
   {
       // Use the following line of code in projects that target the .NET Framework 4.
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
       // In projects that target the .NET Framework 3.5, use the following line of code.
       // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();
   
       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);
       }
   }
   

4. Aggiungere il seguente metodo alla classe ThisAddIn. Quando l'utente seleziona la casella di controllo Aggiungi controllo RTF sulla barra multifunzione, questo metodo consente di aggiungere un oggetto RichTextContentControl alla selezione corrente nel documento se viene selezionata la casella di controllo o di rimuovere l'oggetto RichTextContentControl se la casella di controllo viene deselezionata.

   Friend Sub ToggleRichTextControlOnDocument()
       ' Use the following line of code in projects that target the .NET Framework 4.
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       ' In projects that target the .NET Framework 3.5, use the following line of code.
       ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
   
       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
   

   internal void ToggleRichTextControlOnDocument()
   {
       // Use the following line of code in projects that target the .NET Framework 4.
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
       // In projects that target the .NET Framework 3.5, use the following line of code.
       // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();
   
       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);
       }
   }
   

Rimozione del pulsante al salvataggio del documento

I controlli Windows Form non vengono mantenuti al salvataggio e chiusura del documento. Tuttavia, un wrapper ActiveX per ogni controllo rimane nel documento e il bordo di questo wrapper può essere visualizzato dagli utenti finali quando il documento viene riaperto. Sono disponibili diversi modi per pulire i controlli Windows Form creati dinamicamente nei componenti aggiuntivi. Nella presente procedura dettagliata il controllo Button viene rimosso a livello di codice quando il documento viene salvato.

Per rimuovere il pulsante al salvataggio del documento

1. Nel file di codice ThisAddIn.cs o ThisAddIn.vb aggiungere il seguente metodo alla classe ThisAddIn. Questo metodo è un gestore eventi per l'evento DocumentBeforeSave. Se il documento salvato dispone di un elemento host Document associato, il gestore eventi ottiene l'elemento host e rimuove il controllo Button, se esistente.

   Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
       ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
       ' Use the following line of code in projects that target the .NET Framework 4.
       Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)
   
       ' In projects that target the .NET Framework 3.5, use the following line of code.
       ' Dim isExtended As Boolean = Doc.HasVstoObject()
   
       If isExtended Then
           ' Use the following line of code in projects that target the .NET Framework 4.
           Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)
   
           ' In projects that target the .NET Framework 3.5, use the following line of code.
           ' Dim vstoDocument As Document = Doc.GetVstoObject()
   
           If vstoDocument.Controls.Contains(button) Then
               vstoDocument.Controls.Remove(button)
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
           End If
       End If
   End Sub
   

   private void Application_DocumentBeforeSave(Word.Document Doc, 
       ref bool SaveAsUI, ref bool Cancel)
   {
       // Use the following line of code in projects that target the .NET Framework 4.
       bool isExtended = Globals.Factory.HasVstoObject(Doc);
   
       // In projects that target the .NET Framework 3.5, use the following line of code.
       // bool isExtended = Doc.HasVstoObject();
   
       if (isExtended)
       {
           // Use the following line of code in projects that target the .NET Framework 4.
           Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);
   
           // In projects that target the .NET Framework 3.5, use the following line of code.
           // Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();
   
           if (vstoDocument.Controls.Contains(button))
           {
               vstoDocument.Controls.Remove(button);
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
           }
       }
   }
   

2. In C#, aggiungere il seguente codice al gestore eventi ThisAddIn_Startup. Questo codice è necessario in C# per connettere il gestore eventi Application_DocumentBeforeSave con l'evento DocumentBeforeSave.

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

Aggiunta e rimozione di controlli quando l'utente fa clic sulle caselle di controllo sulla barra multifunzione

Modificare i gestori eventi Click delle caselle di controllo aggiunte alla barra multifunzione per aggiungere o rimuovere i controlli sul documento.

Per aggiungere o rimuovere controlli quando l'utente fa clic sulle caselle di controllo sulla barra multifunzione

• Nel file di codice MyRibbon.cs o MyRibbon.vb, sostituire i gestori eventi addButtonCheckBox_Click e addRichTextCheckBox_Click generati con il codice riportato di seguito. Questo codice consente di ridefinire i gestori eventi per chiamare i metodi ToggleButtonOnDocument e ToggleRichTextControlOnDocument aggiunti alla classe ThisAddIn nelle fasi precedenti nella presente procedura dettagliata.

  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
  

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

Verifica della soluzione

Aggiungere controlli a un documento selezionandoli dalla scheda personalizzata sulla barra multifunzione. Una volta salvato il documento, il controllo Button verrà rimosso.

Per verificare la soluzione.

1. Premere F5 per eseguire il progetto.

2. Nel documento attivo, premere INVIO più volte per aggiungere nuovi paragrafi vuoti al documento.

3. Selezionare il primo paragrafo.

4. Fare clic sulla scheda Componenti aggiuntivi.

5. Nel gruppo Aggiungi controlli, scegliere Pulsante Aggiungi.

   Viene visualizzato un pulsante nel primo paragrafo.

6. Selezionare l'ultimo paragrafo.

7. Nel gruppo Aggiungi controlli, scegliere Aggiungi controllo RTF.

   Un controllo del contenuto RTF viene aggiunto all'ultimo paragrafo.

8. Salvare il documento.

   Il pulsante viene rimosso dal documento.

Passaggi successivi

Per ulteriori informazioni sui controlli dei componenti aggiuntivi a livello di applicazione, vedere gli argomenti seguenti:

• Per un esempio in cui viene illustrato come aggiungere molti altri tipi di controlli a un documento in fase di esecuzione e ricreare i controlli quando viene riaperto il documento, vedere l'esempio relativo ai controlli dinamici dei componenti aggiuntivi per Word in Procedure dettagliate ed esempi di sviluppo di applicazioni per Microsoft Office.

• Per una procedura dettagliata in cui viene illustrato come aggiungere controlli a un foglio di lavoro tramite un componente aggiuntivo a livello di applicazione per Excel, vedere Procedura dettagliata: aggiunta di controlli a un foglio di lavoro in fase di esecuzione in un progetto a livello di applicazione.

Vedere anche

Attività

Procedura: aggiungere controlli Windows Form a documenti di Office

Procedura: aggiungere controlli del contenuto ai documenti di Word

Concetti

Aggiunta di controlli ai documenti di Office in fase di esecuzione

Persistenza dei controlli dinamici nei documenti di Office

Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione

Altre risorse

Soluzioni Word

Word Add-In Dynamic Controls Sample