Ajouter des contrôles à Bureau documents au moment de l’exécution

  • Article

Vous pouvez ajouter des contrôles à un document Microsoft Office Word et à un classeur Microsoft Office Excel au moment de l’exécution. Vous pouvez également les supprimer au moment de l’exécution. Les contrôles que vous ajoutez aux documents ou que vous supprimez au moment de l’exécution sont appelés contrôles dynamiques.

S’applique à : les informations contenues dans cette rubrique s’appliquent aux projets de niveau document et aux projets de complément VSTO pour Excel et Word. Pour plus d’informations, consultez Fonctionnalités disponibles par application Office lication et le type de projet.

Cette rubrique décrit les tâches suivantes :

Gérer les contrôles au moment de l’exécution à l’aide de collections de contrôles

Pour ajouter, obtenir ou supprimer des contrôles au moment de l’exécution, utilisez les méthodes d’assistance des objets ControlCollection et ControlCollection .

La façon dont vous accédez à ces objets dépend du type de projet que vous développez :

  • Dans un projet au niveau du document pour Excel, utilisez la propriété Controls des classes Sheet1, Sheet2et Sheet3 . Pour plus d’informations sur ces classes, consultez l’élément hôte de feuille de calcul.

  • Dans un projet au niveau du document pour Word, utilisez la propriété Controls de la classe ThisDocument . Pour plus d’informations sur cette classe, consultez l’élément hôte document.

  • Dans un projet de complément VSTO pour Excel ou Word, utilisez la Controls propriété d’un Worksheet ou Document que vous générez au moment de l’exécution. Pour plus d’informations sur la génération de ces objets au moment de l’exécution, consultez Étendre des documents Word et des classeurs Excel dans des compléments VSTO au moment de l’exécution.

Ajouter des contrôles

Les types ControlCollection et ControlCollection incluent des méthodes d’assistance que vous pouvez utiliser pour ajouter des contrôles hôtes et des contrôles Windows Forms communs aux documents et aux feuilles de calcul. Chaque nom de méthode est au format Addcontrol classoù control class correspond au nom de la classe du contrôle que vous souhaitez ajouter. Par exemple, pour ajouter un contrôle NamedRange à votre document, utilisez la méthode AddNamedRange .

L’exemple de code suivant montre comment ajouter NamedRange à Sheet1 dans un projet au niveau du document pour Excel.

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Contrôles d’accès et de suppression

Vous pouvez utiliser la propriété Controls d’un Worksheet ou Document pour effectuer une itération dans tous les contrôles dans votre document, y compris les contrôles que vous avez ajoutés au moment de la conception. Les contrôles que vous avez ajoutés au moment de la conception sont également appelés contrôles statiques.

Vous pouvez supprimer des contrôles dynamiques en appelant la Delete méthode du contrôle ou en appelant la Remove méthode de chaque collection Controls. L’exemple de code suivant utilise la méthode Remove pour supprimer une NamedRange de Sheet1 dans un projet au niveau du document pour Excel.

Globals.Sheet1.Controls.Remove("ChartSource");

Vous ne pouvez pas supprimer les contrôles statiques au moment de l’exécution. Si vous essayez d’utiliser la méthode Delete ou Remove pour supprimer un contrôle statique, une exception CannotRemoveControlException sera levée.

Remarque

Ne supprimez pas les contrôles par programmation dans le gestionnaire d’événements Shutdown du document. Les éléments d’interface utilisateur du document ne sont plus disponibles quand l’événement Shutdown est déclenché. Si vous souhaitez supprimer les contrôles avant la fermeture du document, ajoutez votre code au gestionnaire d’événements pour un autre événement, tel que BeforeClose ou BeforeSave pour Word, ou BeforeCloseou BeforeSave pour Excel.

Ajouter des contrôles hôtes à des documents

Lorsque vous ajoutez par programmation des contrôles hôtes aux documents, vous devez fournir un nom qui identifie de façon unique le contrôle. Vous devez également spécifier où le contrôle doit être ajouté dans le document. Pour obtenir des instructions spécifiques, consultez les rubriques suivantes :

Pour plus d’informations sur les contrôles hôtes, consultez la vue d’ensemble des éléments hôtes et des contrôles hôtes.

Lorsqu’un document est enregistré puis fermé, tous les contrôles hôtes créés dynamiquement sont déconnectés de leurs événements et perdent leur fonctionnalité de liaison de données. Vous pouvez ajouter du code à votre solution pour recréer les contrôles hôtes lorsque le document est de nouveau ouvert. Pour plus d’informations, consultez Conserver les contrôles dynamiques dans Bureau documents.

Remarque

Les méthodes d’assistance ne sont pas fournies pour les contrôles hôtes suivants, car ceux-ci ne peuvent pas être ajoutés par programmation aux documents : XmlMappedRange, XMLNodeet XMLNodes.

Ajouter des contrôles Windows Forms à des documents

Lorsque vous ajoutez par programmation un contrôle Windows Forms à un document, vous devez fournir l’emplacement du contrôle et un nom qui identifie de façon unique le contrôle. Le runtime Visual Studio Tools pour Office fournit des méthodes d’assistance pour chaque contrôle. Ces méthodes sont surchargées afin que vous puissiez transmettre une plage ou des coordonnées spécifiques pour l’emplacement du contrôle.

Lorsqu’un document est enregistré puis fermé, tous les contrôles Windows Forms créés dynamiquement sont supprimés du document. Vous pouvez ajouter du code à votre solution pour recréer les contrôles lorsque le document est de nouveau ouvert. Si vous créez des contrôles Windows Forms dynamiques à l’aide d’un complément VSTO, les wrappers ActiveX pour les contrôles sont laissés dans le document. Pour plus d’informations, consultez Conserver les contrôles dynamiques dans Bureau documents.

Remarque

Les contrôles Windows Forms ne peuvent pas être ajoutés par programmation aux documents protégés. Si vous déprotégez par programmation un document Word ou une feuille de calcul Excel pour ajouter un contrôle, vous devez écrire le code supplémentaire pour supprimer le wrapper ActiveX du contrôle lorsque le document est fermé. Le wrapper ActiveX du contrôle n’est pas supprimé automatiquement des documents protégés.

Ajouter des contrôles personnalisés

Si vous souhaitez ajouter un Control qui n’est pas pris en charge par les méthodes d’assistance disponibles, tel qu’un contrôle utilisateur personnalisé, utilisez les méthodes suivantes :

  • Pour Excel, utilisez l’une des méthodes AddControl d’un objet ControlCollection .

  • Pour Word, utilisez l’une des méthodes AddControl d’un objet ControlCollection .

    Pour ajouter le contrôle, transmettez le Control, un emplacement pour le contrôle et un nom qui identifie de façon unique le contrôle à la méthode AddControl. La méthode AddControl renvoie un objet qui définit la façon dont le contrôle interagit avec la feuille de calcul ou le document. La AddControl méthode retourne un ControlSite (pour Excel) ou un ControlSite objet (pour Word).

    L’exemple de code suivant montre comment utiliser la méthode AddControl pour ajouter dynamiquement un contrôle utilisateur personnalisé à une feuille de calcul dans un projet Excel au niveau du document. Dans cet exemple, le contrôle utilisateur est nommé UserControl1, et la Range est nommée range1. Pour utiliser cet exemple, exécutez-le à partir d’une classe Sheetn dans le projet.

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Utiliser des membres de contrôles personnalisés

Après avoir utilisé l’une des méthodes AddControl pour ajouter un contrôle à une feuille de calcul ou à un document, vous avez désormais deux objets de contrôle différents :

  • Le Control qui représente le contrôle personnalisé.

  • Le ControlSite, OLEObject ou l’objet OLEControl qui représente le contrôle après qu’il a été ajouté à la feuille de calcul ou au document.

    De nombreuses propriétés et méthodes sont partagées entre ces contrôles. Il est important que vous accédiez à ces membres via le contrôle approprié :

  • Pour accéder aux membres qui appartiennent uniquement au contrôle personnalisé, utilisez le Control.

  • Pour accéder aux membres partagés par les contrôles, utilisez le ControlSite, OLEObject ou l’objet OLEControl.

    Si vous accédez à un membre partagé à partir du Control, un échec peut survenir sans que vous soyez averti ou notifié, ou des résultats non valides peuvent être générés. Utilisez toujours les méthodes ou propriétés du ControlSite, OLEObject ou de l’objet OLEControl, sauf si la méthode ou la propriété nécessaire n’est pas disponible ; ensuite seulement vous devez référencez le Control.

    Par exemple, la classe ControlSite et la classe Control ont une propriété Top. Pour obtenir ou définir la distance entre le haut du contrôle et le haut du document, utilisez la propriété Top du ControlSite, et non la propriété Top du Control.

    // Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

Contenu connexe