Registering event callbacks

The three Java interfaces for retrieving event callbacks from within a report are ReportHyperlinkListener, ReportActionListener, and ReportMouseListener. The ReportHyperlinkListener and ReportActionListener require special properties defined in your report definition, while the ReportMouseListener is a lower level event that is always called within the report PreviewDialog.

All the codes used in this article can be accessed from here.

ReportHyperlinkListener

The org.pentaho.reporting.engine.classic.core.modules.gui.base.event.ReportHyperlinkListener interface defines the following API callback method:

void hyperlinkActivated(ReportHyperlinkEvent event);

This method is called whenever someone clicks on an element within a report that has defined the link url style attribute. The ReportHyperlinkEvent provides additional metadata about the click, including the source node in the report, the hyperlink target definition, as well as the window and title hyperlink definition:

// The PreviewPane object
public Object getSource();
// The reporting node object
public RenderNode getSourceNode();
// The defined style attribute url
public String getTarget();
// The defined style attribute window
public String getWindow();
// The defined style attribute title
public String getTitle();

ReportHyperlinkListener implementations are registered by calling PreviewPane.addReportHyperlinkListener(listener). The PreviewPane object is accessible after defining a PreviewDialog by calling PreviewDialog.getPreviewPane().

One use case for implementing ReportHyperlinkListener is to allow report linking from one high level report to more detailed reports within a Java application.

Hyperlinks may appear differently when rendering in HTML and Swing. Make sure to preview your report to verify that it renders correctly.

ReportActionListener

In addition to receiving ReportHyperlinkListener events, the Swing PreviewDialog may also receive special events triggered only in the Swing environment. This is done by specifying the swing action attribute on an element. The swing action attribute type is a string. When an element within a report defines the action attribute, and a user clicks on that element, an event is fired and all registered ReportActionListener instances receive an event notification with the specified swing action attribute value.

The org.pentaho.reporting.engine.classic.core.modules.gui.base.event.ReportActionListener interface defines the following API callback method:

public void reportActionPerformed(final ReportActionEvent event);

The ReportActionEvent object returned in the callback provides the following information:

// The PreviewPane object
public Object getSource();
// The reporting node object
public RenderNode getNode();
// The action parameter specified in the report.
public Object getActionParameter();

To register a ReportActionListener, you must call PreviewDrawablePanel.addReportActionListener(listener). The PreviewDrawablePanel is accessible using the PreviewPane.getReportPreviewArea() API call.

ReportMouseListener

The org.pentaho.reporting.engine.classic.core.modules.gui.base.event.ReportMouseListener interface provides the following callbacks:

public void reportMouseClicked(ReportMouseEvent event);
public void reportMousePressed(ReportMouseEvent event);
public void reportMouseReleased(ReportMouseEvent event);

These are triggered when a user has clicked, pressed, or released their mouse within a report. Each listener registered is called for every element found at the specific x, y location within the report. If there are two or more elements overlapping, multiple event calls will be made, one for each of the report elements. The ReportMouseEvent provides the following information when a callback occurs:

// The PreviewPane object
public Object getSource();
// The reporting node object
public RenderNode getSourceNode();
// The original java.awt.event.MouseEvent
public MouseEvent getSourceEvent();

To register a ReportMouseListener, you must call PreviewDrawablePanel.addReportMouseListener(listener). The PreviewDrawablePanel is accessible using the PreviewPane.getReportPreviewArea() API call.

By combining these callbacks with additional API calls using the PageDrawable API, you can resolve the elements at any particular x, y location within a report. The PageDrawable API defines the following methods:

// Retrieves ReportNodes based on x and y location.
// A namespace and name filter may be applied to only
// retrieve nodes that define a certain attribute.
public RenderNode[] getNodesAt (final double x,
final double y, final String namespace, final String name);
// Retrieves nodes within a window, starting at an x,y
// location and stretching out to the defined pixel width
// and height. A namespace and name filter may be applied
// to only retrieve nodes that define a certain attribute.
public RenderNode[] getNodesAt (final double x,
final double y, final double width, final double height,
final String namespace, final String name);

The PageDrawable object is accessible using the PreviewDrawablePanel.getPageDrawable() API call.