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:

Evento	Descrizione
Load	Generato quando il app Office lication carica la personalizzazione della barra multifunzione. Il Load gestore eventi viene aggiunto automaticamente al file di codice della barra multifunzione. Usare questo gestore eventi per eseguire codice personalizzato al caricamento della barra multifunzione.
LoadImage	Consente di memorizzare nella cache le immagini nella personalizzazione della barra multifunzione quando viene caricata la barra multifunzione. È possibile ottenere un lieve miglioramento delle prestazioni se si scrive codice per memorizzare nella cache le immagini della barra multifunzione in questo gestore eventi. Per ulteriori informazioni, vedere LoadImage.
Close	Generato quando l'istanza della barra multifunzione viene chiusa.

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.

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

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.

Per questa attività:	Eseguire questa operazione:
Nascondere o visualizzare 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.
Ottiene l'immagine 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 RibbonBoxoggetto , RibbonDropDown, RibbonGalleryo RibbonSplitButton Controllo.	Utilizzare la proprietà Items.
Aggiungere elementi a un RibbonComboBoxcontrollo , RibbonDropDowno RibbonGallery .	Utilizzare la proprietà Items.
Aggiungere controlli a un oggetto RibbonMenu.	Utilizzare la proprietà Items. Per aggiungere controlli all'oggetto RibbonMenu dopo il caricamento della barra multifunzione nella app Office lication, è necessario impostare la Dynamic proprietà su true prima che la barra multifunzione venga caricata nella app Office lication. Per informazioni, vedere Impostare le proprietà che diventano di sola lettura.
Ottiene l'elemento selezionato di un oggetto RibbonComboBox, RibbonDropDownRibbonGalleryo .	Utilizzare la proprietà SelectedItem. Per un RibbonComboBoxoggetto , utilizzare la Text proprietà .
Ottenere i gruppi in un oggetto RibbonTab.	Usare la proprietà Groups.
Specificare il numero di righe e colonne visualizzate in un oggetto RibbonGallery.	Usare le RowCount proprietà e ColumnCount .

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.

C#

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

VB

<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.

C#

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

VB

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.

Nota

È possibile impostare le proprietà dei controlli nei menu dinamici in qualsiasi momento. Questa tabella non si applica in tal caso.

Proprietà	Classe di controllo della barra multifunzione
BoxStyle	RibbonBox
Buttontype	RibbonSplitButton
Columncount	RibbonGallery
Controlid	RibbonTab
DialogLauncher	RibbonGroup
Dinamico	RibbonMenu
Global	OfficeRibbon
Gruppi	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Nome	RibbonComponent
Posizione	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
Schede	OfficeRibbon
Title	RibbonSeparator

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.

Nota

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

Eventi di controllo della barra multifunzione

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

Evento	Descrizione
Clic	Si verifica quando si fa clic su un controllo .
Textchanged	Si verifica quando viene modificato il testo di una casella di modifica o di una casella combinata.
ItemsLoading	Si verifica quando l'insieme Items del controllo viene richiesto da Office. Office memorizza nella cache l'insieme Items fino a quando il codice non modifica le proprietà del controllo oppure viene chiamato il InvalidateControl metodo .
Buttonclick	Si verifica quando si fa clic su un pulsante in un RibbonGallery oggetto o RibbonDropDown .
SelectionChanged	Si verifica quando la selezione in un RibbonDropDown oggetto o RibbonGallery viene modificata.
DialogLauncherClick	Si verifica quando si fa clic sull'icona dell'icona di avvio della finestra di dialogo nell'angolo in basso a destra di un gruppo.

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

Parametro	Descrizione
Mittente	Oggetto Object che rappresenta il controllo che ha generato l'evento.
e	Oggetto RibbonControlEventArgs che contiene IRibbonControl. Usare questo controllo per accedere a qualsiasi proprietà non disponibile nel modello a oggetti della barra multifunzione fornito dal Strumenti di Visual Studio per il runtime di Office.

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