Vue d'ensemble du modèle objet de ruban
Mise à jour : Juillet 2008
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
Version de Microsoft Office
Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet. |
Visual Studio Tools pour Office expose un modèle objet fortement typé que vous pouvez utiliser pour obtenir et définir les propriétés de contrôles de ruban 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 uniquement avant le chargement du ruban par l'application Office. Pour plus d'informations, consultez Définition de propriétés qui passent en lecture seule.
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 Tools pour Office ajoute à votre projet une classe qui hérite de la classe OfficeRibbon.
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 OfficeRibbon contient les trois événements suivants :
L'événement Load est déclenché lorsque l'application Office charge la personnalisation du ruban. Le gestionnaire d'événements Load est ajouté automatiquement au fichier de code du ruban. Utilisez ce gestionnaire d'événements pour exécuter du code personnalisé lors du chargement du ruban.
L'événement LoadImage vous permet de mettre en cache des images dans la personnalisation du ruban lors du chargement du ruban. Vous améliorerez légèrement les performances en écrivant du code pour mettre en cache les images du ruban dans ce gestionnaire d'événements. Pour plus d'informations, consultez LoadImage.
L'événement Close est déclenché à la fermeture de l'instance du ruban.
Classes de contrôle du ruban
L'espace de noms Microsoft.Office.Tools.Ribbon contient une classe de ruban pour chaque contrôle visible dans le groupe Contrôles de ruban Office de la Boîte à outils.
Le tableau suivant décrit la classe de chaque contrôle de ruban. Pour obtenir une description de chaque contrôle, consultez Vue d'ensemble du ruban.
Nom du contrôle |
Nom de la classe |
|---|---|
Box |
|
Button |
|
Buttongroup |
|
CheckBox |
|
ComboBox |
|
DropDown |
|
EditBox |
|
Gallery |
|
Group |
|
Label |
|
Menu |
|
Separator |
|
SplitButton |
|
Tab |
|
ToggleButton |
L'espace de noms Microsoft.Office.Tools.Ribbon utilise le préfixe « Ribbon » pour ces classes 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 classes de contrôle du ruban
Chaque classe de contrôle du ruban contient des propriétés que vous pouvez utiliser pour effectuer différentes tâches, telles que l'assignation d'une étiquette à un contrôle ou le masquage et l'affichage de contrôles.
Dans certains cas, des propriétés passent en lecture seule après le chargement du ruban ou l'ajout d'un contrôle à 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 tâches que vous pouvez effectuer à l'aide de propriétés de contrôle du ruban.
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 |
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 au RibbonMenu après le chargement du ruban dans l'application Office, vous devez affecter la valeur true à la propriété Dynamic avant le chargement. 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, |
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 du ruban.
Dans le méthode CreateRibbonExtensibilityObject de la classe ThisAddin de votre projet.
Les menus dynamiques comportent certaines exceptions. Vous pouvez créer des contrôles, définir leurs propriétés puis les ajouter à un menu dynamique au moment de l'exécution, même après chargement du ruban qui contient le menu.
À compter de Visual Studio 2008 Service Pack 1 (SP1), les propriétés des contrôles que vous ajoutez à un menu dynamique peuvent être définies à n'importe quel moment. Toutefois, si vous n'avez pas installé SP1, certaines des propriétés passent en lecture seule une fois que le contrôle a été ajouté au menu.
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 de ruban dans le constructeur de la classe du ruban. 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.
<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";
}
}
Définition des propriétés dans la méthode CreateRibbonExtensibilityObject
Vous pouvez définir les propriétés d'un contrôle de ruban lorsque vous substituez la méthode CreateRibbonExtensibilityObject dans la classe ThisAddin, ThisWorkbook ou 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 CreateRibbonExtensibilityObject de la classe ThisWorkbook d'un projet de classeur 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 });
}
}
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.
.gif "Remarque") Remarque : |
|---|
Si vous installez SP1, vous pouvez définir les propriétés de contrôles sur les menus dynamiques à n'importe quel moment. Dans ce cas, le tableau suivant ne s'applique pas. |
Propriété |
Classe de contrôle du ruban |
|---|---|
BoxStyle |
|
ButtonType |
|
ColumnCount |
|
ControlId |
|
DialogLauncher |
|
Dynamic |
|
Global |
|
Groups |
|
ImageName |
|
ItemSize |
|
MaxLength |
|
Name |
|
Position |
|
RibbonType |
|
RowCount |
|
ShowItemImage |
|
ShowItemLabel |
|
ShowItemSelection |
|
SizeString |
|
StartFromScratch |
|
Tabulations |
|
Title |
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, les propriétés répertoriées dans le tableau ci-dessus doivent être définies avant la création de la première instance du ruban. Une fois la première instance créée, ces propriétés passent en lecture seule car l'instance définit le fichier XML utilisé par Outlook pour charger le ruban.
Si votre logique conditionnelle affecte à l'une de ces propriétés une valeur différente lorsque d'autres instances du ruban sont créées, ce code sera sans effet.
| Remarque : |
|---|
Assurez-vous que la propriété Name 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 du design, la propriété 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 Microsoft.Office.Core.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 un 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 Visual Studio Tools pour Office. |
Voir aussi
Tâches
Comment : démarrer avec la personnalisation du ruban
Procédure pas à pas : création d'un onglet personnalisé à l'aide du Concepteur de ruban
Procédure pas à pas : mise à niveau des contrôles sur un ruban au moment de l'exécution
Comment : personnaliser un onglet intégré
Comment : personnaliser le menu Microsoft Office
Comment : exporter un ruban à partir du Concepteur de ruban vers l'élément XML Ribbon
Comment : afficher les erreurs de l'interface utilisateur du complément
Concepts
Accès au ruban au moment de l'exécution
Personnalisation d'un ruban pour Outlook
Référence
Historique des modifications
Date |
Historique |
Raison |
|---|---|---|
|
Juillet 2008 |
Modification des informations relatives à la définition des propriétés de contrôles sur les menus dynamiques après installation du SP1. |
Modifications de fonctionnalités dans le SP1. |