Cenni preliminari sul modello a oggetti della barra multifunzione

Articolo
02/19/2013

Runtime di Visual Studio Tools per Office espone un modello a oggetti fortemente tipizzato per ottenere e impostare le proprietà 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 possibile aggiungere schede, gruppi e controlli a una barra multifunzione, ma solo prima della barra multifunzione viene caricato 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 2013, Excel 2010, InfoPath 2013, InfoPath 2010, Outlook 2013, Outlook 2010, PowerPoint 2013, PowerPoint 2010, Project 2013, Project 2010, Visio 2013, Visio 2010, Word 2013, 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, Visual Studio aggiunge una classe Ribbon al progetto.La classe Ribbon eredita dalla classe RibbonBase.

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:

Evento	Descrizione
RibbonBase.Load	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 eseguire il codice personalizzato al caricamento della barra multifunzione.
RibbonBase.LoadImage	Consente di memorizzare nella cache immagini della personalizzazione della barra multifunzione al caricamento della barra multifunzione.È possibile ottenere un lieve miglioramento delle prestazioni se si scrive codice per memorizzare le immagini della barra multifunzione in questo gestore eventi.Per ulteriori informazioni, vedere LoadImage.
RibbonBase.Close	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.

La tabella seguente sono indicati il tipo per ogni controllo Ribbon.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
Separatore	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 Ribbon contiene proprietà che è possibile utilizzare per eseguire varie attività, come assegnare un'etichetta a un controllo, o nascondere e mostrare i 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 seguente vengono descritte alcune attività che è possibile eseguire utilizzando le proprietà del controllo Ribbon.

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 a 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, impostare le proprietà e aggiungerli quindi a un menu dinamico in fase di esecuzione, anche dopo la barra multifunzione contenente il menu viene caricata.

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

Impostare le proprietà di un controllo Ribbon 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.

Aggiungere il codice riportato di seguito.

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

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

Nei progetti di Visual Basic., o nei progetti visual C# creati in Visual Studio 2012, 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

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

Le proprietà seguenti di esempio della barra multifunzione di set nel metodo CreateRibbonExtensibilityObject della classe ThisWorkbook di progetto cartella di lavoro di Excel.

Aggiungere il codice riportato di seguito.

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

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, è possibile impostare le proprietà elencate nella tabella precedente solo prima della prima istanza della barra multifunzione venga creata.Una volta creata la prima istanza, queste proprietà diventano di sola lettura perché la prima istanza definisce il file XML che Outlook utilizza per caricare la barra multifunzione.

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

[!NOTA]

Assicurarsi che la proprietà Nome viene impostata per ogni controllo che si aggiunge 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 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 la raccolta Items del controllo è richiesto da Office.Office memorizza nella cache la raccolta Items fino a che il codice non modifica le proprietà del controllo o il metodo IRibbonUI.InvalidateControl 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