Cenni preliminari sul modello a oggetti della barra multifunzione

Aggiornamento: Luglio 2008

Visual Studio Tools per Office espone 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.

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 Tools per Office aggiunge al progetto una classe che 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 OfficeRibbon contiene i seguenti tre eventi:

• Load

• LoadImage

• Close

L'evento 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 l'esecuzione di codice personalizzato al caricamento della barra multifunzione.

L'evento LoadImage consente di memorizzare nella cache immagini della personalizzazione della barra multifunzione al caricamento della barra multifunzione. Scrivendo il codice per memorizzare nella cache le immagini della barra multifunzione in questo gestore eventi, si ottiene un leggero miglioramento delle prestazioni. Per ulteriori informazioni, vedere LoadImage.

L'evento Close viene generato quando l'istanza della barra multifunzione viene chiusa.

Classi di controlli della barra multifunzione

Lo spazio dei nomi Microsoft.Office.Tools.Ribbon contiene una classe Ribbon per ogni controllo presente nel gruppo Controlli barra multifunzione di Office della Casella degli strumenti.

Nella tabella riportata di seguito viene illustrata la classe 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 queste classi 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 utilizzando le proprietà delle classi di controlli della barra multifunzione

Ogni classe di 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 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.

A partire da Visual Studio 2008 Service Pack 1 (SP1), è possibile impostare le proprietà di controlli aggiunti a un menu dinamico in qualsiasi momento. Tuttavia, se SP1 non è installato, alcune proprietà diventano di sola lettura dopo l'aggiunta del controllo al menu.

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.

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

}

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 seguente vengono impostate le proprietà della barra multifunzione nel metodo CreateRibbonExtensibilityObject della classe ThisWorkbook di un progetto cartella di lavoro di Excel 2007.

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.

Nota:
Se si installa SP1, è possibile impostare in qualsiasi momento le proprietà dei controlli nei menu dinamici. In tal caso, questa tabella non è applicabile.

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.

Nota:
Assicurarsi che la proprietà Name sia impostata per ogni controllo che si aggiunge a una barra multifunzione di Outlook. Se in fase di esecuzione si aggiunge un controllo a una barra multifunzione di Outlook, è necessario impostare questa proprietà nel codice. Se in fase di esecuzione si aggiunge un controllo a una barra multifunzione di Outlook, 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.

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 a un elemento XML della barra

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

Concetti

Accesso alla barra multifunzione in fase di esecuzione

Cenni preliminari sulla barra multifunzione

Finestra di progettazione della barra multifunzione

Personalizzazione di una barra multifunzione per Outlook

Riferimenti

Microsoft.Office.Tools.Ribbon

Cronologia delle modifiche