Contrôles de contenu

Mise à jour : Juillet 2008

Les contrôles de contenu vous permettent de concevoir des documents et des modèles qui ont les fonctionnalités suivantes :

• Une interface utilisateur dont les entrées sont contrôlées comme dans le cas d'un formulaire.

• Des restrictions qui empêchent les utilisateurs de modifier les sections protégées du document ou du modèle. Pour plus d'informations, consultez Protection de parties de documents à l'aide de contrôles de contenu.

• La liaison à une source de données. Pour plus d'informations, consultez Liaison de données à des contrôles de contenu.

Vue d'ensemble des contrôles de contenu

Les contrôles de contenu fournissent une interface utilisateur optimisée à la fois pour l'entrée d'utilisateur et pour l'impression. Lorsque vous ajoutez un contrôle de contenu à un document, le contrôle est identifié par une bordure, un titre et un texte temporaire qui peut fournir des instructions à l'utilisateur. La bordure et le titre du contrôle n'apparaissent pas dans les versions imprimées du document.

Par exemple, si vous souhaitez que l'utilisateur entre une date dans une section de votre document, vous pouvez ajouter un contrôle du contenu de sélecteur de dates au document. Lorsque les utilisateurs cliquent sur le contrôle, l'interface utilisateur du sélecteur de dates standard apparaît. Vous pouvez également définir les propriétés du contrôle de manière à configurer le calendrier régional affiché et à spécifier le format de date. Lorsque l'utilisateur a choisi une date, l'interface utilisateur du contrôle est masquée et seule la date apparaît si l'utilisateur imprime le document.

Les contrôles de contenu vous aident également à effectuer les opérations suivantes :

• Empêcher des utilisateurs de modifier ou supprimer des parties d'un document. Cela peut s'avérer utile si votre document ou modèle contient des informations que les utilisateurs doivent pouvoir lire mais pas modifier, ou si vous souhaitez que les utilisateurs puissent modifier des contrôles de contenu mais pas les supprimer.

• Lier des parties d'un document ou modèle à des données. Vous pouvez lier des contrôles de contenu à des champs de base de données, à des objets managés dans le .NET Framework, à des éléments XML stockés dans le document et à d'autres sources de données.

Dans les projets au niveau du document, vous pouvez ajouter des contrôles de contenu à votre document au moment du design ou au moment de l'exécution. À compter de Visual Studio 2008 Service Pack 1 (SP1), vous pouvez également ajouter des contrôles de contenu à tout document ouvert au moment de l'exécution en utilisant un complément d'application. Pour plus d'informations, consultez Comment : ajouter des contrôles de contenu à des documents Word.

Remarque :
Vous pouvez utiliser des contrôles de contenu uniquement dans des documents enregistrés au format Open XML de Word 2007. Vous ne pouvez pas en utiliser dans des documents enregistrés dans le format de document (.doc) de Word 97-2003.

Types de contrôles de contenu

Visual Studio Tools pour Office vous permet d'ajouter huit types de contrôles de contenu à des documents. Chaque contrôle de contenu a une classe correspondante dans l'espace de noms Microsoft.Office.Tools.Word. Vous pouvez également utiliser la classe ContentControl, qui peut représenter chacun des contrôles de contenu disponibles.

Pour une procédure pas à pas qui montre comment utiliser chacun des contrôles de contenu disponibles, consultez Procédure pas à pas : création d'un modèle à l'aide de contrôles de contenu.

Galerie de blocs de construction

Une galerie de bloc de construction permet aux utilisateurs de sélectionner dans une liste des blocs de construction de document à insérer dans un document. Un bloc de construction de document est une partie de contenu créée pour être utilisée plusieurs fois, telle qu'une une page de garde commune, une table mise en forme ou un en-tête. Pour plus d'informations, consultez la classe BuildingBlockGalleryContentControl. Pour plus d'informations sur les blocs de construction, consultez Nouveautés pour les développeurs dans Word 2007.

Combo Box

Une zone de liste déroulante affiche la liste des éléments que les utilisateurs peuvent sélectionner. Contrairement à une liste déroulante, la zone de liste déroulante permet aux utilisateurs d'ajouter leurs propres éléments. Pour plus d'informations, consultez la classe ComboBoxContentControl.

Sélecteur de dates

Un sélecteur de dates fournit une interface utilisateur de calendrier pour sélectionner une date. Le calendrier apparaît lorsque l'utilisateur final clique sur la flèche de liste déroulante dans le contrôle. Vous pouvez utiliser des calendriers régionaux et des formats de date différents. Pour plus d'informations, consultez la classe DatePickerContentControl.

Liste déroulante

Une liste déroulante affiche la liste des éléments que les utilisateurs peuvent sélectionner. Contrairement à une zone de liste déroulante, la liste déroulante ne permet pas aux utilisateurs d'ajouter ou de modifier des éléments. Pour plus d'informations, consultez la classe DropDownListContentControl.

Group

Un contrôle de groupe définit une région protégée d'un document que les utilisateurs ne peuvent pas modifier ou supprimer. Un contrôle de groupe peut contenir tous types d'éléments de document : du texte, des tableaux, des graphiques et d'autres contrôles de contenu. Pour plus d'informations, consultez la classe GroupContentControl.

Picture

Un contrôle d'image affiche une image. Vous pouvez spécifier l'image au moment du design ou de l'exécution, ou les utilisateurs peuvent cliquer sur ce contrôle pour sélectionner une image à insérer dans le document. Pour plus d'informations, consultez la classe PictureContentControl.

Texte enrichi

Un contrôle de texte enrichi contient du texte ou d'autres éléments, comme des tableaux, des images ou d'autres contrôles de contenu. Pour plus d'informations, consultez la classe RichTextContentControl.

Texte brut

Un contrôle de texte brut contient du texte. Un contrôle de texte brut ne peut pas contenir d'autres éléments, comme des tableaux, des images ou d'autres contrôles de contenu. En outre, tout le texte d'un contrôle de texte brut a la même mise en forme. Par exemple, si vous mettez en italique un mot d'une phrase contenue dans un contrôle de texte brut, tout le texte à l'intérieur du contrôle est mis en italique. Pour plus d'informations, consultez la classe PlainTextContentControl.

ContentControl

Un objet ContentControl est un contrôle mutable qui peut représenter chacun des huit types de contrôles de contenu. Vous pouvez modifier un objet ContentControl de manière à ce qu'il se comporte comme un type différent de contrôle de contenu à l'aide de la propriété Type. Par exemple, si vous créez un objet ContentControl qui représente un contrôle de texte brut, vous pouvez le modifier au moment de l'exécution afin qu'il se comporte comme une zone de liste déroulante.

Vous pouvez créer des objets ContentControl uniquement au moment de l'exécution, et pas au moment du design. Pour plus d'informations, consultez Comment : ajouter des contrôles de contenu à des documents Word.

Fonctionnalités communes des contrôles de contenu

La plupart des contrôles de contenu de Visual Studio Tools pour Office partagent un ensemble de membres que vous pouvez utiliser pour effectuer des tâches courantes. Le tableau suivant décrit quelques-unes des tâches que vous pouvez effectuer à l'aide de ces membres.

Pour cette tâche :	Procédez comme suit :
Obtenez ou définissez le texte affiché dans le contrôle.	Utilisez la propriété Text. Remarque : Les classes PictureContentControl et ContentControl n'ont pas cette propriété.
Obtenez ou définissez le texte temporaire affiché dans le contrôle jusqu'à ce qu'un utilisateur modifie le contrôle, que le contrôle soit rempli avec les données d'une source de données ou que le contenu du contrôle soit supprimé.	Utilisez la propriété PlaceholderText. Remarque : La classe PictureContentControl n'a pas cette propriété.
Obtenez ou définissez le titre affiché dans la bordure du contrôle de contenu lorsque l'utilisateur clique sur lui.	Utilisez la propriété Title.
Supprimez automatiquement le contrôle du document après que l'utilisateur a modifié le contrôle. (Le texte du contrôle reste dans le document.)	Utilisez la propriété Temporary.
Exécutez le code lorsque l'utilisateur clique dans le contrôle de contenu ou lorsque le curseur est transféré par programme vers le contrôle de contenu.	Gérez l'événement Entering du contrôle.
Exécutez le code lorsque l'utilisateur clique en dehors du contrôle de contenu ou lorsque le curseur est déplacé par programme en dehors du contrôle de contenu.	Gérez l'événement Exiting du contrôle.
Exécutez le code après que le contrôle de contenu a été ajouté au document à la suite d'une opération de rétablissement ou d'annulation.	Gérez l'événement Added du contrôle.
Exécutez le code juste avant que le contrôle de contenu soit supprimé du document.	Gérez l'événement Deleting du contrôle.

Protection de parties de documents à l'aide de contrôles de contenu

Lorsque vous protégez une partie d'un document, vous empêchez les utilisateurs de modifier ou de supprimer le contenu dans cette partie du document. Il existe plusieurs manières de protéger des parties d'un document à l'aide de contrôles de contenu.

Si la zone que vous souhaitez protéger se trouve à l'intérieur d'un contrôle de contenu, vous pouvez utiliser les propriétés du contrôle de contenu pour empêcher des utilisateurs de modifier ou supprimer le contrôle :

• La propriété LockContents empêche les utilisateurs de modifier le contenu.

• La propriété LockContentControl empêche les utilisateurs de supprimer le contrôle.

Si la zone que vous souhaitez protéger ne se trouve pas à l'intérieur d'un contrôle de contenu, ou si vous souhaitez protéger une zone qui contient des contrôles de contenu et d'autres types de contenu, vous pouvez placer la zone entière dans un GroupContentControl. Contrairement à d'autres contrôles de contenu, un GroupContentControl ne fournit aucune interface utilisateur visible à l'utilisateur. Son seul but est de définir une région que les utilisateurs ne peuvent pas modifier.

Remarque :
Si vous créez un GroupContentControl qui contient des contrôles de contenu incorporés, ces contrôles ne sont pas protégés automatiquement. Vous devez utiliser la propriété LockContents de chaque contrôle incorporé pour empêcher les utilisateurs de modifier leur contenu.

Pour plus d'informations sur l'utilisation de contrôles de contenu pour protéger des parties de documents, consultez Comment : protéger des parties de documents à l'aide de contrôles de contenu.

Liaison de données à des contrôles de contenu

Vous pouvez afficher des données dans des documents en liant un contrôle de contenu à une source de données. Lorsque la source de données est mise à jour, le contrôle de contenu reflète les modifications. Vous pouvez également enregistrer les modifications dans la source de données.

Les contrôles de contenu fournissent les options de liaison des données suivantes :

• Vous pouvez lier des contrôles de contenu à des champs de base de données ou des objets managés en utilisant le même modèle de liaison de données que Windows Forms.

• Vous pouvez lier des contrôles de contenu à des éléments de fragments XML (également appelés parties XML personnalisées) qui sont incorporés dans le document.

Pour obtenir une vue d'ensemble de la liaison de contrôles hôtes dans les solutions Visual Studio Tools pour Office aux données, consultez Liaison de données aux contrôles.

Utilisation du modèle de liaison de données Windows Forms

La plupart des contrôles de contenu prennent en charge le modèle de liaison de données simple que Windows Forms utilise. La liaison de données simple signifie qu'un contrôle est lié à un élément de données unique, tel qu'une valeur dans une colonne d'une table de données. Pour plus d'informations, consultez Liaison de données et Windows Forms.

Dans les projets au niveau du document, vous pouvez également lier des données à des contrôles de contenu en utilisant la fenêtre Sources de données dans Visual Studio. Pour plus d'informations sur l'ajout à des documents de contrôles de contenu liés aux données, consultez Comment : remplir des documents avec les données d'une base de données et Comment : remplir des documents avec les données d'objets.

Le tableau suivant répertorie les contrôles de contenu que vous pouvez lier à chaque type de données dans la fenêtre Sources de données.

Dans les projets au niveau du document et de l'application, vous pouvez également lier par programme un contrôle de contenu à une source de données en utilisant la méthode Add de la propriété DataBindings du contrôle. En procédant ainsi, vous passez la chaîne Texte au paramètre propertyName de la méthode Add. La propriété Text est la propriété de liaison de données par défaut des contrôles de contenu.

Les contrôles de contenu prennent également en charge la liaison de données bidirectionnelle, dans laquelle les modifications apportées au contrôle sont répercutées dans la source de données. Pour plus d'informations, consultez Comment : mettre à jour une source de données avec les données d'un contrôle hôte.

Remarque :

Les contrôles de contenu ne prennent pas en charge la liaison de données complexe. Si vous liez un DropDownListContentControl ou un ComboBoxContentControl à une source de données à l'aide du modèle de données Windows Forms, les utilisateurs ne verront qu'une seule valeur lorsqu'ils cliquent sur le contrôle. Pour lier ces contrôles à un jeu des valeurs de données à partir duquel les utilisateurs peuvent choisir, vous pouvez lier ces contrôles à des éléments d'une partie XML personnalisée.

Liaison de contrôles de contenu à des parties XML personnalisées

Vous pouvez lier des contrôles de contenu à des éléments dans des parties XML personnalisées qui sont incorporées dans le document. Pour plus d'informations sur les parties XML personnalisées, consultez Vue d'ensemble des parties XML personnalisées.

Pour lier un contrôle de contenu à un élément d'une partie XML personnalisée, utilisez la propriété XMLMapping du contrôle. L'exemple de code suivant montre comment lier un PlainTextContentControl à l'élément Price sous le nœud Product dans une partie XML personnalisée qui a déjà été ajoutée au document.

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price")

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);

Pour une procédure pas à pas qui montre comment lier des contrôles de contenu à des parties XML personnalisées dans plus de détails, consultez Procédure pas à pas : liaison de contrôles de contenu à des parties XML personnalisées.

Lorsque vous liez un contrôle de contenu à une partie XML personnalisée, la liaison de données bidirectionnelle est activée automatiquement. Si un utilisateur modifie le texte dans le contrôle, les éléments XML correspondants sont mis à jour automatiquement. De la même façon, si les valeurs d'élément dans les parties XML personnalisées sont modifiées, les contrôles de contenu liés aux éléments XML afficheront les nouvelles données.

Vous pouvez lier les types suivants de contrôles de contenu à des parties XML personnalisées :

• ComboBoxContentControl

• DatePickerContentControl

• DropDownListContentControl

• PictureContentControl

• PlainTextContentControl

Événements de liaison de données pour les contrôles de contenu

Tous les contrôles de contenu fournissent un jeu des événements que vous pouvez gérer afin d'effectuer des tâches liées aux données, par ex. pour valider que le texte d'un contrôle répond à certains critères avant que la source de données soit mise à jour. Le tableau suivant répertorie les événements de contrôle de contenu relatifs à la liaison de données.

Limitations des contrôles de contenu

Lorsque vous utilisez des contrôles de contenu dans vos projets Visual Studio Tools pour Office, tenez compte des limitations suivantes.

Différences de comportement entre le moment du design et le moment de l'exécution

Nombre des limitations que Microsoft Office Word impose aux contrôles de contenu au moment de l'exécution ne sont pas appliquées au moment du design. Lorsque vous concevez l'interface utilisateur de votre solution au niveau du document dans Visual Studio, veillez à n'apporter aux contrôles de contenu que des modifications susceptibles d'être prises en charge au moment de l'exécution.

Si vous modifiez un contrôle de contenu au moment du design d'une façon que le contrôle ne prend pas en charge au moment de l'exécution, le concepteur Visual Studio ne vous signalera pas les modifications non prises en charge. Toutefois, lorsque vous déboguez ou exécutez le projet, ou si vous enregistrez puis rouvrez le projet, Word affichera un message d'erreur et demandera l'autorisation de réparer le document. Lorsque vous réparez le document, Word supprime tout le contenu et la mise en forme non pris en charge dans le contrôle.

Par exemple, Word ne vous empêche pas d'ajouter un tableau à un PlainTextContentControl au moment du design. Cependant, comme les objets PlainTextContentControl ne peuvent pas contenir de tableaux au moment de l'exécution, Word affichera un message d'erreur à l'ouverture du document.

Notez également que de nombreuses propriétés qui définissent le comportement des contrôles de contenu n'ont aucun effet au moment du design. Par exemple, si vous affectez la valeur True à la propriété LockContents d'un contrôle de contenu au moment du design, vous pouvez encore modifier le texte du contrôle dans le concepteur Visual Studio. Cette propriété empêche seulement les utilisateurs de modifier le contrôle au moment de l'exécution.

Limitations d'événement

Les contrôles de contenu ne fournissent pas un événement déclenché lorsque l'utilisateur modifie le texte ou d'autres éléments dans le contrôle. Par exemple, aucun événement n'est déclenché lorsqu'un utilisateur sélectionne un autre élément dans un DropDownListContentControl ou un ComboBoxContentControl.

Pour déterminer quand un utilisateur modifie le contenu d'un contrôle de contenu, vous pouvez lier le contrôle à une partie XML personnalisée, puis gérez l'événement StoreUpdating. Cet événement est déclenché lorsque l'utilisateur modifie le contenu d'un contrôle lié à une partie XML personnalisée. Pour une procédure pas à pas qui montre comment lier un contrôle de contenu à une partie XML personnalisée, consultez Procédure pas à pas : liaison de contrôles de contenu à des parties XML personnalisées.

Voir aussi

Tâches

Comment : ajouter des contrôles de contenu à des documents Word

Procédure pas à pas : création d'un modèle à l'aide de contrôles de contenu

Concepts

Liaison de données aux contrôles

Limitations de programmation des éléments hôtes et des contrôles hôtes

Autres ressources

Contrôles hôtes Word

Données dans les solutions Office

Historique des modifications