Cenni preliminari sul modello a oggetti della barra multifunzione

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:

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.

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.

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.

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.

Eventi del controllo della barra multifunzione

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

I gestori di questi eventi hanno i seguenti due parametri.

Vedere anche

Attività

Procedura: iniziare a personalizzare la barra multifunzione

Procedura dettagliata: creazione di una scheda personalizzata utilizzando la finestra di progettazione della barra multifunzione

Procedura dettagliata: aggiornamento dei controlli di una barra multifunzione in fase di esecuzione

Procedura: personalizzare una scheda incorporata

Procedura: personalizzare il menu Microsoft Office

Procedura: esportare una barra multifunzione dalla finestra di progettazione in un elemento XML della barra

Procedura: visualizzare gli errori dell'interfaccia utente del componente aggiuntivo

Riferimenti

Microsoft.Office.Tools.Ribbon

Concetti

Accesso alla barra multifunzione in fase di esecuzione

Finestra di progettazione della barra multifunzione

Personalizzazione di una barra multifunzione per Outlook

Altre risorse

Cenni preliminari sulla barra multifunzione