Panoramica del modello a oggetti della barra multifunzione

Il runtime di Strumenti di Visual Studio per Office espone un modello a oggetti fortemente tipizzato che è possibile usare per ottenere e impostare le proprietà dei controlli della barra multifunzione in fase di esecuzione. Ad esempio, è possibile popolare in modo dinamico i controlli menu oppure visualizzare e nascondere i controlli contestualmente. È anche possibile aggiungere schede, gruppi e controlli a una barra multifunzione, ma solo prima che la barra multifunzione venga caricata dalla app Office lication. Per informazioni, vedere Impostare le proprietà che diventano di sola lettura.

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 le applicazioni seguenti: Excel; InfoPath 2013 e InfoPath 2010; Outlook; Powerpoint; Progetto; Visio; Parola. Per altre informazioni, vedere Funzionalità disponibili per app Office lication e tipo di progetto.

Questo modello a oggetti della barra multifunzione è costituito principalmente dalle classi di controllo ribbon, eventi della barra multifunzione e controllo barra multifunzione.

Classe ribbon

Quando si aggiunge un nuovo elemento della barra multifunzione (Progettazione visiva) a un progetto, Visual Studio aggiunge una classe Ribbon al progetto. La classe Ribbon eredita dalla RibbonBase classe .

Questa classe viene visualizzata come classe parziale divisa 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 Microsoft.Office.Tools.Ribbon spazio dei nomi contiene un tipo per ogni controllo visualizzato nel gruppo Controlli barra multifunzione di Office della casella degli strumenti.

Nella tabella seguente viene illustrato il tipo per ogni Ribbon controllo. Per una descrizione di ogni controllo, vedere Panoramica della barra multifunzione.

Lo Microsoft.Office.Tools.Ribbon spazio dei nomi usa il prefisso "Ribbon" per questi tipi per evitare un conflitto di nomi con i nomi delle classi di controllo nello spazio dei System.Windows.Forms nomi.

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

Attività comuni che usano le proprietà dei controlli della barra multifunzione

Ogni Ribbon controllo contiene proprietà che è possibile usare per eseguire varie attività, ad esempio l'assegnazione di un'etichetta a un controllo o la visualizzazione e la 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 altre informazioni, vedere Impostare le proprietà che diventano di sola lettura.

Nella tabella seguente vengono descritte alcune delle attività che è possibile eseguire usando Ribbon le proprietà del controllo.

Impostare le proprietà che diventano di sola lettura

Alcune proprietà possono essere impostate solo prima del caricamento della barra multifunzione. Esistono tre posizioni per impostare queste proprietà:

• Nella finestra Proprietà di Visual Studio.

• Nel costruttore della classe Ribbon .

• CreateRibbonExtensibilityObject Nel metodo della ThisAddinclasse , ThisWorkbooko ThisDocument del progetto.

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

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

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

Impostare le proprietà nel costruttore della barra multifunzione

È possibile impostare le proprietà di un Ribbon controllo nel costruttore della classe Ribbon . Questo codice deve essere visualizzato dopo la chiamata al InitializeComponent metodo . Nell'esempio seguente viene aggiunto un nuovo pulsante a un gruppo se l'ora corrente è 17.00 Ora Pacifico (UTC-8) o successiva.

Aggiungi il seguente codice.

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

<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

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

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

Impostare le proprietà nel metodo CreateRibbonExtensibilityObject

È possibile impostare le proprietà di un Ribbon controllo quando si esegue l'override ThisAddindel CreateRibbonExtensibilityObject metodo nella classe , ThisWorkbooko ThisDocument del progetto. Per altre informazioni sul metodo, vedere Panoramica della CreateRibbonExtensibilityObject barra multifunzione.

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

Aggiungi il seguente codice.

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

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

Proprietà che diventano di sola lettura

La tabella seguente mostra le proprietà che possono essere impostate solo prima del caricamento della barra multifunzione.

Impostare le proprietà per le barre multifunzione visualizzate nei controlli di Outlook

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

Se si dispone di una logica condizionale che imposta una di queste proprietà su un valore diverso quando vengono create altre istanze della barra multifunzione, questo codice non avrà alcun effetto.

Eventi di controllo della barra multifunzione

Ogni classe di controllo contiene uno o più eventi. Nella tabella seguente vengono descritti questi eventi.

I gestori eventi per questi eventi hanno i due parametri seguenti.

Contenuto correlato

• Accedere alla barra multifunzione in fase di esecuzione
• Panoramica della barra multifunzione
• Procedura: Introduzione alla personalizzazione della barra multifunzione
• Finestra di progettazione della barra multifunzione
• Procedura dettagliata: Creare una scheda personalizzata usando Progettazione barra multifunzione
• Procedura dettagliata: aggiornare i controlli in una barra multifunzione in fase di esecuzione
• Personalizzare una barra multifunzione per Outlook
• Procedura: Personalizzare una scheda predefinita
• Procedura: Aggiungere controlli alla visualizzazione Backstage
• Procedura: Esportare una barra multifunzione da Progettazione barra multifunzione a XML barra multifunzione
• Procedura: Visualizzare gli errori dell'interfaccia utente del componente aggiuntivo