BIRT レポート・レイアウト・イベント・ハンドラー

各レポート・レイアウト・イベント・ハンドラーは、レポートに表示される BIRT レポート要素へのアクセスを提供します。 このような要素をレポート・レイアウト要素 と呼んでおり、 データ・ソースまたはデータ・セットを表す要素と区別しています。

レポート・レイアウト・イベント・ハンドラーの主な特性は以下のとおりです。
remark_label というラベル要素を受け入れて、account_balance という結合式を持つ 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 番目の列は、eventTypeelementName 以外のプロパティーを指定できるかどうかを示しています。

EGL 外部型 用途 eventType と elementName 以外のプロパティー (後述) Java インターフェース
CellInstance レポートのグリッドまたはテーブル内のセルにアクセスする。 グリッドに対して CellInstance を使用する場合に使用可能なプロパティーは、columnNumberrowNumber です (いずれもオプション)。テーブルに対して CellInstance を使用する場合に使用可能なプロパティーは rowType (必須)、columnNumberrowNumber (いずれもオプション)、および 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 列挙型:
  • detail
  • header
  • footer
  • groupHeader
  • groupFooter
行の型を指定します。テーブルのセルまたは行に必須です。 グリッドのセルまたは行に対して指定された場合、このプロパティーは無視されます。
行要素またはセル要素の場合にのみ有効になる columnNumber および rowNumber プロパティーには、以下のような追加の詳細事項があります。
  • 列および行の番号は、それぞれ 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		
  • 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 のイベント・ハンドラーにおける順序の影響

eventType プロパティーの値が 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
myReportTable テーブルに 3 つの detail 行がある場合、実行時の効果は以下のようになります。
  • 行 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 は呼び出されません。 すべての行が赤になります。


フィードバック