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.

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

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

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.