[方法] フォーム イベントに応答する方法

ユーザーがフォームに入力する際に発生する各種イベントに応答するコードを書くことができます。InfoPath 内でイベントの作業を実行するには、デザイン モードのフォーム テンプレートの作業中にイベント ハンドラを追加します。

InfoPath イベント ハンドラは常にデザイン モードで作成する必要があります。これは、InfoPath ではイベントを InternalStartup メソッドにシンクするための正しい宣言が自動的に追加され、イベント ハンドラのコード スケルトンがフォームのコード ファイル (FormCode.cs または FormCode.vb) に挿入されるためです。イベント ハンドラを作成した後、フォームのコード ファイルの宣言は変更しないでください。

InfoPath イベント ハンドラの作成の詳細については、「[方法] イベント ハンドラを追加する方法」を参照してください。

イベント クラスの概要

Microsoft.Office.InfoPath 名前空間によって提供される InfoPath モデルでは、12 個のイベントを実装する 3 つのクラスを実装します。イベントはフォーム テンプレート ビジネス ロジックにより発生させ、処理することができます。次の表に、各 InfoPath イベント オブジェクト、関連付けられたイベント、およびその機能を示します。

名前	イベント	説明
ButtonEvent	Clicked	ButtonEvent クラスは、フォーム上の [ボタン] コントロールがクリックされると発生する Clicked イベントを実装します。
FormEvents	ContextChanged Loading Merge Save Sign Submit VersionUpgrade ViewSwitched	FormEvents クラスは、InfoPath フォーム テンプレート自体に固有のイベントを実装します。 ContextChanged コンテキスト ノードが変更されると発生します。 Loading フォーム テンプレートが読み込まれた後、ビューが初期化される前に発生します。 Merge [フォームの結合] コマンドがユーザー インターフェイスから起動される、または /aggregate コマンド ライン スイッチを指定して InfoPath が開始されると発生します。 Save ユーザー インターフェイスから [保存] または [名前を付けて保存] コマンドが使用される、または XmlForm クラスの Save メソッドおよび SaveAs メソッドが使用されると発生します。 Sign [デジタル署名] ダイアログ ボックスで署名することになる署名データが選択されると発生します。 Submit ユーザー インターフェイスから [送信] コマンドが使用される、または XmlForm クラスの Submit メソッドが使用されると発生します。 VersionUpgrade 開かれているフォームのバージョン番号が、基になっているフォーム テンプレートのバージョン番号よりも古いと発生します。 ViewSwitched フォームのビューの切り替えが成功した後で発生します。
XmlEvent	Changed Changing Validating	フォーム インスタンスの基になっている XML ドキュメントのデータに対する変更によって発生するイベントを実装します。 Changed フォームの基になっている XML ドキュメントの変更が受け付けられ、Validating イベントが発生した後、発生します。 Changing フォームの基になっている XML ドキュメントに対する変更が行われた後で、変更が受け付けられる前に発生します。 Validating フォームの基になっている XML ドキュメントの変更が受け付けられた後、Changed イベントが発生する前に発生します。 XmlEvent クラスは、RaiseUndoRedoForChanged プロパティも実装します。このプロパティは、元に戻す操作またはやり直し操作が実行されたときに Changed イベントが発生するかどうかを取得または設定します。

メモ :
Changed イベントと Changing イベントは、フォームの空白ではないフィールドが変更されたときに 1 回だけ発生します。一方、Microsoft.Office.Interop.InfoPath.SemiTrust 名前空間によって提供される InfoPath 2003 と InfoPath 2003 互換のオブジェクト モデルの類似したイベント (OnBeforeChange と OnAfterChange) は、フォームの空白ではないフィールドの変更時に 2 回発生します。つまり、古い値が削除されたときに 1 回、新しい値が挿入されたときにもう 1 回発生します。

EventArgs クラスの概要

12 個の各イベントには、イベント ハンドラに渡される EventArgs オブジェクトが関連付けられています。このオブジェクトにより、イベント ハンドラ コードで使用できるイベントの状態情報およびその他の機能が提供されます。次の表に、InfoPath イベント、関連付けられた EventArgs オブジェクト、およびオブジェクトのプロパティとメソッドで提供される機能の簡単な説明を示します。オブジェクトの特定のプロパティとメソッドの詳細については、表の EventArgs オブジェクトの名前をクリックし、トピックの [メンバ] リンクをクリックしてください。

イベント	EventsArgs クラス	説明
Clicked	ClickedEventArgs	コントロール ID を取得します。 [ボタン] コントロールを含む、フォームの基になる XML ドキュメントで、最も内側の XML ノードに置かれている XPathNavigator オブジェクトを取得します。
ContextChanged	ContextChangedEventArgs	イベントが発生したときに実行されたコンテキスト変更の種類を取得します。 操作を元に戻したかやり直したことによって、コンテキスト変更が発生したかどうかを示す値を取得します。 イベントが発生したコンテキスト ノードに置かれていた XPathNavigator への参照を取得します。
Loading	LoadingEventArgs	読み込み後にフォームを開くビューを指定します。 XmlFormCancelEventArgs オブジェクトへの参照を取得します。 /InputParameters コマンド ライン オプションを使用して、またはフォームを開く URL のクエリ パラメータを使用して指定された入力パラメータを含む IDictionary を取得します。
Merge	MergeEventArgs	XmlFormCancelEventArgs オブジェクトへの参照を取得します。 結合操作で結合されるフォームの数を取得します。 現在結合されているフォームの、ゼロベースのインデックスを取得します。 現在のフォームだけをキャンセルするのか、または結合操作全体をキャンセルするのかを判別するために、Cancel プロパティと共に使用する値を取得または設定します。 現在結合されているフォームの基になっている XML ドキュメントのルート ノードに配置されている XPathNavigator オブジェクトを取得します。
Save	SaveEventArgs	ユーザーによって要求された保存操作を実行します。 イベントの取り消しに使用できる SaveCancelEventArgs オブジェクトへの参照を取得します。 イベントに対するイベント ハンドラで使用するファイル名を取得します。 保存操作が "保存" 操作として実行されるか "名前を付けて保存" として実行されるかを取得します。
Sign	SignEventArgs	[デジタル署名] ダイアログ ボックスを表示するかどうかを取得または設定します。 イベントを発生させた署名可能なデータのセットを取得します。
Submit	SubmitEventArgs	イベントをキャンセルする XmlFormCancelEventArgs オブジェクトへの参照を取得します。
VersionUpgrade	VersionUpgradeEventArgs	イベントをキャンセルする XmlFormCancelEventArgs オブジェクトへの参照を取得します。 アップグレード中のフォーム ドキュメントのバージョン番号を取得します。 アップグレード中のフォームに関連付けられたフォーム テンプレートのバージョン番号を取得します。
ViewSwitched	ViewSwitchedEventArgs	ViewSwitchedEventArgs クラスには、イベントに対して System.Object から継承される以外のプロパティとメソッドはありません。
Changed	XmlEventArgs	現在変更中のノードを返す XPath 式を含む XPathExpression オブジェクトを取得します。 変更中のノードの新しい値を取得します。 削除中のノードの親であるノードを示す XPathNavigator オブジェクトを取得します。 変更中のノードの元の値を取得します。 ノードが変更されたときに発生した操作の種類を示す XmlOperation 列挙を取得します。 変更中のノードを示す XPathNavigator オブジェクトを取得します。 変更中のノードが、元に戻すまたはやり直す操作の一部であるかどうかを示す値を取得します。
Changing	XmlChangingEventArgs	イベントに関連付けられた XmlFormCancelEventArgs オブジェクトを取得します。 上記の XmlEventArgs オブジェクトの機能をすべて継承します。
Validating	XmlValidatingEventArgs	指定した値を持つカスタム エラー情報の入った FormError オブジェクトを作成し、それをフォームの FormErrorCollection オブジェクトに追加します。 上記の XmlEventArgs オブジェクトの機能をすべて継承します。

EventArgs オブジェクトを使用する

イベント ハンドラを作成する際、InfoPath は、プロジェクトのフォーム コード ファイル内でイベント ハンドラの宣言を作成します。イベント ハンドラの宣言内で、InfoPath は、イベント ハンドラに渡されるパラメータの名前として e を使用します。 このパラメータには、イベント発生時に状態情報とその他の機能を提供するイベント ハンドラに関連付けられる EventArgs オブジェクトが含まれます。

たとえば、[ツール] メニューをクリックして [プログラミング] をポイントし、[Loading イベント] をクリックすることで、デザイン モードで Loading イベントのイベント ハンドラを作成する際、InfoPath は、LoadingEventArgs オブジェクトを受け取るイベント ハンドラの宣言をフォーム コード ファイルに追加し、次のイベント ハンドラ宣言にコードを追加するためのコード エディタを開きます。

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

イベント ハンドラのコードを書く際、e パラメータを通じて渡される EventArgs イベント オブジェクトによって実装されるプロパティとメソッドを使用できます。 たとえば、次の Changing イベント ハンドラでは、XmlChangingEventArgs オブジェクトの NewValue プロパティ (XmlEventArgs クラスから継承) を使用して、変更されたフィールドの値が確認されます。ユーザーがフィールドを変更し、空白にした場合、XmlChangingEventArgs オブジェクトの CancelableArgs プロパティを使用して、XmlFormCancelEventArgs クラスの Message プロパティにアクセスし、ユーザーにエラーを表示し、XmlFormCancelEventArgs.Cancel プロパティを true に設定してイベントをキャンセルし、ユーザーが行った変更内容をロールバックします。

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