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

Aggiornamento: Luglio 2008

Si applica a
Le informazioni contenute in questo argomento riguardano solo i progetti Visual Studio Tools per Office e le versioni di Microsoft Office specificati. Tipo di progetto Progetti a livello di applicazione Versione Microsoft Office Word 2007 Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

A partire da Visual Studio 2008 Service Pack 1 (SP1) l'aggiunta di controlli può essere effettuata a qualsiasi documento di Microsoft Office Word 2007 aperto, utilizzando 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.

Vengono illustrate le attività seguenti:

• 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.

Nota:
Nel computer in uso è possibile che vengano visualizzati nomi o percorsi diversi per alcuni elementi dell'interfaccia utente di Visual Studio nelle istruzioni seguenti. La versione di Visual Studio in uso e le impostazioni configurate determinano questi elementi. Per ulteriori informazioni vedere Impostazioni di Visual Studio.

Prerequisiti

Per completare la procedura dettagliata è necessario disporre dei componenti elencati di seguito.

• Visual Studio Tools per Office°(componente facoltativo di Visual Studio 2008 Professional e Visual Studio Team System).

• Visual Studio 2008 SP1.

• Microsoft Office Word 2007.

Creazione di un nuovo progetto componente aggiuntivo per Word

Creare innanzitutto un progetto componente aggiuntivo per Word 2007.

Per creare un nuovo progetto componente aggiuntivo per Word

• Creare un progetto componente aggiuntivo a livello di applicazione per Word 2007 denominato WordDynamicControls. Per ulteriori informazioni, vedere la classe Procedura: creare progetti Visual Studio Tools per Office.

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	addButtonComboBox
   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 di 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 di 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 hostMicrosoft.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 solo in fase di esecuzione, tramite il metodo GetVstoObject.

Aggiungere metodi alla classe ThisAddIn che può essere chiamata per aggiungere o rimuovere un oggetto Button o RichTextContentControl sul 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, tramite questo metodo viene aggiunto un oggetto Button alla selezione corrente nel documento se viene selezionata la casella di controllo o viene rimosso l'oggetto Button se la casella di controllo viene deselezionata.

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

   internal void ToggleButtonOnDocument()
   {
       Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
       Document vstoDocument = nativeDocument.GetVstoObject();
       string name = "MyButton";
   
       if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
       {
           if (Globals.ThisAddIn.Application.Selection != null)
           {
               button = vstoDocument.Controls.AddButton(
                   Globals.ThisAddIn.Application.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, tramite questo metodo viene aggiunto un oggetto RichTextContentControl alla selezione corrente nel documento se viene selezionata la casella di controllo o viene rimosso l'oggetto RichTextContentControl se la casella di controllo viene deselezionata.

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

   internal void ToggleRichTextControlOnDocument()
   {
       Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
       Document vstoDocument = nativeDocument.GetVstoObject();
       string name = "MyRichTextBoxControl";
   
       if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
       {
           if (Globals.ThisAddIn.Application.Selection != null)
           {
               richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                   Globals.ThisAddIn.Application.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
       If Doc.HasVstoObject() Then
           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)
   {
       if (Doc.HasVstoObject())
       {
           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, sostiutire 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

Aggiugere 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 Esempio di controlli dinamici del componente aggiuntivo di Word.

• 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

Esempio di controlli dinamici del componente aggiuntivo di Word

Concetti

Distribuzione di componenti aggiuntivi a livello di applicazione per Word

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

Cronologia delle modifiche

Date	History	Motivo
Luglio 2008	Argomento aggiunto.	Modifica di funzionalità in SP1.