Elemento XML della barra multifunzione

Articolo
08/11/2011

L'elemento barra multifunzione (XML) consente di personalizzare una barra multifunzione utilizzando XML. Utilizzare l'elemento barra multifunzione (XML) se si desidera personalizzare la barra multifunzione in un modo non supportato dall'elemento barra multifunzione (finestra di progettazione visiva). Per un confronto delle operazioni eseguibili con ogni elemento, vedere Cenni preliminari sulla barra multifunzione.

Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di documento e di applicazione per Excel 2007, Excel 2010, InfoPath 2010, Outlook 2007, Outlook 2010, PowerPoint 2007, PowerPoint 2010, Project 2010, Visio 2010, Word 2007 e Word 2010. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

Aggiunta di un elemento barra multifunzione (XML) a un progetto

È possibile aggiungere un elemento barra multifunzione (XML) a qualsiasi progetto di Office dalla finestra di dialogo Aggiungi nuovo elemento. In Visual Studio vengono aggiunti automaticamente al progetto i file seguenti:

Un file XML della barra multifunzione vuoto. Tale file definisce l'interfaccia utente (UI) della barra multifunzione. Utilizzarlo per aggiungere elementi dell'interfaccia utente quali schede, gruppi e controlli. Per i dettagli, vedere Riferimento al file XML della barra multifunzione più avanti in questo argomento.
Un file di codice della barra multifunzione. Tale file contiene la classe Ribbon Questa classe ha il nome specificato per l'elemento barra multifunzione (XML) nella finestra di dialogo Aggiungi nuovo elemento. Le applicazioni di Microsoft Office utilizzano un'istanza di questa classe per caricare l'interfaccia utente della barra multifunzione personalizzata. Per i dettagli, vedere Riferimento alla classe Ribbon più avanti in questo argomento.

Per impostazione predefinita, tali file aggiungono un gruppo personalizzato alla scheda Componenti aggiuntivi della barra multifunzione.

Visualizzazione della barra multifunzione personalizzata in un'applicazione Microsoft Office

Dopo avere aggiunto un elemento barra multifunzione (XML) al progetto, è necessario aggiungere il codice alla classe ThisAddin, ThisWorkbook o ThisDocument che esegue l'override del metodo CreateRibbonExtensibilityObject e restituisce la classe Ribbon XML all'applicazione di Office.

Nell'esempio di codice seguente viene eseguito l'override del metodo CreateRibbonExtensibilityObject e restituita una classe Ribbon XML denominata MyRibbon.

Protected Overrides Function CreateRibbonExtensibilityObject() As  _
Microsoft.Office.Core.IRibbonExtensibility
    Return New MyRibbon()
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

Definizione del comportamento della barra multifunzione personalizzata

È possibile rispondere alle azioni degli utenti, ad esempio la selezione di un pulsante mediante clic nella barra multifunzione, creando metodi di callback. Questi ultimi sono simili agli eventi dei controlli Windows Form, ma sono identificati da un attributo nel codice XML dell'elemento UI. I metodi vengono scritti nella classe Ribbon e un controllo chiama il metodo che ha lo stesso nome del valore dell'attributo. È ad esempio possibile scrivere un metodo callback che viene chiamato quando un utente fa clic su un pulsante della barra multifunzione. Per la creazione di un metodo callback è necessario eseguire due passaggi:

Assegnare un attributo a un controllo nel file XML della barra multifunzione che identifichi un metodo callback nel codice.
Definire il metodo callback nella classe Ribbon.

Nota

Outlook richiede un ulteriore passaggio. Per ulteriori informazioni, vedere Personalizzazione di una barra multifunzione per Outlook.

Per una procedura dettagliata che illustri come automatizzare un'applicazione dalla barra multifunzione, vedere Procedura dettagliata: creazione di una scheda personalizzata utilizzando l'elemento XML della barra multifunzione.

Assegnazione di metodi callback ai controlli

Per assegnare un metodo callback a un controllo nel file XML della barra multifunzione, aggiungere un attributo che specifichi il tipo e il nome di tale metodo. L'elemento seguente definisce, ad esempio, un interruttore con un metodo callback onAction denominato OnToggleButton1.

<toggleButton id="toggleButton1" onAction="OnToggleButton1" />

onAction viene chiamato quando l'utente esegue l'attività principale associata a un controllo particolare. Il metodo callback onAction di un interruttore viene, ad esempio, chiamato quando l'utente fa clic sul pulsante.

Il metodo specificato nell'attributo può avere un nome qualsiasi, ma è necessario che corrisponda al nome del metodo definito nel file di codice della barra multifunzione.

Esistono molti tipi differenti di metodi callback che è possibile assegnare ai controlli della barra multifunzione. Per un elenco completo dei metodi callback disponibili per ogni controllo, vedere l'articolo tecnico Customizing the Office (2007) Ribbon User Interface for Developers (Part 3 of 3) (informazioni in lingua inglese).

Definizione dei metodi callback

Definire i metodi callback nella classe Ribbon all'interno del file di codice della barra multifunzione. Un metodo callback presenta diversi requisiti:

Deve essere dichiarato public.
Il nome deve corrispondere a quello di un metodo callback assegnato a un controllo nel file XML della barra multifunzione.
La firma deve corrispondere a quella di un tipo di metodo callback disponibile per il controllo della barra multifunzione associato.

Per un elenco completo delle firme dei metodi di callback disponibili per i controlli Ribbon, vedere l'articolo tecnico relativo alla personalizzazione dell'interfaccia utente della barra multifunzione di Office (2007) per gli sviluppatori (Parte 3 di 3) (la pagina potrebbe essere in inglese). Visual Studio non fornisce supporto IntelliSense per i metodi di callback creati nel file di codice della barra multifunzione. Se si crea un metodo di callback che non corrisponde a una firma valida, il codice verrà compilato comunque ma non accadrà nulla in seguito alla selezione del controllo.

Tutti i metodi callback dispongono di un parametro Microsoft.Office.Core.IRibbonControl che rappresenta il controllo che ha chiamato il metodo. È possibile utilizzare questo parametro per riutilizzare lo stesso metodo callback per più controlli. Nell'esempio di codice seguente viene illustrato un metodo callback onAction che esegue attività differenti a seconda del controllo selezionato dall'utente.

Public Sub OnActionCallback(ByVal control As Office.IRibbonControl, _
    ByVal isPressed As Boolean)

    If (control.Id = "checkBox1") Then
        MessageBox.Show("You clicked " + control.Id)
    Else
        MessageBox.Show("You clicked a different control.")
    End If

End Sub

public void OnActionCallback(Office.IRibbonControl control, bool isPressed)
{
    if (control.Id == "checkBox1")
    {
        MessageBox.Show("You clicked " + control.Id);
    }
    else
    {
        MessageBox.Show("You clicked a different control.");
    }
}

Riferimento al file XML della barra multifunzione

È possibile definire l'interfaccia utente della barra multifunzione personalizzata aggiungendo elementi e attributi al file XML della barra. Per impostazione predefinita, tale file contiene il codice XML seguente:

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="https://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">
  <ribbon>
    <tabs>
      <tab idMso="TabAddIns">
        <group id="MyGroup"
               label="My Group">
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

Nella tabella seguente sono descritti gli elementi predefiniti contenuti nel file XML della barra multifunzione.

Elemento	Descrizione
customUI	Rappresenta l'interfaccia utente della barra multifunzione personalizzata nel progetto Componente aggiuntivo.
ribbon	Rappresenta la barra multifunzione.
tabs	Rappresenta un insieme di schede della barra multifunzione.
tab	Rappresenta una singola scheda della barra multifunzione.
group	Rappresenta un gruppo di controlli nella scheda della barra multifunzione.

Questi elementi dispongono di attributi che specificano l'aspetto e il comportamento dell'interfaccia utente della barra multifunzione personalizzata. Nella tabella seguente sono descritti gli attributi predefiniti contenuti nel file XML della barra multifunzione.

Attributo	Elemento padre	Descrizione
onLoad	customUI	Identifica un metodo che viene chiamato in seguito al caricamento della barra multifunzione nell'applicazione.
idMso	tab	Identifica una scheda incorporata da visualizzare nell'interfaccia utente della barra multifunzione.
id	group	Identifica il gruppo.
label	group	Specifica il testo che viene visualizzato nel gruppo.

Gli elementi e gli attributi predefiniti del file XML della barra multifunzione rappresentano sottoinsiemi ridotti degli elementi e degli attributi disponibili. Per un elenco completo degli elementi e degli attributi disponibili, vedere l'articolo tecnico Customizing the Office (2007) Ribbon User Interface for Developers (Part 2 of 3) (informazioni in lingua inglese).

Riferimento alla classe Ribbon

Visual Studio genera la classe Ribbon nel file del codice della barra multifunzione. Aggiungere a questa classe i metodi di callback per i controlli sulla barra multifunzione. Questa classe implementa l'interfaccia Microsoft.Office.Core.IRibbonExtensibility.

Nella tabella seguente sono descritti i metodi predefiniti di questa classe.

Metodo	Descrizione
GetCustomUI	Restituisce il contenuto del file XML della barra multifunzione. Le applicazioni di Microsoft Office chiamano questo metodo per ottenere una stringa XML che definisce l'interfaccia utente della barra multifunzione personalizzata. Questo metodo implementa il metodo IRibbonExtensibility.GetCustomUI(String). Nota GetCustomUI deve essere implementato solo per restituire il contenuto del file XML della barra multifunzione e non per inizializzare il componente aggiuntivo.In particolare, si consiglia di non tentare di visualizzare le finestre di dialogo o altre finestre nell'implementazione GetCustomUI.In caso contrario, l'interfaccia utente della barra multifunzione personalizzata non funzionerà correttamente.Se è necessario eseguire codice che inizializza il componente aggiuntivo, aggiungerlo al gestore eventi ThisAddIn_Startup.
OnLoad	Assegna il parametro Microsoft.Office.Core.IRibbonControl al campo ribbon. Le applicazioni di Microsoft Office chiamano questo metodo quando caricano l'interfaccia utente della barra multifunzione personalizzata. È possibile utilizzare questo campo per aggiornare dinamicamente l'interfaccia utente della barra multifunzione personalizzata. Per ulteriori informazioni, vedere l'articolo tecnico Customizing the Office (2007) Ribbon User Interface for Developers (Part 1 of 3) (informazioni in lingua inglese).
GetResourceText	Chiamato dal metodo GetCustomUI per ottenere il contenuto del file XML della barra multifunzione.