BIRT 보고서 레이아웃 이벤트 핸들러

각 보고서 레이아웃 이벤트 핸들러는 보고서에 표시되는 BIRT 보고서 요소에 대한 액세스를 제공합니다. 이러한 종류의 요소를 보고서 레이아웃 요소라고 하며, 데이터 소스 또는 데이터 세트를 나타내는 요소와 구별합니다.

보고서 레이아웃 이벤트 핸들러의 구별되는 특성은 다음과 같습니다.
  • eventType 특성은 onCreate(보고서 레이아웃 요소가 작성될 때 핸들러가 호출되기 때문) 또는 onPageBreak(페이지 구분이 발생하고 이후에 이전 페이지에서 보고서 레이아웃 요소가 사용될 때 핸들러가 호출되기 때문)입니다.
  • 첫 번째 매개변수의 값은 특정한 유형의 보고서 레이아웃 요소를 기반으로 합니다. 예를 들어 첫 번째 매개변수가 LabelInstance 유형인 경우 이벤트 핸들러에 전달된 보고서 레이아웃 요소는 HTML 형식이 결여된 보고서 텍스트인 레이블에 대한 특정 세부사항을 포함합니다. 또한 첫 번째 매개변수의 유형은 핸들러에서 유효한 특성(필수 eventTypeelementName 이외)을 판별하는 데 도움을 줍니다.
  • onPageBreak를 참조하는 이벤트 핸들러와 관련하여 다음 사항을 참고하십시오.
    • 일부 페이지에 보고서 테이블 또는 눈금이 표시되는 경우 각 페이지 구분 시 해당 테이블 또는 눈금과 관련된 이벤트 핸들러가 호출됩니다.
    • 보고서 레이아웃 요소(예: 레이블)가 테이블 또는 눈금에 있는 경우 해당 보고서 요소가 페이지당 여러 번 반복될 수 있어도 요소와 관련된 이벤트 핸들러는 페이지당 한 번만 호출됩니다.
    • 이벤트 핸들러의 호출 순서는 보고서 레이아웃 요소가 표시되는 순서입니다.
  • 핸들러는 항상 ReportContext 유형의 매개변수를 포함하며, 이를 통해 이벤트 핸들러가 호출될 때 보고서 매개변수 값을 얻거나 설정할 수 있습니다. 보고서 매개변수는 특정한 값으로 설정할 수 있습니다. 예를 들어 보고서에 런타임 값을 표시하는 표현식에 사용할 수 있습니다.
레이블 요소 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)의 컨텐츠는 업데이트할 수 없지만 이전 예에서 표시된 대로 레이블은 업데이트할 수 있습니다. 또한 일반적으로 보고서 레이아웃 이벤트 핸들러는 하나 이상의 보고서 레이아웃 요소의 스타일을 설정할 수 있습니다.

각 이벤트 핸들러 매개변수(예: theLabel)는 Java™ 인터페이스를 표시하는 EGL 외부 유형을 기반으로 합니다. 다음 표는 관련된 Java 인터페이스의 완전한 이름과 함께 보고서 레이아웃 이벤트 핸들러에 있는 각 매개변수의 유형과 용도를 설명합니다. 테이블의 세 번째 열은 eventTypeelementName 이외의 특성을 지정할 수 있는지 여부를 나타냅니다.

EGL 외부 유형 용도 eventType 및 elementName 이외의 특성(나중에 설명) Java 인터페이스
CellInstance 보고서 눈금 또는 테이블의 셀에 액세스합니다. CellInstance가 눈금에 사용되는 경우 사용 가능한 특성은 columnNumberrowNumber(둘 다 선택적)입니다. CellInstance가 테이블에 사용되는 경우 사용 가능한 특성은 rowType(필수), columnNumberrowNumber(둘 다 선택적), groupName(rowType 값이 groupHeader 또는 groupFooter인 경우 필수)입니다. ICellInstance
DataInstance 데이터 소스의 데이터인지 또는 계산으로부터의 데이터인지에 상관 없이 데이터가 포함된 필드에 액세스합니다.   IDataItemInstance
DynamicTextInstance CLOB(character large object) 데이터(예: 메모의 컨텐츠)가 포함된 필드를 참조합니다.   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 프로그래머 참조서 > 참조서 > API 참조서 > BIRT 보고서 스크립팅 API 참조서에 있는 제품 도움말 시스템에 있습니다. 두 개의 각 Java 인터페이스는 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 디자이너는 사용자가 셀 또는 행 이름을 지정할 수 없도록 하기 때문입니다.).

eventType EventTypeKind 열거: beforeOpen, openEvent 등 "EGL BIRT 핸들러"에 설명되어 있습니다.
groupName STRING rowType의 값이 GroupHeader 또는 GroupFooter인 경우(특성이 필수인 경우) 그룹을 식별합니다.
rowNumber INT 테이블(또는 눈금) 셀 또는 행을 처리하는 경우 열을 식별합니다. 이 특성은 선택적입니다.
rowType RowTypeKind 열거:
  • 세부사항
  • 헤더
  • 푸터
  • groupHeader
  • groupFooter
행 유형을 지정하며, 테이블 셀 또는 행에 필요합니다. 눈금 셀 또는 행에 지정된 경우 이 특성은 무시됩니다.
다음은 행 요소 또는 셀 요소에만 의미 있는 columnNumberrowNumber 특성에 대한 추가 세부사항입니다.
  • 열과 행은 각각 0이 아닌 1부터 숫자가 지정됩니다.
  • 눈금 행의 경우 rowNumber 특성은 눈금 내의 위치를 참조합니다. 테이블 행의 경우 rowNumber 특성은 주어진 행 유형 내 또는 특정 그룹 이름이 있는 주어진 행 유형 내의 위치를 참조합니다. (행이 groupHeader 또는 groupFooter 유형인 경우에만 그룹 이름을 사용할 수 있습니다.) 다음과 같은 예가 있습니다.
    • 행 번호 3을 지정하고 rowType 특성 값이 세부사항이면, 세 번째 세부사항 행이 작성될 때마다 EGL 런타임이 이벤트 핸들러를 호출합니다. 각 세부사항 행은 행 유형 자체이며 주어진 보고서에서 여러 번 발생할 수 있음을 참고하십시오. 예를 들어, 데이터베이스 조회에서 직원 이름, 주소 및 직위가 각각 포함된 데이터베이스 행 세트를 검색하는 경우 이름, 주소, 직위에 대해 각각 하나의 보고서 세부사항 행을 정의할 수 있습니다. 이벤트 핸들러는 세 번째 세부사항 행을 굵게 표시할 수 있으며, 다음과 같이 출력됩니다.
      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"일 때마다 두 번째 groupHeader 행 작성 중에 호출이 발생합니다. 이 경우에도 두 번째 행을 굵게 표시할 수 있으며, 다음과 같이 출력됩니다. causing the following output:
      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 특성 값이 세부사항인 경우 열 번호 2를 지정하면 세부사항 행의 두 번째 열이 작성될 때 호출이 발생합니다. 이와 유사하게 열 번호 2, rowType 특성 groupHeader와 groupName 요소 "Division"을 지정하는 경우 groupName이 "Division"인 각 groupHeader 행의 두 번째 열을 작성하는 중에 호출이 발생합니다.
    • 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개의 세부사항 행이 있는 경우 런타임 시 다음과 같이 적용됩니다.
  • myEventHandler01은 행 1을 작성하는 중에 호출되며, 빨간색으로 작성됩니다.
  • myEventHandler02는 행 2을 작성하는 중에 호출되며, 초록색으로 작성됩니다.
  • myEventHandler01은 행 3을 작성하는 중에 호출되며, 빨간색으로 작성됩니다.

행 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는 호출되지 않습니다. 모든 행이 빨간색으로 작성됩니다.