Cenni preliminari sul modello a oggetti della barra multifunzione

Articolo
08/11/2011

In Runtime di Visual Studio Tools per Office viene esposto un modello a oggetti fortemente tipizzato per ottenere e impostare le proprietà dei controlli della barra multifunzione in fase di esecuzione. Ad esempio, è possibile popolare dinamicamente i controlli dei menu oppure attivare o disattivare la visualizzazione dei controlli in base al contesto. Inoltre, si possono aggiungere schede, gruppi e controlli a una barra multifunzione ma solo prima che la barra multifunzione venga caricata dall'applicazione di Office. Per informazioni, vedere Impostazione di proprietà che diventano di sola lettura.

Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di documento e di applicazione per Excel 2007, Excel 2010, InfoPath 2010, Outlook 2007, Outlook 2010, PowerPoint 2007, PowerPoint 2010, Project 2010, Visio 2010, Word 2007 e Word 2010. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

Questo modello a oggetti della barra multifunzione è costituito principalmente dalla classe Ribbon, dagli eventi della barra multifunzione e dalle classi di controlli della barra multifunzione.

Classe Ribbon

Quando si aggiunge un nuovo elemento Barra multifunzione (finestra di progettazione visiva) a un progetto, in Visual Studio viene aggiunta una classe Ribbon al progetto. Se il progetto è destinato a .NET Framework 4, la classe Ribbon eredita dalla classe RibbonBase. Se il progetto è destinato a .NET Framework 3.5, la classe Ribbon eredita dalla classe OfficeRibbon.

Questa classe viene visualizzata come classe parziale suddivisa tra il file di codice della barra multifunzione e il file di codice della finestra di progettazione della barra multifunzione.

Eventi della barra multifunzione

La classe Ribbon contiene i tre eventi seguenti:

Progetti destinati a .NET Framework 4	Progetti destinati a .NET Framework 3.5	Descrizione
RibbonBase.Load	OfficeRibbon.Load	L'evento viene generato quando l'applicazione di Office carica la personalizzazione della barra multifunzione. Il gestore eventi Load viene aggiunto automaticamente al file di codice della barra multifunzione. Utilizzare questo gestore eventi per l'esecuzione di codice personalizzato al caricamento della barra multifunzione.
RibbonBase.LoadImage	OfficeRibbon.LoadImage	Consente di memorizzare nella cache immagini della personalizzazione della barra multifunzione al caricamento della barra multifunzione. Scrivendo il codice per memorizzare nella cache le immagini della barra multifunzione in questo gestore eventi, si ottiene un leggero miglioramento delle prestazioni. Per ulteriori informazioni, vedere LoadImage.
RibbonBase.Close	OfficeRibbon.Close	L'evento viene generato quando l'istanza della barra multifunzione viene chiusa.

Controlli della barra multifunzione

Lo spazio dei nomi Microsoft.Office.Tools.Ribbon contiene un tipo per ogni controllo presente nel gruppo Controlli barra multifunzione di Office della Casella degli strumenti.

Nella tabella riportata di seguito viene illustrato il tipo per ogni controllo della barra multifunzione. Per la descrizione di ciascun controllo, vedere Cenni preliminari sulla barra multifunzione.

Nome del controllo	Nome di classe
Box	RibbonBox
Button	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Gallery	RibbonGallery
Gruppo	RibbonGroup
Etichetta	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Tab	RibbonTab
ToggleButton	RibbonToggleButton

Lo spazio dei nomi Microsoft.Office.Tools.Ribbon utilizza il prefisso "Ribbon" per questi tipi al fine di evitare conflitti con i nomi delle classi di controllo nello spazio dei nomi System.Windows.Forms.

Quando si aggiunge un controllo alla finestra di progettazione della barra multifunzione, questa dichiara la classe per il controllo come un campo nel file di codice della finestra di progettazione della barra multifunzione.

Attività comuni mediante le proprietà dei controlli della barra multifunzione

Ogni controllo della barra multifunzione contiene proprietà che si possono utilizzare per eseguire varie attività, ad esempio l'assegnazione di un'etichetta a un controllo oppure l'attivazione o la disattivazione della visualizzazione dei controlli.

In alcuni casi, le proprietà diventano di sola lettura dopo il caricamento della barra multifunzione o dopo l'aggiunta di un controllo a un menu dinamico. Per ulteriori informazioni, vedere Impostazione di proprietà che diventano di sola lettura.

Nella tabella riportata di seguito vengono descritte alcune attività che è possibile eseguire utilizzando le proprietà dei controlli della barra multifunzione.

Per questa attività:	Eseguire questa operazione:
Attivare o disattivare la visualizzazione di un controllo.	Utilizzare la proprietà Visible.
Abilitare o disabilitare un controllo.	Utilizzare la proprietà Enabled.
Impostare le dimensioni di un controllo.	Utilizzare la proprietà ControlSize.
Ottenere l'immagine che viene visualizzata in un controllo.	Utilizzare la proprietà Image.
Modificare l'etichetta di un controllo.	Utilizzare la proprietà Label.
Aggiungere dati definiti dall'utente a un controllo.	Utilizzare la proprietà Tag.
Ottenere gli elementi in un controllo RibbonBox, RibbonDropDown, RibbonGallery o RibbonSplitButton.	Utilizzare la proprietà Items.
Aggiungere elementi a un controllo RibbonComboBox, RibbonDropDown o RibbonGallery.	Utilizzare la proprietà Items.
Aggiungere i controlli a RibbonMenu.	Utilizzare la proprietà Items. Per aggiungere controlli a RibbonMenu dopo il caricamento della barra multifunzione nell'applicazione di Office, è necessario impostare la proprietà Dynamic su true prima del caricamento della barra multifunzione nell'applicazione di Office. Per informazioni, vedere Impostazione di proprietà che diventano di sola lettura.
Ottenere l'elemento selezionato di un controllo RibbonComboBox, RibbonDropDown o RibbonGallery.	Utilizzare la proprietà SelectedItem. Per un controllo RibbonComboBox, utilizzare la proprietà Text.
Ottenere i gruppi in un controllo RibbonTab.	Utilizzare la proprietà Groups.
Specificare il numero di righe e colonne che vengono visualizzate in un controllo RibbonGallery.	Utilizzare le proprietà RowCount e ColumnCount.

Impostazione di proprietà che diventano di sola lettura

Alcune proprietà possono essere impostate solo prima del caricamento della barra multifunzione. Queste proprietà possono essere impostate in tre modi:

Nella finestra Proprietà di Visual Studio.
Nel costruttore della classe Ribbon.
Nel metodo CreateRibbonExtensibilityObject della classe ThisAddin, ThisWorkbook o ThisDocument del progetto.

I menu dinamici presentano alcune eccezioni. È possibile creare nuovi controlli, impostarne le proprietà e aggiungerli quindi in fase di esecuzione a un menu dinamico anche dopo il caricamento della barra multifunzione contenente il menu.

Le proprietà dei controlli aggiunti a un menu dinamico possono essere impostate in qualsiasi momento.

Per ulteriori informazioni, vedere Proprietà che diventano di sola lettura.

Impostazione di proprietà nel costruttore della barra multifunzione

È possibile impostare le proprietà di un controllo della barra multifunzione nel costruttore della classe Ribbon. È necessario che tale codice si trovi dopo la chiamata al metodo InitializeComponent. Nell'esempio seguente viene aggiunto un nuovo pulsante a un gruppo se l'ora corrente corrisponde alle 17.00 ora del Pacifico (UTC-8) o più tardi.

Per i progetti destinati a .NET Framework 4, aggiungere il codice seguente:

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

Per i progetti destinati a .NET Framework 3.5, aggiungere il codice seguente:

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New()

    'This call is required by the Component Designer.
    InitializeComponent()
    If DateTime.Now.Hour > 16 Then
        Group1.Items.Add(New RibbonButton())
        CType(Group1.Items.Last(), RibbonButton).Label = "New Button"
    End If
End Sub

public Ribbon1()
{
    InitializeComponent();
    if (DateTime.Now.Hour > 16)
    {
        group1.Items.Add(new RibbonButton());
        ((RibbonButton)group1.Items.Last()).Label = "New Button";
    }

}

In progetti Visual C# aggiornati da Visual Studio 2008, il costruttore viene visualizzato nel file di codice della barra multifunzione.

In progetti Visual Basic o in progetti Visual C# creati in Visual Studio 2010, il costruttore viene visualizzato nel file di codice della finestra di progettazione della barra multifunzione. Il file è denominato YourRibbonItem.Designer.cs o YourRibbonItem.Designer.vb. Nei progetti Visual Basic, per visualizzare il file è prima necessario fare clic sul pulsante Mostra tutti i file in Esplora soluzioni.

Impostazione di proprietà nel metodo CreateRibbonExtensibilityObject

È possibile impostare le proprietà di un controllo della barra multifunzione quando si esegue l'override del metodo CreateRibbonExtensibilityObject nella classe ThisAddin, ThisWorkbook o ThisDocument del progetto. Per ulteriori informazioni sul metodo CreateRibbonExtensibilityObject, vedere Cenni preliminari sulla barra multifunzione.

Nell'esempio riportato di seguito vengono impostate le proprietà della barra multifunzione nel metodo CreateRibbonExtensibilityObject della classe ThisWorkbook di un progetto cartella di lavoro di Excel.

Per i progetti destinati a .NET Framework 4, aggiungere il codice seguente:

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    End If
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = false;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager( 
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[]
             { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { tempRibbon });
    }
}

Per i progetti destinati a .NET Framework 3.5, aggiungere il codice seguente:

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    End If
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = true;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
}

Proprietà che diventano di sola lettura

Nella tabella seguente vengono illustrate le proprietà che possono essere impostate solo prima del caricamento della barra multifunzione.

Nota

È possibile impostare le proprietà dei controlli nei menu dinamici in qualsiasi momento. In tal caso, questa tabella non è applicabile.

Proprietà	Classe del controllo della barra multifunzione
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
Dynamic	RibbonMenu
Global	OfficeRibbon
Groups	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Nome	RibbonComponent
Position	RibbonButton RibbonCheckBox RibbonGallery RibbonGroup RibbonMenu RibbonSeparator RibbonSplitButton RibbonTab RibbonToggleButton
RibbonType	OfficeRibbon
RowCount	RibbonGallery
ShowItemImage	RibbonComboBox RibbonDropDown RibbonGallery
ShowItemLabel	RibbonDropDown RibbonGallery
ShowItemSelection	RibbonGallery
SizeString	RibbonComboBox RibbonDropDown RibbonEditBox
StartFromScratch	OfficeRibbon
Tabs	OfficeRibbon
Titolo	RibbonSeparator

Impostazione di proprietà per barre multifunzione che sono visualizzate nei controlli Outlook

Una nuova istanza della barra multifunzione viene creata ogni volta che un utente apre un controllo in cui viene visualizzata la barra multifunzione. Tuttavia, le proprietà elencate nella precedente tabella possono essere impostate solo prima della creazione della prima istanza della barra multifunzione. Una volta creata la prima istanza, queste proprietà diventano di sola lettura perché la prima istanza definisce il file XML utilizzato da Outlook per caricare la barra multifunzione.

Questo codice risulta inefficace se una logica condizionale imposta una proprietà su un valore diverso quando vengono create altre istanze della barra multifunzione.

Nota

Assicurarsi che la proprietà Name sia impostata per ogni controllo che si aggiunge a una barra multifunzione di Outlook. Se in fase di esecuzione si aggiunge un controllo a una barra multifunzione di Outlook, è necessario impostare questa proprietà nel codice. Se in fase di esecuzione si aggiunge un controllo a una barra multifunzione di Outlook, la proprietà Name viene impostata automaticamente.

Eventi del controllo della barra multifunzione

Ogni classe di controllo contiene uno o più eventi. Nella tabella riportata di seguito vengono descritti gli eventi.

Evento	Descrizione
Click	Si verifica quando si seleziona con il mouse un controllo.
TextChanged	Si verifica quando il testo di una casella di modifica o di una casella combinata viene modificato.
ItemsLoading	Si verifica quando l'insieme Items del controllo è richiesto da Office. Office memorizza nella cache l'insieme Items fino a che il codice non modifica le proprietà del controllo o il metodo IRibbonUI.InvalidateControl(String) non viene chiamato.
ButtonClick	Si verifica quando si seleziona con il mouse un pulsante in un controllo RibbonGallery o RibbonDropDown.
SelectionChanged	Si verifica quando cambia la selezione in un controllo RibbonDropDown o RibbonGallery.
DialogLauncherClick	Si verifica quando si seleziona con il mouse l'icona dell'utilità di avvio della finestra di dialogo nell'angolo inferiore destro di un gruppo.

I gestori di questi eventi hanno i seguenti due parametri.

Parametro	Descrizione
sender	Un oggetto Object che rappresenta il controllo che ha generato l'evento.
e	Oggetto RibbonControlEventArgs che contiene Microsoft.Office.Core.IRibbonControl. Utilizzare questo controllo per accedere a qualsiasi proprietà non disponibile nel modello a oggetti della barra multifunzione fornito da Runtime di Visual Studio Tools per Office.

Vedere anche

Condividi tramite