Procédure de réponse à des événements de formulaire
Vous pouvez écrire du code pour répondre à divers événements susceptibles de se produire pendant qu'un utilisateur remplit un formulaire. Pour utiliser les événements dans InfoPath, vous pouvez ajouter des gestionnaires d'événements lorsque vous travaillez sur un modèle de formulaire en mode Création.
Les gestionnaires d'événements InfoPath doivent toujours être créés en mode Création, car InfoPath ajoute automatiquement la déclaration appropriée pour la réception de l'événement dans la méthode InternalStartup et insère le squelette du code du gestionnaire d'événements dans le fichier de code d'un formulaire (FormCode.cs ou FormCode.vb). Après avoir créé un gestionnaire d'événement, ne modifiez pas sa déclaration 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.
Présentation des classes d'événements
Le modèle InfoPath fourni par l'espace de noms Microsoft.Office.InfoPath implémente trois classes qui mettent en œuvre les 12 événements pouvant survenir et être gérés par la logique métier du modèle de formulaire. Le tableau suivant contient la liste de tous les objets d'événements InfoPath, les événements auxquels ils sont associés et une description de leur fonction.
| Nom | Événements | Description |
|---|---|---|
La classe ButtonEvent implémente l'événement Clicked lors d'un clic sur un contrôle Bouton dans un formulaire. |
||
La classe FormEvents implémente les événements spécifiques à un modèle de formulaire InfoPath lui-même : ContextChanged Se produit après une modification du nœud de contexte. Loading Se produit après le chargement du modèle de formulaire mais avant l'initialisation d'une vue quelconque. Merge Se produit lors de l'appel de la commande Fusionner les formulaires dans l'interface utilisateur ou du démarrage d'InfoPath avec le commutateur de ligne de commande Save Se produit lors de l'utilisation de la commande Enregistrer ou Enregistrer sous dans l'interface utilisateur ou lors d'un appel aux méthodes Save et SaveAs de la classe XmlForm. Sign Se produit une fois qu'un ensemble de données signées a été sélectionné pour une signature par l'intermédiaire de la boîte de dialogue Signatures numériques. Submit Se produit lors de l'utilisation de la commande Envoyer dans l'interface utilisateur ou de l'appel de la méthode Submit de la classeXmlForm. VersionUpgrade Se produit lorsque le numéro de version du formulaire en cours d'ouverture est antérieur à celui du modèle de formulaire sur lequel il est basé. ViewSwitched Se produit lors d'un changement de vue réussi d'un formulaire. |
||
Implémente les événements déclenchés par les modifications apportées aux données du document XML sous-jacent d'une instance de formulaire : Changed Se produit après l'acceptation des modifications dans le document XML sous-jacent d'un formulaire et à la suite de l'événement Validating. Changing Se produit après que des modifications ont été apportées au document XML sous-jacent d'un formulaire mais avant qu'elles aient été acceptées. Validating Se produit après l'acceptation des modifications effectuées dans le document XML sous-jacent d'un formulaire, mais avant l'événement Changed. La classe XmlEvent implémente également la propriété RaiseUndoRedoForChanged qui obtient ou définit si l'événement Changed sera déclenché au cours d'une opération d'annulation ou de rétablissement. |
.gif) Remarque |
|---|
Les événements Changed et Changing ne se déclenchent que lorsqu'une modification est effectuée dans un champ non vide du formulaire, tandis que les événements comparables dans InfoPath 2003 et le modèle d'objet compatible InfoPath 2003 fourni par l'espace de noms Microsoft.Office.Interop.InfoPath.SemiTrust (OnBeforeChange et OnAfterChange) se déclenchent deux fois lorsqu'une modification est apportée à un champ non vide, lors de la suppression de l'ancienne valeur et lors de l'insertion de la nouvelle valeur. |
Vue d'ensemble des classes EventArgs
Chacun des 12 événements ont un objet EventArgs associé à l'événement transmis au gestionnaire d'événements afin que l'événement fournisse des informations d'état et d'autres fonctionnalités qui peuvent être utilisées dans le code du gestionnaire d'événements. Le tableau suivant recense les événements InfoPath et les objets EventArgs associés, ainsi qu'une brève description des fonctionnalités fournies par les propriétés et les méthodes de l'objet. Pour plus d'informations sur les propriétés et les méthodes spécifiques de l'objet, cliquez sur le nom de l'objet EventArgs dans le tableau, puis cliquez sur le lien Membres dans la rubrique.
| Événement | Classe EventsArgs | Description |
|---|---|---|
Clicked |
Obtient l'ID du contrôle. Obtient un objet XPathNavigator placé sur le nœud XML le plus au centre du document XML sous-jacent du formulaire qui contient le contrôle Bouton. |
|
ContextChanged |
Obtient le type de modification de contexte qui a été effectué au moment où l'événement s'est produit. Obtient une valeur indiquant si l'événement de modification de contexte s'est produit en réponse à l'annulation ou au rétablissement d'une opération. Obtient une référence à un élément XPathNavigator placé sur le nœud du contexte qui a déclenché l'événement. |
|
Loading |
Spécifie la vue dans laquelle ouvrir le formulaire après le chargement. Obtient une référence à l'objet XmlFormCancelEventArgs. Obtient un IDictionary contenant des paramètres d'entrée spécifiés à l'aide de l'option de ligne de commande |
|
Merge |
Obtient une référence à l'objet XmlFormCancelEventArgs. Obtient le nombre de formulaires fusionnés dans une opération de fusion. Obtient l'index de base 0 du formulaire en cours de fusion. Obtient ou définit une valeur utilisée avec la propriété Cancel pour déterminer s'il faut uniquement annuler la fusion du formulaire actif ou toute l'opération de fusion. Obtient un objet XPathNavigator placé au niveau du nœud racine du document XML sous-jacent du formulaire actuellement fusionné. |
|
Save |
Effectue l'opération d'enregistrement demandée par l'utilisateur. Obtient une référence à l'objet SaveCancelEventArgs qui peut être utilisé pour annuler l'événement. Obtient le nom de fichier à utiliser dans le gestionnaire d'événements correspondant à cet événement. Obtient les informations indiquant si l'opération d'enregistrement est de de type « Enregistrer » ou « Enregistrer sous ». |
|
Sign |
Obtient ou définit l'affichage de la boîte de dialogue Signatures numériques. Obtient le jeu de données signables qui a déclenché l'événement. |
|
Submit |
Obtient une référence à l'objet XmlFormCancelEventArgs pour annuler l'événement. |
|
VersionUpgrade |
Obtient une référence à l'objet XmlFormCancelEventArgs pour annuler l'événement. Obtient le numéro de version du document de formulaire mis à niveau. Obtient le numéro de version du modèle de formulaire associé au formulaire mis à niveau. |
|
ViewSwitched |
La classe ViewSwitchedEventArgs ne fournit pas les propriétés et les méthodes associées aux événements autres que ceux qui sont hérités de System.Object. |
|
Changed |
Obtient un objet XPathExpression qui contient une expression XPath renvoyant le nœud actuellement modifié. Obtient la nouvelle valeur du nœud modifié. Obtient un objet XPathNavigator pointant sur le nœud qui est le parent du nœud en cours de suppression. Obtient la valeur d'origine du nœud modifié. Obtient une énumération XmlOperation qui indique le type d'opération qui s'est produit lorsque le nœud a changé. Obtient un objet XPathNavigator pointant vers le nœud modifié. Obtient une valeur indiquant si le nœud modifié fait partie d'une opération d'annulation ou de rétablissement. |
|
Changing |
Obtient un objet XmlFormCancelEventArgs associé à l'événement. Hérite de toutes les fonctionnalités énumérées ci-dessus pour l'objet XmlEventArgs. |
|
Validating |
Crée un objet FormError qui contient des informations d'erreur personnalisées avec les valeurs spécifiées et les ajoute à l'objet FormErrorCollection du formulaire. Hérite de toutes les fonctionnalités énumérées ci-dessus pour l'objet XmlEventArgs. |
Utilisation des objets EventArgs
Lorsque vous créez un gestionnaire d'événements, InfoPath crée la déclaration de celui-ci dans le code de formulaire du projet. Dans cette déclaration, InfoPath utilise e comme nom du paramètre transmis au gestionnaire d'événements. Ce paramètre contient l'objet EventArgs qui est associé au gestionnaire d'événements pour fournir les informations d'état et d'autres fonctionnalités lorsque l'événement se produit.
Par exemple, lorsque vous créez un gestionnaire d'événements pour l'événement Loading en mode Création (en cliquant sur le menu Outils, en pointant sur Programmation, puis en cliquant sur Événement Chargement en cours (Loading)), InfoPath ajoute la déclaration du gestionnaire d'événements qui reçoit l'objet LoadingEventArgs 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 suivante.
public void FormEvents_Loading(object sender, LoadingEventArgs e)
{
// Write your code here.
}
Public Sub FormEvents_Loading(ByVal sender As Object, _
ByVal e As LoadingEventArgs)
' 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 EventArgs transmis par le paramètre e. Par exemple, dans le gestionnaire d'événements Changing suivant, la propriété NewValue de l'objet XmlChangingEventArgs (hérité de la classe XmlEventArgs) permet de vérifier la valeur du champ qui vient d'être modifié. Si l'utilisateur a modifié ce champ et l'a laissé vide, la propriété Message de la classe XmlFormCancelEventArgs est accessible à l'aide de la propriété CancelableArgs de l'objet XmlChangingEventArgs pour afficher une erreur pour l'utilisateur, et la propriété XmlFormCancelEventArgs.Cancel est définie sur true pour annuler l'événement et les modifications entrées par l'utilisateur.
public void field1_Changing(object sender, LoadingEventArgs e)
{
// Determine whether there is a new value.
if (e.NewValue == "")
{
// The value is blank, so display an error message
// and roll back the changes.
e.CancelableArgs.Message =
"You must supply a value for this field.";
e.CancelableArgs.Cancel = true;
return;
}
}
Public Sub field1_Changing(ByVal sender As Object, _
ByVal e As LoadingEventArgs)
' 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.CancelableArgs.Message = _
"You must supply a value for this field."
e.CancelableArgs.Cancel = True
Return
End If
End Sub