Procedura: Rispondere agli eventi del modulo

È possibile scrivere codice per rispondere ai vari eventi che possono verificarsi quando un utente compila un modulo. Per utilizzare gli eventi in InfoPath, è possibile creare gestori eventi da un modello di modulo in modalità progettazione.

È necessario creare sempre i gestori eventi di InfoPath in modalità progettazione in quanto in InfoPath viene aggiunta automaticamente la dichiarazione corretta per l'elaborazione dell'evento nel metodo InternalStartup e la bozza di codice del gestore eventi viene inserita in un file di codice del modulo denominato FormCode.cs o FormCode.vb. Dopo aver creato un gestore eventi, è consigliabile non modificarne la dichiarazione nel file di codice del modulo.

Per informazioni sulla creazione dei gestori eventi di InfoPath, vedere Procedura: Aggiungere un gestore eventi.

Informazioni generali sulle classi Event

Il modello di InfoPath incluso nello spazio dei nomi Microsoft.Office.InfoPath implementa tre classi, le quali utilizzano i dodici eventi che è possibile generare e gestire tramite la regola business del modello di modulo. Nella tabella seguente sono elencati i singoli oggetti evento di InfoPath, gli eventi a cui sono associati e una descrizione delle funzionalità offerte.

Nome	(eventi)	Descrizione
ButtonEvent	Clicked	La classe ButtonEvent implementa l'evento Clicked generato quando si fa clic su un controllo Pulsante in un modulo.
FormEvents	ContextChanged Loading Merge Save Sign Submit VersionUpgrade ViewSwitched	La classe FormEvents implementa gli eventi specifici di un modello di modulo di InfoPath: ContextChanged Generato dopo la modifica del nodo di contesto. Loading Generato quando il modello di modulo è stato caricato, ma prima che venga inizializzata una visualizzazione. Merge Generato quando viene richiamato il comando Unisci moduli dall'interfaccia utente o quando InfoPath viene avviato con l'opzione della riga di comando /aggregate. Save Generato quando viene utilizzato il comando Salva o Salva con nome dall'interfaccia utente oppure quando vengono utilizzati i metodi Save e SaveAs della classe XmlForm. Sign Generato dopo che un blocco di dati firmati è stato selezionato per la firma tramite la finestra di dialogo Firme digitali. Submit Generato quando viene utilizzato il comando Invia dall'interfaccia utente o il metodo Submit della classe XmlForm. VersionUpgrade Generato quando il numero di versione del modulo da aprire è meno recente di quello del modello di modulo su cui è basato. ViewSwitched Generato dopo che si è passati a un'altra visualizzazione di un modulo.
XmlEvent	Changed Changing Validating	Implementa gli eventi generati dalle modifiche ai dati nel documento XML sottostante di un'istanza di un modulo. Changed Generato dopo che le modifiche al documento XML sottostante di un modulo sono state accettate e dopo l'evento Validating. Changing Generato dopo che sono state apportate modifiche al documento XML sottostante di un modulo ma prima che tali modifiche siano state accettate. Validating Generato dopo che le modifiche al documento XML sottostante di un modulo sono state accettate ma prima dell'evento Changed. La classe XmlEvent implementa inoltre la proprietà RaiseUndoRedoForChanged, che ottiene o imposta l'evento Changed generato quando viene eseguita un'operazione Annulla o Ripristina.

Nota:

Gli eventi Changed e Changing vengono generati solo una volta quando viene apportata una modifica a un campo non vuoto del modulo, mentre gli eventi che possono essere confrontati in InfoPath 2003 e nel modello a oggetti compatibile con InfoPath 2003 inclusi nello spazio dei nomi Microsoft.Office.Interop.InfoPath.SemiTrust (OnBeforeChange e OnAfterChange) vengono attivati due volte in caso di modifiche a un campo non vuoto: una volta quando viene eliminato il valore precedente e una seconda volta quando viene inserito il nuovo valore.

Informazioni generali sulle classi EventArgs

Ognuno dei dodici eventi, che dispone di un oggetto EventArgs associato, viene passato al relativo gestore eventi per fornire informazioni sullo stato e altre funzionalità che possono essere utilizzate nel codice del gestore eventi. Nella tabella seguente sono elencati gli eventi di InfoPath con i relativi oggetti EventArgs associati e una breve descrizione delle funzionalità offerte dalle proprietà e dai metodi dell'oggetto. Per ulteriori informazioni sulle proprietà e sui metodi specifici dell'oggetto, fare clic sul nome dell'oggetto EventArgs nella tabella e quindi sul collegamento Membri nell'argomento.

Evento	Classe EventsArgs	Descrizione
Clicked	ClickedEventArgs	Ottiene l'ID del controllo. Ottiene un oggetto XPathNavigator posizionato nel nodo XML più interno del documento XML sottostante del modulo che contiene il controllo Pulsante.
ContextChanged	ContextChangedEventArgs	Ottiene il tipo di modifica del contesto eseguita quando si è verificato l'evento. Ottiene un valore che indica se l'evento di modifica del contesto si è verificato in risposta all'annullamento o al ripristino di un'operazione. Ottiene un riferimento a un oggetto XPathNavigator posizionato nel nodo di contesto che ha generato l'evento.
Loading	LoadingEventArgs	Specifica la visualizzazione in cui deve essere aperto il modulo dopo il caricamento. Ottiene un riferimento all'oggetto XmlFormCancelEventArgs. Ottiene un oggetto IDictionary contenente eventuali parametri di input specificati utilizzando l'opzione della riga di comando /InputParameters oppure utilizzando parametri di query in un URL per aprire il modulo.
Merge	MergeEventArgs	Ottiene un riferimento all'oggetto XmlFormCancelEventArgs. Ottiene il numero di moduli inclusi in un'operazione di unione. Ottiene l'indice a base zero del modulo di cui è in corso l'unione. Ottiene o imposta un valore utilizzato con la proprietà Cancel per determinare se annullare solo il modulo corrente o l'intera operazione di unione. Ottiene un oggetto XPathNavigator posizionato nel nodo principale del documento XML sottostante del modulo di cui è in corso l'unione.
Save	SaveEventArgs	Esegue l'operazione di salvataggio richiesta dall'utente. Ottiene un riferimento all'oggetto SaveCancelEventArgs che può essere utilizzato per annullare l'evento. Ottiene il nome del file da utilizzare nel gestore eventi per l'evento. Ottiene l'operazione di salvataggio da eseguire come operazione "Salva" o "Salva con nome".
Sign	SignEventArgs	Ottiene o imposta la visualizzazione della finestra di dialogo Firme digitali. Ottiene il blocco di dati firmabile che ha generato l'evento.
Submit	SubmitEventArgs	Ottiene un riferimento all'oggetto XmlFormCancelEventArgs per annullare l'evento.
VersionUpgrade	VersionUpgradeEventArgs	Ottiene un riferimento all'oggetto XmlFormCancelEventArgs per annullare l'evento. Ottiene il numero di versione del documento del modulo di cui è in corso l'aggiornamento. Ottiene il numero di versione del modello di modulo associato al modulo di cui è in corso l'aggiornamento.
ViewSwitched	ViewSwitchedEventArgs	La classe ViewSwitchedEventArgs non include proprietà e metodi per l'evento diversi da quelli ereditati da System.Object.
Changed	XmlEventArgs	Ottiene un oggetto XPathExpression contenente un'espressione XPath che restituisce il nodo di cui è attualmente in corso la modifica. Ottiene il nuovo valore per il nodo di cui è in corso la modifica. Ottiene un oggetto XPathNavigator che punta al nodo padre del nodo di cui è in corso l'eliminazione. Ottiene il valore originale del nodo di cui è in corso la modifica. Ottiene un'enumerazione XmlOperation che indica il tipo di operazione eseguita quando il nodo è stato modificato. Ottiene un oggetto XPathNavigator che punta al nodo di cui è in corso la modifica. Ottiene un valore che indica se il nodo di cui è in corso la modifica fa parte di un'operazione Annulla o Ripristina.
Changing	XmlChangingEventArgs	Ottiene un oggetto XmlFormCancelEventArgs associato all'evento. Eredita tutte le funzionalità sopra elencate per l'oggetto XmlEventArgs.
Validating	XmlValidatingEventArgs	Crea un oggetto FormError contenente informazioni sull'errore personalizzato con i valori specificati e lo aggiunge all'oggetto FormErrorCollection del modulo. Eredita tutte le funzionalità sopra elencate per l'oggetto XmlEventArgs.

Utilizzo degli oggetti EventArgs

Quando si crea un gestore eventi, in InfoPath viene creata la dichiarazione del gestore eventi nel codice del modulo del progetto. In tale dichiarazione viene utilizzato automaticamente e come nome del parametro passato al gestore eventi. Questo parametro contiene l'oggetto EventArgs associato al gestore eventi per fornire informazioni sullo stato e altre funzionalità quando si verifica l'evento.

Se ad esempio si crea un gestore eventi per l'evento Loading in modalità progettazione (scegliendo Programmazione dal menu Strumenti e quindi Evento di caricamento), in InfoPath viene aggiunta al file di codice del modulo la dichiarazione per il gestore eventi che riceve l'oggetto LoadingEventArgs e quindi viene aperto l'editor di codice per consentire l'aggiunta del codice alla dichiarazione del gestore eventi seguente.

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

Quando si scrive il codice per un gestore eventi, è possibile utilizzare le proprietà e i metodi implementati dall'oggetto EventArgs passato tramite il parametro e. Nel gestore eventi Changing seguente, ad esempio, la proprietà NewValue dell'oggetto XmlChangingEventArgs ereditata dalla classe XmlEventArgs viene utilizzata per controllare il valore del campo appena modificato. Se l'utente ha modificato il campo lasciandolo vuoto, si accede alla proprietà Message della classe XmlFormCancelEventArgs utilizzando la proprietà CancelableArgs dell'oggetto XmlChangingEventArgs per visualizzare un errore e la proprietà XmlFormCancelEventArgs.Cancel viene impostata su true per annullare l'evento ed eseguire il rollback delle modifiche apportate dall'utente.

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