BIRT レポート・レイアウト・イベント・ハンドラー
各レポート・レイアウト・イベント・ハンドラーは、レポートに表示される BIRT レポート要素へのアクセスを提供します。 このような要素をレポート・レイアウト要素 と呼んでおり、 データ・ソースまたはデータ・セットを表す要素と区別しています。
- eventType プロパティーは、onCreate であるか (レポート・レイアウト要素の作成中にハンドラーが呼び出されるため)、または onPageBreak です (直前のページのいずれかの位置にあるレポート・レイアウト要素の使用後に実行される改ページ中に、 ハンドラーが呼び出されるため)。
- 最初のパラメーターの値は、レポート・レイアウト要素の個々の型に基づいています。 例えば、最初のパラメーターが LabelInstance 型である場合、イベント・ハンドラーに渡されるレポート・レイアウト要素には、ラベル (HTML のフォーマット設定がないレポート・テキスト) に固有の詳細が含まれています。 また、最初のパラメーターの型は、ハンドラーで有効なプロパティーが何であるか (必須の eventType と elementName 以外) を判別する上で役立ちます。
- onPageBreak を参照するイベント・ハンドラーに関して、以下の注意点があります。
- レポートのテーブルまたはグリッドが複数のページに表示される場合、そのテーブルまたはグリッドに関連したイベント・ハンドラーは改ページごとに呼び出されます。
- レポート・レイアウト要素 (例えば、ラベルなど) がテーブルまたはグリッドにある場合、そのレポート要素に関連したイベント・ハンドラーは、その要素がページごとに複数回繰り返すことのできるものであっても、ページごとに 1 回だけ呼び出されます。
- イベント・ハンドラーの呼び出し順序が、そのままレポート・レイアウト要素の表示順序になります。
- ハンドラーには、ReportContext 型のパラメーターが必ず含まれています。ユーザーはこのパラメーターによって、イベント・ハンドラーの呼び出し時にレポート・パラメーター値を取得または設定することができます。 例えば、自身の実行時の値をレポートに表示する機能を持つ式で使用するレポート・パラメーターを、特定の値に設定する場合などです。
function myLabelFunction( theLabel LabelInstance, theContext ReportContext )
{ eventType = onCreate, elementName = "remark_label" }
balance float = theLabel.getRowData().getColumnValue("account_balance");
if( balance > 0 )
theLabel.text = "Balance Due";
theLabel.getStyle().color = "red";
end
end
この例では、レポート・パラメーターではなく、theLabel というイベント・ハンドラー・パラメーターを使用して、account_balance という結合式を参照し、remark_label というラベルを更新しています。 account_balance および remark_label という名前は、レポート設計ファイルで指定されているものです。
データ要素 (account_balance) の内容をレポート・レイアウト・イベント・ハンドラー内で更新することはできませんが、上記の例で示されているとおり、ラベルは更新することができます。 より一般的に言うならば、レポート・レイアウト・イベント・ハンドラーは、1 つ以上のレポート・レイアウト要素のスタイルを設定することができます。
それぞれのイベント・ハンドラー・パラメーター (theLabel など) は、Java™ インターフェースを表す EGL 外部型に基づいています。 次の表は、レポート・レイアウト・イベント・ハンドラーの各パラメーターの型および目的と、関連する Java インターフェースの非修飾名を示したものです。 表の 3 番目の列は、eventType と elementName 以外のプロパティーを指定できるかどうかを示しています。
| EGL 外部型 | 用途 | eventType と elementName 以外のプロパティー (後述) | Java インターフェース |
|---|---|---|---|
| CellInstance | レポートのグリッドまたはテーブル内のセルにアクセスする。 | グリッドに対して CellInstance を使用する場合に使用可能なプロパティーは、columnNumber と rowNumber です (いずれもオプション)。テーブルに対して CellInstance を使用する場合に使用可能なプロパティーは rowType (必須)、columnNumber と rowNumber (いずれもオプション)、および groupName (rowType の値が groupHeader または groupFooter の場合に必須) です。 | ICellInstance |
| DataInstance | データ・ソースまたは計算からのデータを含むフィールドにアクセスする。 | IDataItemInstance | |
| DynamicTextInstance | メモの内容などの文字ラージ・オブジェクト (CLOB) データを含むフィールドにアクセスする。 | IDynamicTextInstance | |
| GridInstance | 単純なテーブル状の構造であるグリッド内のフィールドにアクセスする。 | IGridInstance | |
| ImageInstance | データ・セット・フィールド、ローカル・ファイル・システム、リモート・ロケーションなどにあるイメージ、またはレポート設計ファイルに組み込まれたイメージにアクセスする。 | IImageInstance | |
| LabelInstance | HTML のフォーマット設定がなく、算出値を表さないラベルにアクセスする。 | ILabelInstance | |
| ListInstance | リストにアクセスする。 | IListInstance | |
| ReportContext | レポート・パラメーター値を取得または設定する。 | IReportContext | |
| RowInstance | レポートのグリッドまたはテーブル内の特定の行にアクセスする。 | グリッドに対して RowInstance を使用した場合は、オプションの rowNumber プロパティーが使用可能です。テーブルに対して RowInstance を使用した場合、使用可能なプロパティーは rowType (必須)、rowNumber (オプション)、および groupName (rowType の値が groupHeader または groupFooter の場合に必須) です。 | IRowInstance |
| TableInstance | テーブルにアクセスする。 | ITableInstance | |
| TextInstance | HTML のフォーマット設定があるテキスト、または算出値を表すテキストにアクセスする。 | ITextItemInstance |
以下の表は、レポート・レイアウト・イベント・ハンドラーで使用されるその他 4 つの外部型を示したものです。
| EGL 外部型 | 用途 | Java インターフェース |
|---|---|---|
| ReportElementInstance | 前の表にリストされているいずれかの型の変数を使用する際に、追加の Java メソッドを提供する。 | IReportElementInstance (Java のスーパークラス) |
| ReportItemInstance | 前の表にリストされている (CellInstance と RowInstance 以外の) いずれかの型の変数を使用する際に、追加の Java メソッドを提供する。 | IReportItemInstance (Java のスーパークラス、IReportElementInstance に従属) |
| RowData | 一連の結合式の実行時の値にアクセスする。厳密には、ReportElementInstance の関数 getRowData() が返す内容を受け入れます。 | IRowData |
| Style | 使用中のスタイルに関する詳細にアクセスする。厳密には、ReportElementInstance の関数 getStyle() が返す内容を受け入れます。 | IScriptStyle |
外部型およびそれらの機能については、『BIRT レポート・レイアウト・イベント・ハンドラーの外部型』を参照してください。
Java 固有の詳細が必要になるとは限りませんが、各インターフェースについて説明した Javadoc が「BIRT レポート・スクリプト API リファレンス (BIRT Report Scripting API Reference)」に用意されています。 これは、製品のヘルプ・システムの「BIRT プログラマー・リファレンス (BIRT Programmer Reference)」>「リファレンス (Reference)」>「API リファレンス (API Reference)」>「BIRT レポート・スクリプト API リファレンス (BIRT Report Scripting API Reference)」にあります。 各 Java インターフェースは、2 つのものを例外として、 org.eclipse.birt.report.engine.api.script.instance パッケージの中にあります。 その例外 (IRowData および IReportContext) は、org.eclipse.birt.report.engine.api.script の中にあります。
イベント・ハンドラーのプロパティー
次の表は、前述のプロパティーについて説明したものです。
| プロパティー | 型 | コメント |
|---|---|---|
| columnNumber | INT | テーブル (またはグリッド) のセルを処理する際に列を特定します。 このプロパティーはオプションです。 |
| elementName | STRING | CellInstance と RowInstance 以外のすべてのレイアウト要素の型の場合、elementName はレポート要素自体の名前です。 CellInstance と RowInstance の場合、elementName は、セルまたは行があるテーブルまたはグリッドの名前です。 (このような違いがあるのは、BIRT Designer では、ユーザーがセルまたは行に名前を付けられないためです。) |
| eventType | EventTypeKind 列挙型: beforeOpen、openEvent など | 『EGL BIRT ハンドラー』の説明を参照してください。 |
| groupName | STRING | rowType の値が GroupHeader または GroupFooter の場合 (この場合、プロパティーは必須です) に、グループを特定します。 |
| rowNumber | INT | テーブル (またはグリッド) のセルまたは行を処理する際に行を特定します。 このプロパティーはオプションです。 |
| rowType | RowTypeKind 列挙型:
|
行の型を指定します。テーブルのセルまたは行に必須です。 グリッドのセルまたは行に対して指定された場合、このプロパティーは無視されます。 |
- 列および行の番号は、それぞれ 0 からではなく、1 から始まります。
- グリッドの行の場合、rowNumber プロパティーは、そのグリッドの中の位置を指し示します。
テーブルの行の場合、rowNumber プロパティーは、指定の行の型の中、または特定のグループ名が付いた指定の行の型の中の位置を指し示します。
(グループ名は、行の型が groupHeader または groupFooter である場合にのみ使用できます。)
以下に例を示します。
- 行番号 3 を指定し、rowType プロパティー値が detail である場合、EGL ランタイムは、3 番目の detail 行が作成されるたびにイベント・ハンドラーを呼び出します。
それぞれの detail 行自体 は row 型であり、1 つのレポートに複数回作成することができます。
例えば、データベース照会によって、それぞれ従業員の名前、住所、および肩書きが含まれているデータベース行のセットを検索する場合に、名前、住所、肩書きのそれぞれに対して 1 行ずつレポートの detail 行を定義する場合などです。
イベント・ハンドラーで 3 番目の detail 行を太字体にする処理を行った場合、出力は以下のようになります。
Sales: Mr. A 100 Main Street, Someplace, NY Sales Manager Mr. B 101 Main Street, Someplace, NY Sales Rep Marketing: Ms. X 102 Main Street, Someplace, NY Marketing Manager - 行番号 2 を指定し、rowType プロパティーが groupHeader、groupName 要素が「Division」である場合は、groupName が「Division」のものについて、2 番目の groupHeader 行を作成する際に呼び出しが実行されます。
この場合も 2 行目を太字体にする処理を行うとすると、出力は以下のようになります。
Division A contains 2 departments: Sales Marketing Division B contains 3 departments: Sales Marketing Operations
- 行番号 3 を指定し、rowType プロパティー値が detail である場合、EGL ランタイムは、3 番目の detail 行が作成されるたびにイベント・ハンドラーを呼び出します。
それぞれの detail 行自体 は row 型であり、1 つのレポートに複数回作成することができます。
例えば、データベース照会によって、それぞれ従業員の名前、住所、および肩書きが含まれているデータベース行のセットを検索する場合に、名前、住所、肩書きのそれぞれに対して 1 行ずつレポートの detail 行を定義する場合などです。
イベント・ハンドラーで 3 番目の detail 行を太字体にする処理を行った場合、出力は以下のようになります。
- RowInstance 型の要素を受け入れるイベント・ハンドラーについては、以下の規則が適用されます。
- 上記の例のとおり、rowNumber を指定した場合、EGL ランタイムは指定した行を作成する際にイベント・ハンドラーを呼び出します。
- rowNumber を指定しなかった場合は、指定した型の行を作成するたびに、あるいは RowType 値が groupHeader または groupFooter である場合には、指定したグループの指定した型 (groupHeader または groupFooter) の行を作成するたびに、呼び出しが実行されます。
- CellInstance 型の要素を受け入れるイベント・ハンドラーについては、以下の規則が適用されます。
- columnNumber と rowNumber の両方を指定した場合、EGL ランタイムは指定した行の指定したセルを作成する際にイベント・ハンドラーを呼び出します。
- rowNumber のみ指定して、columnNumber は指定しなかった場合、指定した行のセルを作成するたびに呼び出しが実行されます。
- columnNumber のみ指定して、rowNumber は指定しなかった場合、指定した列のセルを作成するたびに呼び出しが実行されます。 例えば、rowType プロパティー値が detail のときに列番号 2 を指定した場合は、detail 行の 2 番目の列を作成するたびに呼び出しが実行されます。 同様に、列番号 2 を指定し、rowType プロパティーが groupHeader、groupName 要素が「Division」である場合は、groupName が「Division」の各 groupHeader 行の 2 番目の列を作成するたびに呼び出しが実行されます。
- columnNumber も rowNumber も指定しなかった場合は、指定した型の行のセルを作成するたびに、あるいは RowType 値が groupHeader または groupFooter である場合には、指定したグループの指定した行の型 (groupHeader または groupFooter) のセルを作成するたびに、呼び出しが実行されます。
onCreate のイベント・ハンドラーにおける順序の影響
function myEventHandler01( r RowInstance, theContext ReportContext )
{eventType = onCreate, elementName = "myReportTable", rowType = detail}
r.getStyle().color = "red";
end
function myEventHandler02( r RowInstance, theContext ReportContext )
{eventType = onCreate, elementName = "myReportTable", rowType = detail, rowNumber = 2}
r.getStyle().color = "green";
end
- 行 1 を作成する際には myEventHandler01 が呼び出されます。行の色は赤です。
- 行 2 を作成する際には myEventHandler02 が呼び出されます。行の色は緑です。
- 行 3 を作成する際には myEventHandler01 が呼び出されます。行の色は赤です。
行 2 を作成する際にはどちらの関数も適用可能ですが、myEventHandler02 が優先されるため、その行に対して myEventHandler01 は呼び出されません。
function myEventHandler02( r RowInstance, theContext ReportContext )
{eventType = onCreate, elementName = "myReportTable", rowType = detail, rowNumber = 2}
r.getStyle().color = "green";
end
function myEventHandler01( r RowInstance, theContext ReportContext )
{eventType = onCreate, elementName = "myReportTable", rowType = detail}
r.getStyle().color = "red";
end
各行を作成する際に myEventHandler01 が優先され、myEventHandler02 は呼び出されません。 すべての行が赤になります。