Procédure de réponse aux événements de formulaire en utilisant le modèle objet InfoPath 2003

Vous pouvez écrire du code pour répondre à divers événements se produisant pendant qu'un utilisateur remplit un formulaire. Pour utiliser les événements dans InfoPath, vous créez des gestionnaires d'événements dans un formulaire en mode Création.

Les gestionnaires d'événements InfoPath doivent d'abord être créés en mode Création car, lors de l'utilisation du modèle objet compatible avec InfoPath 2003, InfoPath ajoute automatiquement la déclaration appropriée et applique un attribut (InfoPathEventHandlerAttribute) dans le fichier de code de formulaire (FormCode.cs ou FormCode.vb) pour identifier et réceptionner le gestionnaire d'événements. Après avoir créé un gestionnaire d'événements, vous ne pouvez plus modifier sa déclaration et son attribut dans le fichier de code du formulaire.

Pour plus d'informations sur la création de gestionnaires d'événements InfoPath, voir Procédure d'ajout d'un gestionnaire d'événements en utilisant le modèle objet InfoPath 2003.

Vue d'ensemble des objets d'événement

Le modèle objet compatible avec InfoPath 2003 implémente neuf objets exposés dans l'espace de noms Microsoft.Office.Interop.InfoPath.SemiTrust. Le tableau suivant vous offre une description de chacun des neuf événements InfoPath, en indiquant les gestionnaires d'événements qui lui sont associés.

Nom	Gestionnaires d'événements	Description
DataDOMEvent	OnBeforeChange OnValidate, OnAfterChange	Renvoie une référence au document XML sous-jacent d'un formulaire, le statut de renvoi et d'autres propriétés contenant des informations relatives au nœud XML lors d'un changement de DOM (Document Object Model) XML. Comprend également une méthode pour générer une erreur.
DocActionEvent	OnClick	Renvoie une référence au document XML sous-jacent d'un formulaire, le statut de renvoi et le nœud XML source lors d'un clic de bouton dans la zone du formulaire.
DocContextChangeEvent	OnContextChange	Renvoie des informations relatives au nœud DOM (Document Object Model) XML qui est le contexte actuel du document XML sous-jacent du formulaire.
DocEvent	OnSwitchView, OnAfterImport	Renvoie une référence au document XML sous-jacent d'un formulaire lors d'une opération de changement de vue ou de fusion de formulaires.
DocReturnEvent	OnLoad, OnSubmitRequest	Renvoie une référence au document XML sous-jacent du formulaire accompagnée du statut de renvoi lors du chargement ou de l'envoi d'un formulaire.
MergeEvent	OnMergeRequest	Renvoie des propriétés et des méthodes qui peuvent être utilisées durant un événement OnMergeRequest pour interagir par programme avec le document XML sous-jacent d'un formulaire et déterminer des propriétés de fusion telles que le nombre de fichiers fusionnés.
SaveEvent	OnSaveRequest	Renvoie un certain nombre de propriétés et de méthodes qui peuvent être utilisées durant une opération d'enregistrement à partir du gestionnaire d'événements OnSaveRequest, afin d'interagir par programme avec le document XML sous-jacent d'un formulaire, de déterminer les propriétés d'enregistrement et d'effectuer l'opération d'enregistrement.
SignEvent	OnSign	Utilisé pour ajouter des données supplémentaires à la signature numérique.
VersionUpgradeEvent	OnVersionUpgrade	Renvoie une référence au document XML sous-jacent d'un formulaire, le statut de renvoi et les numéros de version du document et de la solution lors d'une opération de mise à niveau de la version.

Utilisation des objets d'événement

Lorsque vous créez un gestionnaire d'événements, InfoPath crée la déclaration de celui-ci dans le fichier de code de formulaire du projet (FormCode.cs ou FormCode.vb). Dans cette déclaration, InfoPath utilise e comme nom du paramètre transmis au gestionnaire d'événements. Ce paramètre contient l'objet d'événement associé au gestionnaire d'événements.

Par exemple, lorsque vous créez un gestionnaire d'événements pour l'événement OnLoad en mode Création (en cliquant sur le menu Outils, en pointant sur Programmation, puis en cliquant sur Événement Sur chargement (OnLoad)), InfoPath ajoute la déclaration du gestionnaire d'événements qui reçoit l'objet DocReturnEvent au fichier de code du formulaire, puis ouvre l'Éditeur de code pour vous permettre d'ajouter votre code à la déclaration de gestionnaire d'événements qui suit.

// The following function handler is created by Microsoft Office 
// InfoPath. Do not modify the type or number of arguments.
[InfoPathEventHandler(EventType=InfoPathEventType.OnLoad)]
public void FormEvents_OnLoad(DocReturnEvent e)
{
   // Write your code here.

}

' The following function handler is created by Microsoft Office 
' InfoPath. Do not modify the type or number of arguments.
<InfoPathEventHandler(EventType:=InfoPathEventType.OnLoad)> _
Public Sub FormEvents_OnLoad(ByVal e As DocReturnEvent)
   ' Write your code here.

End Sub

Lorsque vous écrivez du code pour un gestionnaire d'événements, vous pouvez utiliser les propriétés et les méthodes implémentées par l'objet d'événement transmis par le paramètre e. Par exemple, dans le gestionnaire d'événements OnBeforeChange qui suit, la propriété NewValue de l'objet d'événement DataDOMEvent est utilisée pour la vérification de la valeur du champ qui vient d'être modifié. S'il est vide, la propriété ReturnMessage de l'objet d'événement DataDOMEvent est utilisée pour afficher une erreur dans une boîte de dialogue et la propriété ReturnStatus est définie sur false, ce qui indique que les modifications de l'utilisateur ne doivent pas être acceptées.

[InfoPathEventHandler(MatchPath="/my:myFields/my:field1", 
    EventType=InfoPathEventType.OnBeforeChange)]
public void field1_OnBeforeChange(DataDOMEvent e)
{
   // Determine whether there is a new value.
   if ((string)e.NewValue == "")
   {
      // The value is blank, so display an error message and roll
      // back the changes.
      e.ReturnMessage = "You must supply a value for this field.";
      e.ReturnStatus = false;
      return;
   }
}

<InfoPathEventHandler(MatchPath:="/my:myFields/my:field1", _ EventType:=InfoPathEventType.OnBeforeChange)> _
Public Sub field1_OnBeforeChange(ByVal e As DataDOMEvent)

   ' Determine whether there is a new value.
   If (e.NewValue = "") Then
      ' The value is blank, so display an error message and roll back
      ' the changes.
      e.ReturnMessage = "You must supply a value for this field."
      e.ReturnStatus = False
      Return
   End If
End Sub

Remarque
Chaque objet d'événement InfoPath du modèle objet compatible avec InfoPath 2003 implémente différentes propriétés et méthodes. Pour plus d'informations sur un objet d'événement en particulier, cliquez dessus dans le tableau Objets d'événement présenté plus haut.