Élément XML Ribbon

Article
04/28/2010

Mise à jour : novembre 2007

S'applique à
Les informations de cette rubrique s'appliquent uniquement aux projets Visual Studio Tools pour Office et aux versions de Microsoft Office spécifiés. Type de projet Projets au niveau du document Projets au niveau de l'application Version de Microsoft Office Excel 2007 Word 2007 Outlook 2007 PowerPoint 2007 Pour plus d'informations, voir Fonctionnalités disponibles par type d'application et de projet.

Les informations de cette rubrique s'appliquent uniquement aux projets Visual Studio Tools pour Office et aux versions de Microsoft Office spécifiés.

Type de projet

Projets au niveau du document
Projets au niveau de l'application

Version de Microsoft Office

Excel 2007
Word 2007
Outlook 2007
PowerPoint 2007

Pour plus d'informations, voir Fonctionnalités disponibles par type d'application et de projet.

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.

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

Vous pouvez ajouter un élément Ruban (XML) à tout projet Visual Studio Tools pour Office à partir de la boîte de dialogue Ajouter un nouvel élément. Visual Studio Tools pour Office 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 Ribbon1.

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 2007 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 la liste complète des signatures de méthode de rappel disponibles pour les contrôles de ruban, consultez l'article technique Personnalisation de l'interface utilisateur du Ruban d'Office (2007) pour les développeurs (Partie 3 sur 3). Visual Studio Tools pour Office ne fournit pas à IntelliSense la prise en charge des méthodes de rappel que vous créez dans le fichier de 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 Tools pour Office 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é. 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.

Voir aussi

Tâches

Procédure pas à pas : création d'un onglet personnalisé à l'aide d'un élément XML Ribbon

Concepts

Vue d'ensemble du ruban

Personnalisation de l'interface utilisateur Office

Partager via