Procedura dettagliata: Aggiungere controlli a un documento in fase di esecuzione in un componente aggiuntivo VSTO

È possibile aggiungere controlli a qualsiasi documento di Microsoft Office Word aperto usando un componente aggiuntivo VSTO. Questa procedura dettagliata illustra come usare la barra multifunzione per consentire agli utenti di aggiungere un Button oggetto o a RichTextContentControl un documento.

Si applica a: le informazioni contenute in questo argomento si applicano ai progetti di componente aggiuntivo VSTO per Word 2010. Per altre informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

In questa procedura dettagliata sono illustrati i task seguenti:

• Creazione di un nuovo progetto di componente aggiuntivo VSTO per Word.

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

• Aggiunta di controlli ai documenti in fase di esecuzione.

• Rimozione di controlli dal documento.

  Nota

  I nomi o i percorsi visualizzati per alcuni elementi dell'interfaccia utente di Visual Studio nelle istruzioni seguenti potrebbero essere diversi nel computer in uso. La versione di Visual Studio in uso e le impostazioni configurate determinano questi elementi. Per altre informazioni, vedere Personalizzare l'IDE.

Prerequisiti

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

• Una versione di Visual Studio che include Microsoft Office Developer Tools. Per altre informazioni, vedere Configurare un computer per sviluppare soluzioni Office.

• Word 2013 o Word 2010 .

Creare un nuovo progetto di componente aggiuntivo di Word

Creare innanzitutto un progetto di componente aggiuntivo VSTO per Word.

Per creare un nuovo progetto di componente aggiuntivo VSTO per Word.

1. Creare un progetto di componente aggiuntivo VSTO per Word con il nome WordDynamicControls. Per altre informazioni, vedere Procedura: Creare progetti di Office in Visual Studio.

2. Aggiungere un riferimento all'assembly Microsoft.Office.Tools.Word.v4.0.Utilities.dll . Tale riferimento è necessario per aggiungere un controllo Windows Form a livello di codice al documento più avanti in questa procedura dettagliata.

Fornire un'interfaccia utente per aggiungere controlli a un documento

Aggiungere una scheda personalizzata alla barra multifunzione di 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. Dal menu Progetto fare clic su Aggiungi nuovo elemento.

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

3. Modificare il nome della nuova barra multifunzione in MyRibbone quindi scegliere 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. Nella finestra di progettazione della barra multifunzione fare clic sul gruppo group1 .

5. Nella finestra Proprietà impostare la proprietà Etichetta per group1 su Add Controls.

6. Dalla scheda Controlli barra multifunzione di Office della Casella degli strumentitrascinare un controllo ToggleButton in group1.

7. Fare clic su CheckBox1 per selezionarlo.

8. Nella finestra Proprietà modificare le seguenti proprietà:

   Proprietà	valore
   Nome	addButtonCheckBox
   Etichetta	Pulsante Aggiungi

9. Aggiungere una seconda casella di controllo a group1e quindi modificare le proprietà seguenti.

   Proprietà	valore
   Nome	addRichTextCheckBox
   Etichetta	Add Rich Text Control

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

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

11. Tornare alla finestra di progettazione della barra multifunzione e fare doppio clic su Add Rich Text Control.

    Il gestore eventi Click della casella di controllo Add Rich Text Control viene aperto nell'editor di codice.

    Più avanti in questa procedura dettagliata si aggiungerà codice a questi gestori eventi per aggiungere e rimuovere i controlli nel documento attivo.

Aggiungere e rimuovere controlli nel documento attivo

Nel codice del componente aggiuntivo VSTO è necessario convertire il documento attivo in un Documentelemento host prima di poter aggiungere un controllo. Nelle soluzioni Office si possono aggiungere controlli gestiti solo agli elementi host, che agiscono da contenitori per i controlli. Nei progetti di componente aggiuntivo VSTO gli elementi host possono essere creati in fase di esecuzione usando il GetVstoObject metodo .

Aggiungere metodi alla classe ThisAddIn che possono essere chiamati per aggiungere o rimuovere un oggetto Button o RichTextContentControl nel documento attivo. Più avanti in questa procedura dettagliata si chiameranno tali metodi dai gestori eventi Click delle caselle di controllo sulla barra multifunzione.

Per aggiungere e rimuovere controlli nel documento attivo

1. In Esplora soluzioni fare doppio clic su ThisAddIn.cs o 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.

   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. Aggiungere il seguente metodo alla classe ThisAddIn. Quando l'utente fa clic sulla casella di controllo Aggiungi pulsante sulla barra multifunzione, questo metodo aggiunge un oggetto Button alla selezione corrente nel documento se la casella di controllo è selezionata oppure rimuove l'oggetto Button se la casella di controllo è deselezionata.

   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. Aggiungere il seguente metodo alla classe ThisAddIn. Quando l'utente fa clic sulla casella di controllo Add Rich Text Control sulla barra multifunzione, questo metodo aggiunge un oggetto RichTextContentControl alla selezione corrente nel documento se la casella di controllo è selezionata oppure rimuove l'oggetto RichTextContentControl se la casella di controllo è deselezionata.

   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
   

Rimuovere il controllo Pulsante quando il documento viene salvato

I controlli Windows Form non vengono mantenuti quando il documento viene salvato e quindi chiuso. Nel documento, però, rimane un wrapper ActiveX per ogni controllo e il bordo di questo wrapper è visibile agli utenti finali quando il documento viene riaperto. Esistono diversi modi per pulire in modo dinamico i controlli Windows Form nei componenti aggiuntivi VSTO. In questa procedura dettagliata si rimuove a livello di codice il Button controllo quando il documento viene salvato.

Per rimuovere il controllo Button quando il documento viene salvato

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

   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. In C# aggiungere il codice seguente al gestore eventi ThisAddIn_Startup . Questo codice è necessario in C# per connettere il gestore eventi Application_DocumentBeforeSave all'evento DocumentBeforeSave .

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

Aggiungere e rimuovere controlli quando l'utente fa clic sulle caselle di controllo sulla barra multifunzione

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

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

1. Nel file di codice MyRibbon.cs o MyRibbon.vb sostituire i gestori eventi e addRichTextCheckBox_Click generati addButtonCheckBox_Click con il codice seguente. Questo codice ridefinisce i gestori eventi per chiamare i metodi ToggleButtonOnDocument e ToggleRichTextControlOnDocument che sono stati aggiunti alla classe ThisAddIn più indietro in questa procedura dettagliata.

   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
   

Test della soluzione

Aggiungere controlli a un documento selezionandoli dalla scheda personalizzata sulla barra multifunzione. Quando si salva il documento, il controllo Button viene rimosso.

Per testare 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 Add Controls fare clic su Aggiungi pulsante.

   Nel primo paragrafo viene visualizzato un pulsante.

6. Selezionare l'ultimo paragrafo.

7. Nel gruppo Add Controls fare clic su Add Rich Text Control.

   All'ultimo paragrafo viene aggiunto un controllo contenuto RTF.

8. Salvare il documento.

   Il pulsante viene rimosso dal documento.

Passaggi successivi

Per altre informazioni sui controlli nei componenti aggiuntivi VSTO, vedere questi argomenti:

• Per un esempio che illustra come aggiungere molti altri tipi di controlli a un documento in fase di esecuzione e ricreare i controlli quando il documento viene riaperto, vedere l'esempio di controlli dinamici del componente aggiuntivo di Word negli esempi di sviluppo e nelle procedure dettagliate di Office.

• Per una procedura dettagliata che illustra come aggiungere controlli a un foglio di lavoro usando un componente aggiuntivo VSTO per Excel, vedere Procedura dettagliata: Aggiungere controlli a un foglio di lavoro in fase di esecuzione nel progetto di componente aggiuntivo VSTO.

Contenuto correlato

• Soluzioni word
• Aggiungere controlli ai documenti di Office in fase di esecuzione
• Rendere persistenti i controlli dinamici nei documenti di Office
• Procedura: Aggiungere controlli Windows Form ai documenti di Office
• Procedura: Aggiungere controlli contenuto ai documenti di Word
• Estendere i documenti di Word e le cartelle di lavoro di Excel nei componenti aggiuntivi VSTO in fase di esecuzione