Aggiungere controlli ai documenti di Office in fase di esecuzione

  • Articolo

È possibile aggiungere controlli a un documento di Microsoft Office Word e a una cartella di lavoro di Microsoft Office Excel in fase di esecuzione. È inoltre possibile rimuoverli in fase di esecuzione. I controlli aggiunti o rimossi in fase di esecuzione sono noti come controlli dinamici.

Si applica a: le informazioni contenute in questo argomento si applicano ai progetti a livello di documento e ai progetti di componente aggiuntivo VSTO per Excel e Word. Per altre informazioni, vedere Funzionalità disponibili per app Office lication e tipo di progetto.

In questo argomento vengono descritti gli elementi indicati di seguito.

Gestire i controlli in fase di esecuzione usando le raccolte di controlli

Per aggiungere, ottenere o rimuovere i controlli in fase di esecuzione, usare i metodi di supporto degli oggetti ControlCollection e ControlCollection .

La modalità di accesso a questi oggetti dipende dal tipo di progetto che si sta sviluppando:

Aggiunta di controlli

I tipi ControlCollection e ControlCollection includono metodi di supporto che è possibile usare per aggiungere controlli host e controlli Windows Form comuni a documenti e fogli di lavoro. Il nome di ciascun metodo presenta il formato Addclasse del controllo, dove classe del controllo rappresenta il nome del controllo che si desidera aggiungere. Ad esempio, per aggiungere un controllo NamedRange al documento, usare il metodo AddNamedRange .

Nell'esempio di codice seguente viene aggiunto un controllo NamedRange a un oggetto Sheet1 di un progetto a livello di documento per Excel.

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Controlli di accesso ed eliminazione

È possibile usare la proprietà Controls di un oggetto Worksheet o Document per scorrere tutti i controlli nel documento, compresi i controlli aggiunti in fase di progettazione. Questi controlli sono anche noti come controlli statici.

È possibile rimuovere i controlli dinamici chiamando il Delete metodo del controllo o chiamando il Remove metodo di ogni insieme Controls. Nell'esempio di codice seguente, il metodo Remove viene usato per rimuovere un controllo NamedRange dall'oggetto Sheet1 di un progetto a livello di documento per Excel.

Globals.Sheet1.Controls.Remove("ChartSource");

I controlli statici non possono essere rimossi in fase di esecuzione. Se si tenta di usare il metodo Delete o il metodo Remove per rimuovere un controllo statico, verrà generata un'eccezione CannotRemoveControlException.

Nota

Non rimuovere a livello di codice i controlli nel gestore eventi Shutdown del documento. Gli elementi di interfaccia utente del documento non sono più disponibili quando viene generato l'evento Shutdown . Se si desidera rimuovere i controlli prima della chiusura del documento, aggiungere il codice al gestore eventi per un altro evento, ad esempio BeforeClose o BeforeSave per Word oppure BeforeCloseo BeforeSave per Excel.

Aggiungere controlli host ai documenti

Quando si aggiunge a livello di codice un controllo host a un documento, è necessario specificare un nome che identifichi il controllo in modo univoco, nonché la posizione del documento in cui aggiungere il controllo. Per istruzioni specifiche, vedere gli argomenti seguenti:

Per altre informazioni sui controlli host, vedere Panoramica degli elementi host e dei controlli host.

Quando si salva e si chiude un documento, tutti i controlli host creati dinamicamente vengono disconnessi dai relativi eventi e perdono le proprie funzionalità di associazione dati. È possibile aggiungere codice alla soluzione per ricreare i controlli host quando il documento viene riaperto. Per altre informazioni, vedere Rendere persistenti i controlli dinamici nei documenti di Office.

Nota

I controlli host XmlMappedRange, XMLNodee XMLNodesnon possono essere aggiunti a livello di codice ai documenti. Di conseguenza, per tali controlli non viene fornito alcun metodo di supporto.

Aggiungere controlli Windows Form ai documenti

Quando si aggiunge a livello di codice un controllo Windows Form a un documento, è necessario fornire il percorso del controllo e un nome che lo identifichi in modo univoco. Il Strumenti di Visual Studio per il runtime di Office fornisce metodi helper per ogni controllo. Questi metodi sono sottoposti a overload per consentire il passaggio di un intervallo o le coordinate specifiche per la posizione del controllo.

Quando si salva e si chiude un documento, tutti i controlli Windows Form creati dinamicamente vengono rimossi dal documento. È possibile aggiungere codice alla soluzione per ricreare i controlli quando il documento viene riaperto. Se si creano controlli Windows Form dinamici usando un componente aggiuntivo VSTO, i wrapper ActiveX per i controlli vengono lasciati nel documento. Per altre informazioni, vedere Rendere persistenti i controlli dinamici nei documenti di Office.

Nota

I controlli Windows Form non possono essere aggiunti a documenti protetti a livello di codice. Per rimuovere a livello di codice la protezione di un documento di Word o di un foglio di lavoro di Excel allo scopo di aggiungere un controllo, è necessario scrivere codice aggiuntivo per rimuovere il wrapper ActiveX del controllo alla chiusura del documento. Il wrapper ActiveX del controllo non viene eliminato automaticamente dai documenti protetti.

Aggiungere controlli personalizzati

Se si desidera aggiungere un Control non supportato dai metodi di supporto disponibili, ad esempio un controllo utente personalizzato, usare i metodi seguenti:

  • Per Excel, usare uno dei metodi AddControl di un oggetto ControlCollection .

  • Per Word, usare uno dei metodi AddControl di un oggetto ControlCollection .

    Per aggiungere il controllo, passare il controllo Control, la posizione del controllo e un nome che lo identifichi in modo univoco per il metodo AddControl. Il metodo AddControl restituisce un oggetto che definisce la modalità di interazione del controllo con il foglio di lavoro o il documento. Il AddControl metodo restituisce un ControlSite oggetto (per Excel) o un ControlSite oggetto (per Word).

    Nell'esempio di codice seguente viene illustrato come usare il metodo AddControl per aggiungere dinamicamente un controllo utente personalizzato a un foglio di lavoro in un progetto Excel a livello di documento. In questo esempio, il controllo utente è denominato UserControl1e Range è denominato range1. Per usare questo esempio, eseguirlo dalla classe Sheetn nel progetto.

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Usare i membri dei controlli personalizzati

Dopo aver usato uno dei metodi AddControl per aggiungere un controllo a un foglio di lavoro o a un documento, si dispone di due oggetti controllo diversi:

  • Il controllo Control che rappresenta il controllo personalizzato.

  • Oggetto ControlSite, OLEObject o OLEControl che rappresenta il controllo dopo l'aggiunta al foglio di lavoro o al documento.

    Questi controlli condividono molti metodi e proprietà. È importante accedere a questi membri mediante il controllo appropriato:

  • Per accedere ai membri appartenenti esclusivamente al controllo personalizzato, usare Control.

  • Per accedere a membri condivisi dai controlli, usare l'oggetto ControlSite, OLEObject o OLEControl.

    Se si accede a un membro condiviso da Control, è possibile che vengano generati risultati non validi oppure che si verifichi un errore senza che vengano visualizzati avvisi o notifiche. Usare sempre i metodi o le proprietà dell'oggetto ControlSite, OLEObject o OLEControl, a meno che il metodo o la proprietà da usare non sia disponibile; solo in questo caso è opportuno fare riferimento a Control.

    Ad esempio, sia la classe ControlSite che la classe Control dispongono di una proprietà Top. Per ottenere o impostare la distanza fra la parte superiore del controllo e quella del documento, usare la proprietà Top del controllo ControlSiteanziché la proprietà Top del controllo Control.

    // Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

Contenuto correlato