Procédure pas à pas : ajout de contrôles à un document au moment de l'exécution dans un complément d'application

Article
08/10/2011

Vous pouvez ajouter des contrôles à tout document Microsoft Office Word ouvert à l'aide d'un complément d'application. Cette procédure pas à pas explique comment utiliser le ruban pour permettre aux utilisateurs d'ajouter un Button ou un RichTextContentControl à un document.

S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau application pour Word 2007 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Cette procédure pas à pas décrit les tâches suivantes :

Création d'un projet de complément Word
Fourniture d'une interface utilisateur (IU) permettant d'ajouter des contrôles au document
Ajout de contrôles au document au moment de l'exécution
Suppression de contrôles dans le document

Notes

Il est possible que votre ordinateur affiche des noms ou des emplacements différents pour certains des éléments d'interface utilisateur de Visual Studio dans les instructions suivantes. L'édition de Visual Studio dont vous disposez et les paramètres que vous utilisez déterminent ces éléments. Pour plus d'informations, consultez Paramètres Visual Studio.

Composants requis

Pour exécuter cette procédure pas à pas, vous devez disposer des composants suivants :

Une édition de Visual Studio 2010 qui inclut les outils de développement Microsoft Office. Pour plus d'informations, consultez [Configuration d'un ordinateur pour développer des solutions Office](bb398242\(v=vs.100\).md).

Word 2007 ou Word 2010.

Création d'un projet de complément Word

Commencez par créer un projet de complément Word.

Pour créer un projet de complément Word

Créez un projet de complément d'application pour Word portant le nom WordDynamicControls. Pour plus d'informations, consultez Comment : créer des projets Office dans Visual Studio.
Si votre projet cible le .NET Framework 4, ajoutez une référence à l'assembly Microsoft.Office.Tools.Word.v4.0.Utilities.dll. Cette référence est obligatoire pour ajouter par programmation ultérieurement dans cette procédure un contrôle Windows Forms au document.

Fourniture d'une interface utilisateur permettant l'ajout de contrôles à un document

Ajoutez un onglet personnalisé au ruban dans Word. Les utilisateurs peuvent activer des cases à cocher sur l'onglet afin d'ajouter des contrôles à un document.

Pour fournir une interface utilisateur permettant l'ajout de contrôles à un document

Dans le menu Projet, cliquez sur Ajouter un nouvel élément.
Dans la boîte de dialogue Ajouter un nouvel élément, sélectionnez Ruban (Concepteur visuel).
Remplacez le nom du nouveau ruban par MyRibbon, puis cliquez sur Ajouter.

Le fichier MyRibbon.cs ou MyRibbon.vb s'ouvre dans le Concepteur de ruban et affiche un onglet et un groupe par défaut.
Dans le Concepteur de ruban, cliquez sur group1.
Dans la fenêtre Propriétés , modifiez la propriété Label de group1 pour ajouter des contrôles.
Sous l'onglet Contrôles de ruban Office de la Boîte à outils, faites glisser un contrôle CheckBox sur group1.
Cliquez sur CheckBox1 afin de le sélectionner.
Dans la fenêtre Propriétés, modifiez les propriétés suivantes.

Propriété

Valeur

Nom

addButtonCheckBox

Étiquette

Ajouter un bouton
Ajoutez une deuxième case à cocher dans group1, puis modifiez les propriétés suivantes.

Propriété

Valeur

Nom

addRichTextCheckBox

Étiquette

Ajouter un contrôle de texte enrichi
Dans le concepteur de ruban, double-cliquez sur Ajouter un bouton.

Le gestionnaire d'événements Click de la case à cocher Ajouter un bouton s'ouvre dans l'Éditeur de code.
Retournez dans le Concepteur de ruban, et double-cliquez sur Ajouter un contrôle de texte enrichi.

Le gestionnaire d'événements Click de la case à cocher Ajouter un contrôle de texte enrichi s'ouvre dans l'Éditeur de code.

Propriété	Valeur
Nom	addButtonCheckBox
Étiquette	Ajouter un bouton

Propriété	Valeur
Nom	addRichTextCheckBox
Étiquette	Ajouter un contrôle de texte enrichi

À une étape ultérieure de cette procédure, vous ajouterez du code à ces gestionnaires d'événements pour ajouter et supprimer des contrôles sur le document actif.

Ajout et suppression de contrôles sur le document actif

Dans le code de complément, vous devez convertir le document actif en un élément hôte Microsoft.Office.Tools.Word.Document avant de pouvoir ajouter un contrôle. Dans les solutions Visual Studio Tools pour Office, les contrôles managés peuvent être ajoutés uniquement aux éléments hôtes, qui agissent comme conteneurs pour les contrôles. Dans les projets de complément d'application, les éléments hôtes peuvent être créés uniquement au moment de l'exécution, en utilisant la méthode GetVstoObject.

Ajoutez des méthodes à la classe ThisAddIn qui peut être appelée pour ajouter ou supprimer un Button ou RichTextContentControl sur le document actif. À une étape ultérieure de cette procédure, vous appellerez ces méthodes à partir des gestionnaires d'événements Click des cases à cocher du ruban.

Pour ajouter et supprimer des contrôles sur le document actif

Dans l'Explorateur de solutions, double-cliquez sur ThisAddIn.cs ou ThisAddIn.vb afin d'ouvrir le fichier dans l'Éditeur de code.

Ajoutez le code suivant à la classe ThisAddIn : Ce code déclare les objets Button et RichTextContentControl qui représentent les contrôles qui seront ajoutés au document.

Private button As Microsoft.Office.Tools.Word.Controls.Button = Nothing
Private richTextControl As RichTextContentControl = Nothing

private Microsoft.Office.Tools.Word.Controls.Button button = null;
private RichTextContentControl richTextControl = null;

Ajoutez la méthode suivante à la classe ThisAddIn. Lorsque l'utilisateur clique sur la case à cocher Ajouter un bouton sur le ruban, cette méthode ajoute un Button à la sélection actuelle sur le document si la case à cocher est activée, ou supprime le Button si la case à cocher est désactivée.

Friend Sub ToggleButtonOnDocument()
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()

    Dim name As String = "MyButton"

    If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
        Dim selection = Me.Application.Selection
        If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
            button = vstoDocument.Controls.AddButton( _
                selection.Range, 100, 30, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleButtonOnDocument()
{
    // Use the following line of code in projects that target the .NET Framework 4.
    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();

    string name = "MyButton";

    if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
    {
        Word.Selection selection = this.Application.Selection;
        if (selection != null && selection.Range != null)
        {
            button = vstoDocument.Controls.AddButton(
                selection.Range, 100, 30, name);
        }
    }
    else
    {
        vstoDocument.Controls.Remove(name);
    }
}

Ajoutez la méthode suivante à la classe ThisAddIn. Lorsque l'utilisateur clique sur la case à cocher Ajouter un contrôle de texte enrichi sur le ruban, cette méthode ajoute un RichTextContentControl à la sélection actuelle sur le document si la case à cocher est activée, ou supprime le RichTextContentControl si la case à cocher est désactivée.

Friend Sub ToggleRichTextControlOnDocument()
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()

    Dim name As String = "MyRichTextBoxControl"

    If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
        Dim selection = Me.Application.Selection
        If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
            richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                    selection.Range, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleRichTextControlOnDocument()
{
    // Use the following line of code in projects that target the .NET Framework 4.
    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();

    string name = "MyRichTextBoxControl";

    if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
    {
        Word.Selection selection = this.Application.Selection;
        if (selection != null && selection.Range != null)
        {
            richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                selection.Range, name);
        }
    }
    else
    {
        vstoDocument.Controls.Remove(name);
    }
}

Suppression du contrôle Button lorsque le document est enregistré

Les contrôles Windows Forms ne deviennent pas persistants lorsque le document est enregistré puis fermé. Toutefois, il reste un wrapper ActiveX pour chaque contrôle dans le document, et la bordure de ce wrapper peut être vue par les utilisateurs finaux lorsque le document est rouvert. Il y a plusieurs méthodes pour nettoyer des contrôles Windows Forms créés dynamiquement dans des compléments. Dans cette procédure pas à pas, vous supprimez le contrôle Button par programmation lorsque le document est enregistré.

Pour supprimer le contrôle Button lorsque le document est enregistré

Dans le fichier de code ThisAddIn.cs ou ThisAddIn.vb, ajoutez la méthode suivante à la classe ThisAddIn. Cette méthode est un gestionnaire d'événements pour l'événement DocumentBeforeSave. Si un élément hôte Document est associé au document enregistré, le gestionnaire d'événements obtient l'élément hôte et supprime le contrôle Button, s'il existe.

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim isExtended As Boolean = Doc.HasVstoObject()

    If isExtended Then
        ' Use the following line of code in projects that target the .NET Framework 4.
        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

        ' In projects that target the .NET Framework 3.5, use the following line of code.
        ' Dim vstoDocument As Document = Doc.GetVstoObject()

        If vstoDocument.Controls.Contains(button) Then
            vstoDocument.Controls.Remove(button)
            Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
        End If
    End If
End Sub

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    // Use the following line of code in projects that target the .NET Framework 4.
    bool isExtended = Globals.Factory.HasVstoObject(Doc);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // bool isExtended = Doc.HasVstoObject();

    if (isExtended)
    {
        // Use the following line of code in projects that target the .NET Framework 4.
        Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

        // In projects that target the .NET Framework 3.5, use the following line of code.
        // Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();

        if (vstoDocument.Controls.Contains(button))
        {
            vstoDocument.Controls.Remove(button);
            Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
        }
    }
}

Dans C#, ajoutez le code suivant au gestionnaire d'événements ThisAddIn_Startup. Ce code est requis en C# pour connecter le gestionnaire d'événements Application_DocumentBeforeSave à l'événement DocumentBeforeSave.
```
this.Application.DocumentBeforeSave += 
    new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
    Application_DocumentBeforeSave);
```

Ajout et suppression de contrôles lorsque l'utilisateur clique sur les cases à cocher sur le ruban

Enfin, modifiez les gestionnaires d'événements Click des cases à cocher que vous avez ajoutées au ruban afin d'ajouter ou de supprimer des contrôles sur le document.

Pour ajouter ou supprimer des contrôles lorsque l'utilisateur clique sur les cases à cocher sur le ruban

Dans le fichier de code MyRibbon.cs ou MyRibbon.vb, remplacez les gestionnaires d'événements addButtonCheckBox_Click et addRichTextCheckBox_Click générés par le code suivant. Ce code redéfinit ces gestionnaires d'événements afin d'appeler les méthodes ToggleButtonOnDocument et ToggleRichTextControlOnDocument que vous avez ajoutées à la classe ThisAddIn ultérieurement dans cette procédure pas à pas.

Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _
    ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click
    Globals.ThisAddIn.ToggleButtonOnDocument()
End Sub

Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _
    ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click
    Globals.ThisAddIn.ToggleRichTextControlOnDocument()
End Sub

private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.ToggleButtonOnDocument();
}

private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.ToggleRichTextControlOnDocument();
}

Test de la solution

Ajoutez des contrôles à un document en les sélectionnant depuis l'onglet personnalisé sur le ruban. Lorsque vous enregistrez le document, le contrôle Button est supprimé.

Pour tester la solution

Appuyez sur F5 pour exécuter votre projet.
Dans le document actif, appuyez plusieurs fois sur ENTRÉE pour y ajouter de nouveaux paragraphes vides.
Sélectionnez le premier paragraphe.
Cliquez sur l'onglet Compléments.
Dans le groupe Ajouter des contrôles, cliquez sur Ajouter un bouton.

Un bouton apparaît dans le premier paragraphe.
Sélectionnez le dernier paragraphe.
Dans le groupe Ajouter des contrôles, cliquez Ajouter un contrôle de texte enrichi.

Un contrôle de contenu en texte enrichi est ajouté au dernier paragraphe.
Enregistrez le document.

Le bouton est supprimé du document.

Étapes suivantes

Vous pouvez approfondir votre connaissance des contrôles dans les compléments d'application en consultant les rubriques suivantes :

Pour obtenir un exemple qui montre de quelle façon ajouter de nombreux autres types de contrôles à un document au moment de l'exécution et recréer les contrôles lorsque le document est rouvert, consultez l'exemple des contrôles dynamiques de complément Word dans Exemples et procédures pas à pas relatifs au développement Office.
Pour suivre une procédure pas à pas qui montre comment ajouter des contrôles à une feuille de calcul en utilisant un complément d'application pour Excel, consultez Procédure pas à pas : ajout de contrôles à une feuille de calcul au moment de l'exécution dans un projet d'application.

Voir aussi

Partager via