Élément XML Ribbon

Article
03/04/2013

L'élément Ruban (XML) vous permet de personnaliser un ruban en utilisant XML.Utilisez l'élément Ruban (XML) si vous souhaitez personnaliser le ruban de sorte que l'élément Ruban (Concepteur visuel) ne le prenne pas en charge.Pour comparer ce que vous pouvez faire avec chaque élément, consultez Vue d'ensemble du ruban.

S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau document et de niveau application pour les applications suivantes : Excel 2013 et Excel 2010 ; InfoPath 2013 et InfoPath 2010 ; Outlook 2013 et Outlook 2010 ; PowerPoint 2013 et PowerPoint 2010 ; Project 2013 et Project 2010 ; Visio 2013 et Visio 2010 ; Word 2013 et Word 2010. Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Ajout d'un élément Ruban (XML) à un projet

Vous pouvez ajouter un élément Ruban (XML) à tout projet Office depuis la boîte de dialogue Ajouter un nouvel élément.Visual Studio ajoute automatiquement les fichiers suivants à votre projet :

Un fichier XML du ruban.Ce fichier définit l'interface utilisateur du ruban.Utilisez ce fichier pour ajouter des éléments d'interface utilisateur tels que des onglets, des groupes et des contrôles.Pour plus d'informations, consultez Référence de fichier XML du ruban plus loin dans cette rubrique.
Un fichier de code du ruban.Ce fichier contient la classe du ruban.Cette classe porte le nom que vous avez spécifié pour l'élément Ruban (XML) dans la boîte de dialogue Ajouter un nouvel élément.Les applications Microsoft Office utilisent une instance de cette classe pour charger le ruban personnalisé.Pour plus d'informations, consultez Référence de classe du ruban plus loin dans cette rubrique.

Par défaut, ces fichiers ajoutent un groupe personnalisé à l'onglet Compléments dans le ruban.

Affichage du ruban personnalisé dans une application Microsoft Office

Après avoir ajouté un élément Ruban (XML) à votre projet, vous devez ajouter du code à la classe ThisAddin, ThisWorkbook ou ThisDocument qui substitue la méthode CreateRibbonExtensibilityObject et retourne la classe Ribbon XML à l'application Office.

L'exemple de code suivant substitue la méthode CreateRibbonExtensibilityObject et retourne une classe Ribbon XML nommée 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();
}

Définition du comportement du ruban personnalisé

Vous pouvez répondre aux actions de l'utilisateur, par exemple un clic de bouton sur le ruban, en créant des méthodes de rappel.Les méthodes de rappel ressemblent aux événements dans les contrôles Windows Forms, mais elles sont identifiées par un attribut dans le XML de l'élément d'interface utilisateur.Vous écrivez des méthodes dans la classe du ruban et un contrôle appelle la méthode qui porte le même nom que la valeur d'attribut.Par exemple, vous pouvez créer une méthode de rappel qui est appelée lorsqu'un utilisateur clique sur un bouton dans le ruban.Deux étapes sont obligatoires pour créer une méthode de rappel :

Assigner un attribut à un contrôle dans le fichier XML du ruban qui identifie une méthode de rappel dans votre code.
Définir la méthode de rappel dans la classe du ruban.

[!REMARQUE]

Outlook requiert une étape supplémentaire.Pour plus d’informations, consultez Personnalisation d'un ruban pour Outlook.

Pour obtenir une procédure pas à pas sur l'automatisation d'une application à partir du ruban, voir Procédure pas à pas : création d'un onglet personnalisé à l'aide d'un élément XML Ribbon.

Assignation de méthodes de rappel à des contrôles

Pour assigner une méthode de rappel à un contrôle dans le fichier XML du ruban, ajoutez un attribut indiquant le type et le nom de la méthode de rappel.Par exemple, l'élément suivant définit un bouton bascule ayant une méthode de rappel onAction appelée OnToggleButton1.

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

La méthode onAction est appelée lorsque l'utilisateur exécute la tâche principale associée à un contrôle spécifique.Par exemple, la méthode de rappel onAction d'un bouton bascule est appelée lorsque l'utilisateur clique sur ce bouton.

La méthode que vous indiquez dans l'attribut peut avoir n'importe quel nom.Toutefois, son nom doit correspondre à celui de la méthode que vous définissez dans le fichier de code du ruban.

Il existe plusieurs types différents de méthodes de rappel que vous pouvez assigner aux contrôles du ruban.Pour une liste complète des méthodes de rappel disponibles pour chaque contrôle, consultez l'article technique Personnalisation de l'interface utilisateur du Ruban d'Office (2007) pour les développeurs (Partie 3 sur 3).

Définition des méthodes de rappel

Définissez vos méthodes de rappel dans la classe du ruban dans le fichier de code du ruban.Une méthode de rappel a plusieurs conditions requises :

Elle doit être déclarée comme publique.
Son nom doit correspondre au nom d'une méthode de rappel que vous avez assignée à un contrôle dans le fichier XML du ruban.
Sa signature doit correspondre à la signature d'un type de méthode de rappel disponible pour le contrôle du ruban associé.

Pour obtenir une liste complète des signatures de méthode de rappel pour les contrôles de ruban, consultez l'article technique Personnalisation de l'interface utilisateur du ruban Office (2007) pour les développeurs (troisième partie) (page éventuellement en anglais).Visual Studio ne prend pas en charge IntelliSense pour les méthodes de rappel que vous créez dans le fichier code du ruban.Si vous créez une méthode de rappel qui ne correspond pas à une signature valide, le code est compilé mais rien ne se produit lorsque l'utilisateur clique sur le contrôle.

Toutes les méthodes de rappel ont un paramètre Microsoft.Office.Core.IRibbonControl représentant le contrôle qui a appelé la méthode.Vous pouvez utiliser ce paramètre afin de réutiliser la même méthode de rappel pour plusieurs contrôles.L'exemple de code suivant présente une méthode de rappel onAction qui exécute différentes tâches en fonction du contrôle sur lequel l'utilisateur clique.

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

Référence de fichier XML du ruban

Vous pouvez définir votre ruban personnalisé en ajoutant des éléments et des attributs au fichier XML du ruban.Par défaut, le fichier XML du ruban contient le code XML suivant.

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

Le tableau suivant décrit les éléments par défaut dans le fichier XML du ruban.

Élément	Description
customUI	Représente le ruban personnalisé dans le projet de complément.
ribbon	Représente le ruban.
tabs	Représente un ensemble d'onglets du ruban.
tab	Représente un seul onglet du ruban.
group	Représente un groupe de contrôles dans l'onglet du ruban.

Ces éléments ont des attributs qui spécifient l'apparence et le comportement du ruban personnalisé.Le tableau suivant décrit les attributs par défaut dans le fichier XML du ruban.

Attribut	Élément parent	Description
onLoad	customUI	Identifie une méthode appelée lorsque l'application charge le ruban.
idMso	tab	Identifie un onglet intégré à afficher dans le ruban.
id	group	Identifie le groupe.
label	group	Spécifie le texte qui apparaît sur le groupe.

Les éléments et les attributs par défaut contenus dans le fichier XML du ruban sont un petit sous-ensemble des éléments et des attributs disponibles.Pour une liste complète des éléments et attributs disponibles, consultez l'article technique Personnalisation de l'interface utilisateur du Ruban d'Office (2007) pour les développeurs (Partie 2 sur 3).

Référence de classe du ruban

Visual Studio génère la classe du ruban dans le fichier de code du ruban.Ajoutez à cette classe les méthodes de rappel pour les contrôles du ruban.Cette classe implémente l'interface Microsoft.Office.Core.IRibbonExtensibility.

Le tableau suivant décrit les méthodes par défaut contenues dans cette classe.

Méthode	Description
GetCustomUI	Retourne le contenu du fichier XML du ruban.Les applications Microsoft Office appellent cette méthode pour obtenir une chaîne XML qui définit l'interface utilisateur de votre ruban personnalisé.Cette méthode implémente la méthode IRibbonExtensibility.GetCustomUI. Remarque La méthode GetCustomUI doit être implémentée uniquement pour retourner le contenu du fichier XML du ruban. Elle ne doit pas être utilisée pour initialiser votre complément.En particulier, vous ne devez pas essayer d'afficher des boîtes de dialogue ou d'autres fenêtres dans votre implémentation GetCustomUI.Sinon, le ruban personnalisé risque de ne pas fonctionner correctement.Si vous devez exécuter le code qui initialise votre complément, ajoutez le code au gestionnaire d'événements ThisAddIn_Startup.
OnLoad	Assigne le paramètre Microsoft.Office.Core.IRibbonControl au champ ribbon.Les applications Microsoft Office appellent cette méthode lorsqu'elles chargent le ruban personnalisé.Vous pouvez utiliser ce champ pour mettre à jour de manière dynamique le ruban personnalisé.Pour plus d'informations, consultez l'article technique Personnalisation de l'interface utilisateur du Ruban d'Office (2007) pour les développeurs (Partie 1 sur 3).
GetResourceText	Appelée par la méthode GetCustomUI pour obtenir le contenu du fichier XML du ruban.