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

Articolo
08/11/2011

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

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

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

Scegliere Aggiungi nuovo elemento dal menu Progetto.
Nella finestra di dialogo Aggiungi nuovo elemento selezionare Barra multifunzione (finestra di progettazione visiva).
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.
Scegliere group1 nella finestra di progettazione della barra multifunzione.
Nella finestra Proprietà modificare la proprietà Label per group1 in Aggiungi controlli.
Dalla scheda Controlli barra multifunzione di Office della Casella degli strumenti, trascinare un controllo CheckBox in group1.
Fare clic su CheckBox1 per selezionarlo.
Nella finestra Proprietà modificare le proprietà riportate di seguito.

Proprietà

Valore

Nome

addButtonCheckBox

Etichetta

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

Proprietà

Valore

Nome

addRichTextCheckBox

Etichetta

Aggiungi controllo RTF
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.
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.

Proprietà	Valore
Nome	addButtonCheckBox
Etichetta	Pulsante Aggiungi

Proprietà	Valore
Nome	addRichTextCheckBox
Etichetta	Aggiungi controllo RTF

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

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

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;

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);
    }
}

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

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;
        }
    }
}

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.

Premere F5 per eseguire il progetto.
Nel documento attivo, premere INVIO più volte per aggiungere nuovi paragrafi vuoti al documento.
Selezionare il primo paragrafo.
Fare clic sulla scheda Componenti aggiuntivi.
Nel gruppo Aggiungi controlli, scegliere Pulsante Aggiungi.

Viene visualizzato un pulsante nel primo paragrafo.
Selezionare l'ultimo paragrafo.
Nel gruppo Aggiungi controlli, scegliere Aggiungi controllo RTF.

Un controllo del contenuto RTF viene aggiunto all'ultimo paragrafo.
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

Condividi tramite