Procedura: Rispondere agli eventi del modulo utilizzando il modello a oggetti di InfoPath 2003

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

È consigliabile creare i gestori eventi di InfoPath in modalità progettazione perché, se si utilizza il modello a oggetti compatibile con InfoPath 2003, in InfoPath viene aggiunta automaticamente la dichiarazione corretta e viene applicato un attributo (InfoPathEventHandlerAttribute) nel file di codice di un modulo (FormCode.cs o FormCode.vb) per identificare ed elaborare il gestore eventi. Dopo avere creato un gestore eventi, evitare di modificare la dichiarazione e l'attributo nel file di codice del modulo.

Per informazioni sulla creazione dei gestori eventi di InfoPath, vedere Procedura: Aggiungere un gestore eventi tramite il modello a oggetti di InfoPath 2003.

Informazioni generali sugli oggetti evento

Il modello a oggetti compatibile con InfoPath 2003 implementa nove oggetti evento che vengono esposti nello spazio dei nomi Microsoft.Office.Interop.InfoPath.SemiTrust. Nella tabella seguente è incluso un elenco dei nove oggetti evento di InfoPath e dei relativi gestori eventi associati, insieme a una descrizione delle rispettive funzionalità.

Nome	Gestori eventi	Descrizione
DataDOMEvent	OnBeforeChange OnValidate, OnAfterChange	Restituisce un riferimento al documento XML sottostante di un modulo, lo stato restituito e altre proprietà che contengono informazioni sul nodo XML durante una modifica del modello a oggetti DOM XML. Include inoltre un metodo per la generazione di errori.
DocActionEvent	OnClick	Restituisce un riferimento al documento XML sottostante di un modulo, lo stato restituito e il nodo XML di origine quando si fa clic su un pulsante nell'area del modulo.
DocContextChangeEvent	OnContextChange	Restituisce informazioni sul nodo DOM (Document Object Model) XML che rappresenta il contesto corrente del documento XML sottostante del modulo.
DocEvent	OnSwitchView, OnAfterImport	Restituisce un riferimento al documento XML sottostante di un modulo quando si cambia visualizzazione o si esegue un'operazione di unione di moduli.
DocReturnEvent	OnLoad, OnSubmitRequest	Restituisce un riferimento al documento XML sottostante di un modulo e lo stato restituito durante il caricamento o l'invio di un modulo.
MergeEvent	OnMergeRequest	Restituisce i metodi e le proprietà che possono essere utilizzati durante un evento OnMergeRequest per interagire a livello di programmazione con il documento XML sottostante di un modulo e determinare le proprietà di unione, come il numero di file da unire.
SaveEvent	OnSaveRequest	Restituisce numerosi metodi e proprietà che possono essere utilizzati durante un'operazione di salvataggio dal gestore eventi OnSaveRequest per interagire a livello di programmazione con il documento XML sottostante di un modulo, determinare le proprietà di salvataggio e quindi eseguire l'operazione di salvataggio.
SignEvent	OnSign	Utilizzato per aggiungere ulteriori dati alla firma digitale.
VersionUpgradeEvent	OnVersionUpgrade	Restituisce un riferimento al documento XML sottostante di un modulo, lo stato restituito e i numeri di versione del documento e della soluzione durante l'operazione di aggiornamento della versione.

Utilizzo degli oggetti evento

Quando si crea un gestore eventi, in InfoPath viene creata la dichiarazione del gestore eventi nel file di codice del modulo del progetto (FormCode.cs o FormCode.vb). Nella dichiarazione viene utilizzato e come nome del parametro passato al gestore eventi. Questo parametro contiene l'oggetto evento associato al gestore eventi.

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

// 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

Quando si scrive il codice per un gestore eventi, è possibile utilizzare le proprietà e i metodi implementati dall'oggetto evento passato tramite il parametro e. Ad esempio, nel gestore eventi OnBeforeChange seguente, viene utilizzata la proprietà NewValue dell'oggetto evento DataDOMEvent per verificare il valore del campo appena modificato. Se il campo è vuoto, viene utilizzata la proprietà ReturnMessage dell'oggetto evento DataDOMEvent per visualizzare all'utente un errore in una finestra di dialogo e viene impostata la proprietà ReturnStatus su false, a indicare che le modifiche apportate dall'utente non devono essere accettate.

[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

Nota:
Ogni oggetto evento di InfoPath nel modello a oggetti compatibile con InfoPath 2003 implementa diversi metodi e proprietà. Per ulteriori informazioni su un oggetto evento specifico, fare clic sull'oggetto desiderato nella tabella Oggetti evento.