各レポート・レイアウト・イベント・ハンドラーは、レポートに表示される BIRT レポート要素へのアクセスを提供します。 このような要素をレポート・レイアウト要素 と呼んでおり、 データ・ソースまたはデータ・セットを表す要素と区別しています。
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 列挙型:
|
行の型を指定します。テーブルのセルまたは行に必須です。 グリッドのセルまたは行に対して指定された場合、このプロパティーは無視されます。 |
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
Division A
contains 2 departments:
Sales
Marketing
Division B
contains 3 departments:
Sales
Marketing
Operations
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
行 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 は呼び出されません。 すべての行が赤になります。