Cenni preliminari sul riquadro delle azioni

Articolo
04/28/2010

Aggiornamento: novembre 2007

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 documento Versione Microsoft Office Microsoft Office System 2007 Microsoft Office 2003 Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

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 documento

Versione Microsoft Office

Microsoft Office System 2007
Microsoft Office 2003

Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

Un riquadro azioni è un riquadro attività Azioni documenti personalizzabile allegato a un documento Microsoft Office Word o una cartella di lavoro Microsoft Office Excel specifica. Si trova all'interno del riquadro attività di Office insieme ad altri riquadri attività incorporati come Origine XML in Excel o Stili e formattazione in Word. È possibile utilizzare i controlli Windows Form o WPF per progettare l'interfaccia utente del riquadro azioni.

Il riquadro azioni può essere creato solo in una personalizzazione a livello di documento per Word o Excel e non può essere creato in un componente aggiuntivo a livello di applicazione. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazione.

Nota:
Il riquadro delle azioni è diverso dai riquadri attività personalizzati. I riquadri attività personalizzati sono associati all'applicazione, non a uno specifico documento. È possibile aggiungere riquadri attività personalizzati ai componenti aggiuntivi a livello di applicazione per Microsoft Office System 2007. Per ulteriori informazioni, vedere Cenni preliminari sui riquadri attività personalizzati.

Il riquadro delle azioni è diverso dai riquadri attività personalizzati. I riquadri attività personalizzati sono associati all'applicazione, non a uno specifico documento. È possibile aggiungere riquadri attività personalizzati ai componenti aggiuntivi a livello di applicazione per Microsoft Office System 2007. Per ulteriori informazioni, vedere Cenni preliminari sui riquadri attività personalizzati.

Visualizzazione del riquadro azioni

Il riquadro azioni è rappresentato dalla classe ActionsPane. Quando si crea un progetto a livello di documento, un'istanza di questa classe è disponibile nel codice tramite il campo ActionsPane della classe ThisWorkbook (per Excel) o ThisDocument (per Word) contenuta nel progetto. Per visualizzare il riquadro azioni, aggiungere un controllo Windows Form alla proprietà Controls del campo ActionsPane. Nell'esempio di codice seguente viene illustrato come aggiungere un controllo denominato actions al riquadro azioni.

Me.ActionsPane.Controls.Add(actions)

this.ActionsPane.Controls.Add(actions);

Il riquadro azioni diventa visibile in fase di esecuzione non appena vi si aggiunge un controllo in modo esplicito. Una volta visualizzato il riquadro delle azioni, è possibile aggiungere o rimuovere dinamicamente controlli in risposta alle azioni dell'utente. In genere, il codice per la visualizzazione del riquadro delle azioni viene aggiunto nel gestore eventi Startup di ThisDocument o di ThisWorkbook in modo che il riquadro delle azioni sia visibile quando l'utente apre il documento per la prima volta. È possibile tuttavia visualizzare il riquadro delle azioni solo in risposta a determinate azioni dell'utente nel documento. Ad esempio, è possibile aggiungere il codice all'evento Click di un controllo nel documento.

Aggiunta di più controlli al riquadro azioni

Se si aggiungono più controlli al riquadro azioni, nella maggior parte dei casi è necessario raggrupparli in un controllo utente e quindi aggiungere quest'ultimo nella proprietà Controls. Questo processo comprende i passaggi seguenti:

Creare l'interfaccia utente del riquadro azioni aggiungendo un elemento Controllo riquadro azioni o Controllo utente al progetto. Entrambi questi elementi includono una classe UserControl personalizzata di Windows Form. Gli elementi Controllo riquadro azioni e Controllo utente sono equivalenti. Differiscono fra loro soltanto per il nome.

Aggiungere controlli Windows Form a UserControl tramite la finestra di progettazione o scrivendo codice.

Nota:
È inoltre possibile aggiungere un controllo WPF al riquadro azioni. A tale scopo, aggiungere un controllo System.Windows.Controls.UserControl WPF all'oggetto UserControl Windows Form. Per ulteriori informazioni, vedere la classe Utilizzo dei controlli WPF nelle soluzioni Office.

Aggiungere un'istanza del controllo utente personalizzato ai controlli contenuti nel campo ActionsPane della classe ThisWorkbook (per Excel) o ThisDocument (per Word) presente nel progetto.

Esempi che illustrano questo processo in maggior dettaglio sono disponibili in Procedura: aggiungere un riquadro per le azioni nei documenti di Word e Procedura: aggiungere un riquadro per le azioni nelle cartelle di lavoro di Excel.

Nascondere il riquadro delle azioni

Sebbene la classe ActionsPane presenti un metodo Hide e una proprietà Visible, non è possibile rimuovere il riquadro azioni dall'interfaccia utente utilizzando membri della classe ActionsPane stessa. La chiamata del metodo Hide o l'impostazione della proprietà Visible su false nasconde solo i controlli aggiunti al riquadro delle azioni ma non nasconde il riquadro attività.

Per nascondere il riquadro attività della soluzione sono disponibili diverse opzioni:

In Word, impostare la proprietà Visible dell'oggetto TaskPane che rappresenta il riquadro attività Azioni documenti su false. Per utilizzare l'esempio di codice seguente è necessario eseguirlo dalla classe ThisDocument del progetto.
```
Me.Application.TaskPanes(Word.WdTaskPanes.wdTaskPaneDocumentActions).Visible = False
```
```
this.Application.TaskPanes[Word.WdTaskPanes.wdTaskPaneDocumentActions].Visible = false;
```
In Excel, impostare la proprietà DisplayDocumentActionTaskPane dell'oggetto Application su false. Per utilizzare l'esempio di codice seguente è necessario eseguirlo dalla classe ThisWorkbook del progetto.
```
Me.Application.DisplayDocumentActionTaskPane = False
```
```
this.Application.DisplayDocumentActionTaskPane = false;
```
In Word o Excel è inoltre possibile impostare la proprietà CommandBar.Visible della barra dei comandi che rappresenta il riquadro attività su false. Per utilizzare l'esempio di codice seguente è necessario eseguirlo dalla classe ThisDocument o ThisWorkbook del progetto.
```
Me.Application.CommandBars("Task Pane").Visible = False
```
```
this.Application.CommandBars["Task Pane"].Visible = false;
```

Cancellazione del riquadro azioni all'apertura del documento

Se l'utente salva il documento con il riquadro delle azioni visibile, quest'ultimo diviene visibile ad ogni apertura documento, indipendentemente dal fatto che il riquadro delle azioni contenga o meno controlli. Se si desidera controllare quando viene visualizzato, chiamare il metodo Clear del campo ActionsPane nel gestore eventi Startup di ThisDocument o di ThisWorkbook per garantire che il riquadro delle azioni non risulti visibile all'apertura del documento.

Rilevamento della chiusura del riquadro azioni

La chiusura del riquadro azioni non genera alcun evento. Anche se la classe ActionsPane dispone di un evento VisibleChanged, questo non viene generato quando l'utente finale chiude il riquadro azioni, ma quando i controlli del riquadro azioni vengono nascosti chiamando il metodo Hide o impostando la proprietà Visible su false.

Se l'utente finale chiude il riquadro azioni, potrà visualizzarlo nuovamente eseguendo nell'interfaccia utente dell'applicazione una delle procedure riportate di seguito.

Per visualizzare il riquadro azioni tramite l'interfaccia utente di Word 2007 o Excel 2007

Nella barra multifunzione, fare clic sulla scheda Visualizza.
Nel gruppo Mostra/Nascondi, fare clic sull'interruttore Azioni documenti.

Per visualizzare il riquadro azioni tramite l'interfaccia utente di Word 2003 o Excel 2003

Scegliere Riquadro attività dal menu Visualizza.
Se viene visualizzato un riquadro attività diverso da Azioni documenti, fare clic sul pulsante Altri riquadri attività vicino la parte superiore del riquadro attività e quindi fare clic su Azioni documenti.

Programmazione degli eventi del riquadro delle azioni

È possibile aggiungere più controlli utente al riquadro delle azioni e scrivere codice per rispondere agli eventi all'interno del documento mostrando o nascondendo i controlli utente. Se si mappano gli elementi dello schema XML al documento, è possibile visualizzare alcuni controlli utente nel riquadro azioni ogni volta che il punto di inserimento è all'interno di uno degli elementi XML. Per ulteriori informazioni, vedere Procedura dettagliata: modifica del riquadro delle azioni in base al contesto dell'utente, Procedura: mappare schemi a documenti di Word in Visual Studio e Procedura: mappare schemi a fogli di lavoro in Visual Studio.

È anche possibile scrivere codice per rispondere agli eventi di qualsiasi oggetto, inclusi gli eventi dei controlli host, delle applicazioni o dei documenti. Per ulteriori informazioni, vedere Procedura dettagliata: programmazione per eventi di un controllo NamedRange.

Associazione di dati a controlli nel riquadro azioni

I controlli del riquadro delle azioni sono dotati delle stesse funzionalità di associazione dati dei controlli contenuti nei Windows Form. Tali controlli possono essere associati a origini dati come DataSet, DataSet tipizzati e XML. Per ulteriori informazioni, vedere la classe Associazione dati e Windows Form.

I controlli del riquadro delle azioni e i controlli del documento possono essere associati allo stesso DataSet. È ad esempio possibile creare una relazione Master-Details tra i controlli del riquadro delle azioni e i controlli del foglio di lavoro. Per ulteriori informazioni, vedere Procedura dettagliata: associazione di dati a controlli in un riquadro delle azioni di Excel.

Convalida di dati nei controlli del riquadro delle azioni

Se nel riquadro eventi Validating di un controllo del riquadro delle azioni viene visualizzata una finestra di messaggio, l'evento potrebbe essere generato una seconda volta quando lo stato attivo si sposta dal controllo alla finestra di messaggio. Per evitare questo problema, utilizzare un controllo ErrorProvider che consente di visualizzare gli eventuali messaggi di errore di convalida.

Ordine di sovrapposizione dei controlli utente

Se si utilizzano più controlli utente, è possibile scrivere codice per sovrapporre in modo appropriato i controlli nel riquadro delle azioni a prescindere dall'ancoraggio verticale o orizzontale. È possibile impostare l'ordine di sovrapposizione dei controlli utente nel riquadro delle azioni mediante l'enumerazione StackStyle della proprietà StackOrder. Per ulteriori informazioni, vedere Procedura: gestire il layout di controllo dei riquadri delle azioni.

La proprietà StackOrder accetta le enumerazioni indicate di seguito.

Stile di sovrapposizione	Definizione
FromBottom	La sovrapposizione viene eseguita a partire dalla parte inferiore del riquadro delle azioni.
FromLeft	La sovrapposizione viene eseguita a partire dalla parte sinistra del riquadro delle azioni.
FromRight	La sovrapposizione viene eseguita a partire dalla parte destra del riquadro delle azioni.
FromTop	La sovrapposizione viene eseguita a partire dalla parte superiore del riquadro delle azioni.
None	Nessun ordine di sovrapposizione definito; l'ordine è controllato dallo sviluppatore.

Nel codice riportato di seguito viene impostata la proprietà StackOrder per sovrapporre i controlli utente a partire dalla parte superiore del riquadro delle azioni.

Me.ActionsPane.StackOrder = Microsoft.Office.Tools.StackStyle.FromTop

this.ActionsPane.StackOrder = Microsoft.Office.Tools.StackStyle.FromTop;

Ancoraggio dei controlli

Se l'utente ridimensiona il riquadro delle azioni in fase di esecuzione, insieme al riquadro potrebbero venire ridimensionati anche i controlli in esso contenuti. È possibile utilizzare la proprietà Anchor di un controllo Windows Form per ancorare i controlli al riquadro delle azioni. Allo stesso modo è possibile ancorare i controlli Windows Form sul controllo utente. Per ulteriori informazioni, vedere Procedura: agganciare i controlli in Windows Form.

Ridimensionamento del riquadro azioni

Non è possibile modificare direttamente le dimensioni di un oggetto ActionsPane poiché ActionsPane è integrato nel riquadro attività. È tuttavia possibile modificare a livello di codice la larghezza del riquadro attività impostando la proprietà Width della classe CommandBar che rappresenta il riquadro attività. È possibile modificare l'altezza del riquadro attività se è mobile o ancorato orizzontalmente.

Il ridimensionamento tramite codice del riquadro attività in genere non è consigliato, perché l'utente dovrebbe potere scegliere la dimensione del riquadro attività sullo schermo più adatta alle proprie esigenze. Tuttavia, se è necessario procedere al ridimensionamento del riquadro attività, è possibile utilizzare a tale scopo il codice riportato di seguito.

Me.CommandBars("Task Pane").Width = 200

this.CommandBars["Task Pane"].Width = 200;

Riposizionamento del riquadro azioni

Non è possibile riposizionare direttamente l'oggetto ActionsPane poiché è integrato nel riquadro attività. È possibile tuttavia spostare il riquadro attività utilizzando il codice, tramite l'impostazione della proprietà Position della classe CommandBar che rappresenta il riquadro attività.

Il riposizionamento tramite codice del riquadro attività in genere non è consigliato, perché l'utente dovrebbe potere scegliere la posizione del riquadro attività sullo schermo più adatta alle proprie esigenze. Se però è necessario spostare il riquadro attività in una particolare posizione, è possibile utilizzare il seguente codice.

Me.CommandBars("Task Pane").Position = _
    Microsoft.Office.Core.MsoBarPosition.msoBarLeft

this.CommandBars["Task Pane"].Position =
    Microsoft.Office.Core.MsoBarPosition.msoBarLeft;

Nota:
Gli utenti finali possono riposizionare manualmente il riquadro attività in qualunque momento. Non è possibile ottenere che il riquadro attività rimanga ancorato nella posizione indicata a livello di codice. Tuttavia, è possibile controllare le modifiche di orientamento e verificare che i controlli nel riquadro azioni siano impilati nella direzione corretta. Per ulteriori informazioni, vedere Procedura: gestire il layout di controllo dei riquadri delle azioni.

Gli utenti finali possono riposizionare manualmente il riquadro attività in qualunque momento. Non è possibile ottenere che il riquadro attività rimanga ancorato nella posizione indicata a livello di codice. Tuttavia, è possibile controllare le modifiche di orientamento e verificare che i controlli nel riquadro azioni siano impilati nella direzione corretta. Per ulteriori informazioni, vedere Procedura: gestire il layout di controllo dei riquadri delle azioni.

L'impostazione delle proprietà Top e Left della classe ActionsPane non modifica la posizione, poiché l'oggetto ActionsPane è incorporato nel riquadro attività.

Se il riquadro attività non è ancorato, è possibile impostare le proprietà Top e Left dell'oggetto CommandBar che rappresenta il riquadro attività. Nell'esempio di codice riportato di seguito viene illustrato come spostare un riquadro attività non ancorato nell'angolo superiore sinistro del documento.

If Me.CommandBars("Task Pane").Position = _
    Microsoft.Office.Core.MsoBarPosition.msoBarFloating Then

    Me.CommandBars("Task Pane").Top = 0
    Me.CommandBars("Task Pane").Left = 0

End If

if (this.CommandBars["Task Pane"].Position == 
    Microsoft.Office.Core.MsoBarPosition.msoBarLeft)
{
    this.CommandBars["Task Pane"].Top = 0;
    this.CommandBars["Task Pane"].Left = 0;
}