Vue d'ensemble du modèle objet de ruban

Article
03/04/2013

Visual Studio Tools pour Office Runtime expose un modèle objet fortement typé que vous pouvez utiliser pour obtenir et définir les propriétés du ruban contrôle au moment de l'exécution.Par exemple, vous pouvez remplir dynamiquement des contrôles de menu ou afficher et masquer des contrôles en fonction du contexte.Vous pouvez également ajouter des onglets, des groupes, et des contrôles à un ruban, mais avant que le ruban soit chargé par l'application Office.Pour plus d'informations, consultez Définition de propriétés qui passent en lecture seule.

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.

Ce modèle objet de ruban se compose principalement de la classe du ruban, des événements du ruban et des classes de contrôle du ruban.

Classe du ruban

Lorsque vous ajoutez un nouvel élément ruban (concepteur visuel) à un projet, Visual Studio ajoute une classe d' Ribbon à votre projet.La classe Ribbon hérite de la classe RibbonBase.

Cette classe apparaît comme une classe partielle répartie entre le fichier de code du ruban et le fichier de code du Concepteur de ruban.

Événements du ruban

La classe d' Ribbon contient les trois événements suivants :

Événement	Description
RibbonBase.Load	Déclenché lorsque l'application Office charge la personnalisation de ruban.Le gestionnaire d'événements d' Load est ajouté automatiquement au fichier de code du ruban.Utilisez ce gestionnaire d'événements pour exécuter du code personnalisé lors de le chargement du ruban.
RibbonBase.LoadImage	Vous permet de mettre en cache des images dans la personnalisation du ruban lors de le chargement du ruban.Vous pouvez obtenir un léger gain de performances si vous écrivez du code pour mettre en cache des images de ruban dans ce gestionnaire d'événements.Pour plus d’informations, consultez LoadImage.
RibbonBase.Close	Déclenché lorsque l'instance de ruban se ferme.

Contrôles du ruban

L'espace de noms Microsoft.Office.Tools.Ribbon contient un type pour chaque contrôle inclus dans le groupe Contrôles de ruban Office de la Boîte à outils.

Le tableau suivant indique le type de chaque contrôle d' Ribbon .Pour obtenir une description de chaque contrôle, consultez Vue d'ensemble du ruban.

Nom du contrôle	Nom de classe
Box	RibbonBox
Button	RibbonButton
Buttongroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Gallery	RibbonGallery
Groupe	RibbonGroup
Étiquette	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Onglet	RibbonTab
ToggleButton	RibbonToggleButton

L'espace de noms Microsoft.Office.Tools.Ribbon utilise le préfixe « Ribbon » pour ces types afin d'éviter une collision de nom avec les classes de contrôle de l'espace de noms System.Windows.Forms.

Lorsque vous ajoutez un contrôle au Concepteur de ruban, ce dernier déclare la classe pour ce contrôle comme un champ dans son fichier de code.

Réalisation de tâches courantes à l'aide des propriétés des contrôles du ruban

Chaque contrôle d' Ribbon contient les propriétés que vous pouvez utiliser pour effectuer différentes tâches, telles que l'assignation d'une étiquette à un contrôle, ou masquer et afficher des contrôles.

Dans certains cas, les propriétés passent en lecture seule après le chargement du ruban ou après un contrôle est ajouté à un menu dynamique.Pour plus d'informations, consultez Définition de propriétés qui passent en lecture seule.

Le tableau suivant décrit certaines des tâches que vous pouvez exécuter à l'aide de les propriétés de contrôle d' Ribbon .

Pour cette tâche :	Procédez comme suit :
Masquer ou afficher un contrôle.	Utilisez la propriété Visible.
Activer ou désactiver un contrôle.	Utilisez la propriété Enabled.
Définir la taille d'un contrôle.	Utilisez la propriété ControlSize.
Obtenir l'image qui s'affiche sur un contrôle.	Utilisez la propriété Image.
Modifier l'étiquette d'un contrôle.	Utilisez la propriété Label.
Ajouter des données définies par l'utilisateur à un contrôle.	Utilisez la propriété Tag.
Obtenir les éléments d'un contrôle RibbonBox, RibbonDropDown, RibbonGallery ou RibbonSplitButton.	Utilisez la propriété Items.
Ajouter des éléments à un contrôle RibbonComboBox, RibbonDropDown ou RibbonGallery.	Utilisez la propriété Items.
Ajouter des contrôles à un RibbonMenu.	Utilisez la propriété Items. Pour ajouter des contrôles à RibbonMenu après que le ruban soit chargé dans l'application Office, vous devez définir la propriété d' Dynamic à true avant que le ruban soit chargé dans l'application Office.Pour plus d'informations, consultez Définition de propriétés qui passent en lecture seule.
Obtenir l'élément sélectionné d'un RibbonComboBox, RibbonDropDown ou RibbonGallery.	Utilisez la propriété SelectedItem.Pour un RibbonComboBox, utilisez la propriété Text.
Obtenir les groupes d'un RibbonTab.	Utilisez la propriété Groups.
Spécifier le nombre de lignes et de colonnes apparaissant dans un RibbonGallery.	Utilisez les propriétés RowCount et ColumnCount.

Définition de propriétés qui passent en lecture seule

Certaines propriétés peuvent être définies uniquement avant le chargement du ruban.Elles peuvent être définies depuis trois emplacements :

Dans la fenêtre Propriétés de Visual Studio.
Dans le constructeur de la classe d' Ribbon .
Dans la méthode CreateRibbonExtensibilityObject de la classe ThisAddin, ThisWorkbook ou ThisDocument de votre projet.

Les menus dynamiques comportent certaines exceptions.Vous pouvez créer de nouveaux contrôles, définir leurs propriétés, puis les ajouter à un menu dynamique au moment de l'exécution, même après que le ruban qui contient le menu est chargé.

Les propriétés des contrôles que vous ajoutez à un menu dynamique peuvent être définies à tout moment.

Pour plus d'informations, consultez Propriétés qui passent en lecture seule.

Définition des propriétés dans le constructeur du ruban

Vous pouvez définir les propriétés d'un contrôle d' Ribbon dans le constructeur de la classe d' Ribbon .Ce code doit apparaître après l'appel à la méthode InitializeComponent.L'exemple suivant ajoute un nouveau bouton à un groupe s'il est actuellement 17 heures (heure du Pacifique) (UTC-8) au moins.

Ajoutez le code ci-dessous.

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

Dans les projets visual C# que vous avez mis à niveau de Visual Studio 2008, le constructeur s'affiche dans le fichier de code du ruban.

Dans les projets Visual Basic, ou dans les projets visual C# que vous avez créé dans Visual Studio 2012, le constructeur s'affiche dans le fichier de code du concepteur de ruban.Ce fichier est nommé YourRibbonItem.Designer.cs ou YourRibbonItem.Designer.vb.Pour afficher ce fichier dans les projets Visual Basic, vous devez au préalable cliquer sur le bouton Afficher tous les fichiers de l'Explorateur de solutions.

Définition des propriétés dans la méthode CreateRibbonExtensibilityObject

Vous pouvez définir les propriétés d'un contrôle d' Ribbon lorsque vous remplacez la méthode d' CreateRibbonExtensibilityObject dans ThisAddin, ThisWorkbook, ou la classe d' ThisDocument de votre projet.Pour plus d'informations sur la méthode CreateRibbonExtensibilityObject, consultez Vue d'ensemble du ruban.

L'exemple suivant définit les propriétés du ruban dans la méthode d' CreateRibbonExtensibilityObject de classe d' ThisWorkbook d'un projet de classeur Excel.

Ajoutez le code ci-dessous.

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

Propriétés qui passent en lecture seule

Le tableau suivant décrit des propriétés qui peuvent être définies uniquement avant le chargement du ruban.

[!REMARQUE]

Vous pouvez définir à tout moment les propriétés des contrôles sur les menus dynamiques.Dans ce cas, le tableau suivant ne s'applique pas.

Propriété	Classe de contrôle du ruban
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
Dynamique	RibbonMenu
Global	OfficeRibbon
Groups	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Nom	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
Tabulations	OfficeRibbon
Titre	RibbonSeparator

Définition des propriétés des rubans qui apparaissent dans les Inspecteurs Outlook

Une nouvelle instance du ruban est créée chaque fois qu'un utilisateur ouvre un inspecteur dans lequel le ruban apparaît.Toutefois, vous pouvez définir les propriétés répertoriées dans le tableau ci-dessus uniquement avant la première instance du ruban est créée.Après la première instance créée, ces propriétés sont en lecture seule car la première instance définit le fichier XML qu'Outlook utilise pour charger le ruban.

Si vous avez une logique conditionnelle qui définit l'un de ces propriétés à une valeur différente lorsque d'autres instances du ruban sont créées, ce code n'aura aucun effet.

[!REMARQUE]

Assurez -vous que la propriété Nom est définie pour chaque contrôle que vous ajoutez à un ruban Outlook.Si vous ajoutez un contrôle à un ruban Outlook au moment de l'exécution, vous devez définir cette propriété dans votre code.Si vous ajoutez un contrôle à un ruban Outlook au moment de le design, la propriété d' Name est définie automatiquement.

Événements de contrôle du ruban

Chaque classe de contrôle contient un ou plusieurs événements.Le tableau suivant décrit ces événements.

Événement	Description
Click	Se produit suite à un clic sur un contrôle.
TextChanged	Se produit lors de la modification du texte d'une zone d'édition ou d'une zone de liste déroulante.
ItemsLoading	Se produit lorsqu'Office demande la collection Items du contrôle.Office met la collection Items en cache jusqu'à ce que votre code modifie les propriétés du contrôle ou que vous appeliez la méthode IRibbonUI.InvalidateControl.
ButtonClick	Se produit suite à un clic sur un bouton dans un contrôle RibbonGallery ou RibbonDropDown.
SelectionChanged	Se produit lors de la modification de la sélection d'un RibbonDropDown ou d'un RibbonGallery.
DialogLauncherClick	Se produit suite à un clic sur l'icône du lanceur de boîte de dialogue dans l'angle inférieur droit d'un groupe.

Les gestionnaires d'événements pour ces événements présentent les deux paramètres suivants.

Paramètre	Description
sender	Object qui représente le contrôle qui a déclenché l'événement.
e	RibbonControlEventArgs qui contient Microsoft.Office.Core.IRibbonControl.Utilisez ce contrôle pour accéder à des propriétés qui ne sont pas disponibles dans le modèle objet de ruban fourni par le Visual Studio Tools pour Office Runtime.

Voir aussi

Partager via