sos.reports
Interface View

All Known Implementing Classes:

AbstractView

public interface View

An object that can size and display a portion of a report. Views are used behind the scenes by JReportPane and its corresponding ReportPaneUI.

Sizing Views

ReportPaneUIs should ensure that views are properly sized when they are rendered. Generally, they will take the following steps to size a root view:

1. Invoke getPreferredLength and/or getMinimumLength along the first axis
2. Invoke setLength along the first axis
3. Invoke getPreferredLength and/or getMinimumLength along the second axis
4. Invoke setLength along the second axis
5. Invoke setTopLeftCorner to position the view

Once the root view is sized, paint can be invoked on it.

Breaking Views into Pages

Breaking a view into m columns and n rows requires m + n invocations of breakView. First fully break along the minor axis (usually the width) and then break along the major axis (usually the height). Follow the following pattern to break a view along a given axis:

1. Invoke getPreferredLength and/or getMinimumLength
2. Invoke setLength
3. Invoke gatherBreakWeights
4. Invoke breakView at a valid break position

After a view has been broken in both directions, invoke setTopLeftCorner to position the view. The view's broken portions can be obtained with getNextBrokenView and getPreviousBrokenView.

Since:

1.0

Nested Class Summary

static class

View.ResizeRequest A way to indicate that a view's minimum and preferred lengths have possibly changed.

Field Summary

static int	X_AXIS A constant that indicates the direction along the X axis (horizontal).
static int	Y_AXIS A constant that indicates the direction along the Y axis (vertical).

Method Summary

void	breakView(int axis, int newLength, ViewFactory viewFactory) Breaks this view at the specified offset along the specified axis and returns a view of the leftover portion.
View	elementToView(Element element) Returns the view corresponding to the specified element, or null if none is found.
void	forwardReportEvent(ReportEvent event) Called by a child view to propagate changes to nested reports up the view hierarchy.
void	gatherBreakWeights(int axis, BreakWeightRecorder recorder) Determines the positions where this view can be broken.
void	gatherViewsAt(java.awt.Point point, java.util.Collection views) Adds this view and any of its children to the specified collection if they contain the specified point.
void	gatherViewsWithin(java.awt.Rectangle region, java.util.Collection views) Adds this view and any of its children to the specified collection if they contain any point in the specified region.
Element	getElement() Returns this view's underlying element.
int	getLength(int axis) Returns the length of this view along the specified axis.
int	getMinimumLength(int axis) Returns the minimum length of this view along the specified axis, given this view's current state.
View	getNextBrokenView(int axis) Returns the next broken portion along the specified axis, after breakView has been called in this direction.
int	getOffset(int axis) Returns the absolute offset of this view along the specified axis.
View	getParent() Returns this view's parent view.
int	getPreferredLength(int axis) Returns the preferred length of this view along the specified axis, given this view's current state.
View	getPreviousBrokenView(int axis) Returns the previous broken portion along the specified axis.
JReportPane	getReportPane() Returns the report pane hosting this view.
java.lang.String	getText() Returns the text rendered by this view.
java.lang.String	getToolTipText(java.awt.Point point) Returns this view's tool tip string, or null, if the tool tip should be gotten by another means.
void	paint(java.awt.Graphics g) Paints this view on the specified rendering surface.
void	reportChanged(ReportEvent event, java.awt.Rectangle dirtyRegion, ViewFactory viewFactory, View.ResizeRequest resizeRequest) Triggers a response to a report change.
void	setLength(int axis, int length) Set the length of this view along the specified axis.
void	setParent(View parent) Sets this view's parent view.
void	setTopLeftCorner(int x, int y) Sets this view's x and y offsets.

Field Detail

X_AXIS

public static final int X_AXIS

A constant that indicates the direction along the X axis (horizontal).

See Also:

Y_AXIS, Constant Field Values

Y_AXIS

public static final int Y_AXIS

A constant that indicates the direction along the Y axis (vertical).

See Also:

X_AXIS, Constant Field Values

Method Detail

breakView

public void breakView(int axis,
                      int newLength,
                      ViewFactory viewFactory)
               throws java.lang.IllegalArgumentException,
                      java.lang.NullPointerException

Breaks this view at the specified offset along the specified axis and returns a view of the leftover portion. This view's length should be set along the specified axis before the call is made; otherwise this view may not know how to lay out its children. This view resets its length to newLength, where newLength is relative to this view. To avoid an InvalidBreakPosition being thrown, the client should invoke gatherBreakWeights and select a break position that is not BreakWeightRecorder.BAD_BREAK_WEIGHT.

Parameters:

axis - axis (either X_AXIS or Y_AXIS) along which to break this view

newLength - offset at which to break this view

Throws:

java.lang.IllegalArgumentException - if axis is not X_AXIS or Y_AXIS

java.lang.IllegalStateException - if this view has already been broken along this axis or if this view has a previous broken view along the opposite axis

InvalidBreakPosition - if this view cannot be broken at newLength

java.lang.NullPointerException - if viewFactory is null

See Also:

gatherBreakWeights(int, sos.reports.BreakWeightRecorder), getNextBrokenView(int)

gatherBreakWeights

public void gatherBreakWeights(int axis,
                               BreakWeightRecorder recorder)

Determines the positions where this view can be broken. This view sets all bits (within this view's range) in the recorder to an appropriate weight. No bit should be BreakWeightRecorder.UNDEFINED_BREAK_WEIGHT when this method returns. To set bits, an implementation may, for example, invoke

   recorder.fill( BreakWeightRecorder.BAD_BREAK_WEIGHT );
 

to signal that it cannot be broken, or

   recorder.setWeight( 25, BreakWeightRecorder.FORCED_BREAK_WEIGHT );
 

to signal that it must be broken at position 25. All positions are relative to this view. If this view contains child views, it should clip the recorder's range using BreakWeightRecorder.createView(int, int) and invoke gatherBreakWeights on its children.

Parameters:

axis - axis (either X_AXIS or Y_AXIS) along which to break this view

recorder - an object that records

Throws:

java.lang.IllegalArgumentException - if axis is not X_AXIS or Y_AXIS

java.lang.NullPointerException - if recorder is null

gatherViewsAt

public void gatherViewsAt(java.awt.Point point,
                          java.util.Collection views)

Adds this view and any of its children to the specified collection if they contain the specified point. point is an absolute position.

The elements should be added to views in the order that they should be resolved. This order is the opposite order in which they are rendered in BasicReportPaneUI.

Parameters:

point - (x,y) position to test for inclusion

views - collection to which this view adds descendant views that include point

Throws:

java.lang.NullPointerException - if point or views is null

See Also:

gatherViewsWithin(java.awt.Rectangle, java.util.Collection)

gatherViewsWithin

public void gatherViewsWithin(java.awt.Rectangle region,
                              java.util.Collection views)

Adds this view and any of its children to the specified collection if they contain any point in the specified region. region is given in absolute positions.

The elements should be added to views in the order that they should be resolved. This order is the opposite order in which they are rendered in BasicReportPaneUI.

Parameters:

region - rectangle to test for intersection

views - collection to which this view adds descendant views that intersect region

Throws:

java.lang.NullPointerException - if region or views is null

getLength

public int getLength(int axis)

Returns the length of this view along the specified axis. If the length has yet to be set along this axis, this method may return any integer.

Parameters:

axis - axis (either X_AXIS or Y_AXIS) along which the length is requested

Returns:

the length of this view along axis

Throws:

java.lang.IllegalArgumentException - if axis is not X_AXIS or Y_AXIS

See Also:

setLength(int, int)

getMinimumLength

public int getMinimumLength(int axis)

Returns the minimum length of this view along the specified axis, given this view's current state.

Parameters:

axis - axis (either X_AXIS or Y_AXIS) along which the length is requested

Returns:

the minimum length of this view along axis

Throws:

java.lang.IllegalArgumentException - if axis is not X_AXIS or Y_AXIS

getNextBrokenView

public View getNextBrokenView(int axis)

Returns the next broken portion along the specified axis, after breakView has been called in this direction.

Parameters:

axis - axis (either X_AXIS or Y_AXIS) along which the next broken view is requested

Returns:

the next broken view along axis

See Also:

breakView(int, int, sos.reports.ViewFactory), getPreviousBrokenView(int)

getPreviousBrokenView

public View getPreviousBrokenView(int axis)

Returns the previous broken portion along the specified axis.

Parameters:

axis - axis (either X_AXIS or Y_AXIS) along which the previous broken view is requested

Returns:

the previous broken view along axis

See Also:

breakView(int, int, sos.reports.ViewFactory), getNextBrokenView(int)

getOffset

public int getOffset(int axis)

Returns the absolute offset of this view along the specified axis. If the offset has yet to be set along this axis, this method may return any integer.

Parameters:

axis - axis (either X_AXIS or Y_AXIS) along which the offset is requested

Returns:

the offset of this view along axis

Throws:

java.lang.IllegalArgumentException - if axis is not X_AXIS or Y_AXIS

See Also:

setTopLeftCorner(int, int)

getPreferredLength

public int getPreferredLength(int axis)

Returns the preferred length of this view along the specified axis, given this view's current state.

Parameters:

axis - axis (either X_AXIS or Y_AXIS) along which the length is requested

Returns:

the preferred length of this view along axis

Throws:

java.lang.IllegalArgumentException - if axis is not X_AXIS or Y_AXIS

getReportPane

public JReportPane getReportPane()

Returns the report pane hosting this view.

Returns:

the report pane hosting this view

getElement

public Element getElement()

Returns this view's underlying element.

Returns:

this view's corresponding element

getText

public java.lang.String getText()

Returns the text rendered by this view.

Returns:

the text rendered by this view (may not be null)

getToolTipText

public java.lang.String getToolTipText(java.awt.Point point)

Returns this view's tool tip string, or null, if the tool tip should be gotten by another means.

Parameters:

point - point at which the tool tip string is requested

Returns:

this view's tool tip text

elementToView

public View elementToView(Element element)

Returns the view corresponding to the specified element, or null if none is found. This method is recursive in that it invokes getView on the child views if appropriate. If this view is a direct view of element, it returns itself.

Parameters:

element - report element for which the corresponding view is requested

Returns:

the view of element

Throws:

java.lang.NullPointerException - if element is null

paint

public void paint(java.awt.Graphics g)

Paints this view on the specified rendering surface.

Parameters:

g - surface on which to render this view

Throws:

java.lang.NullPointerException - if g is null

reportChanged

public void reportChanged(ReportEvent event,
                          java.awt.Rectangle dirtyRegion,
                          ViewFactory viewFactory,
                          View.ResizeRequest resizeRequest)

Triggers a response to a report change. This is initially called by the ReportPaneUI on the root view and flows downward along the view hierarchy.

Parameters:

event - the event describing how the report has changed

dirtyRegion - set by this view to indicate the region that needs to be repainted

viewFactory - a means to create new views if necessary

resizeRequest - set by this view to indicate how its preferences have change as a result of the event

Throws:

java.lang.UnsupportedOperationException - if this view has been broken and does not support report changes

forwardReportEvent

public void forwardReportEvent(ReportEvent event)

Called by a child view to propagate changes to nested reports up the view hierarchy.

Parameters:

event - nested report change

setParent

public void setParent(View parent)

Sets this view's parent view.

Parameters:

parent - view to be the parent of this view

See Also:

getParent()

getParent

public View getParent()

Returns this view's parent view.

Returns:

this view's parent

See Also:

setParent(sos.reports.View)

setLength

public void setLength(int axis,
                      int length)

Set the length of this view along the specified axis.

Parameters:

axis - axis (either X_AXIS or Y_AXIS) along which the length is requested

length - the length of this view along axis

Throws:

java.lang.IllegalArgumentException - if axis is not X_AXIS or Y_AXIS or if length < 0

See Also:

getLength(int)

setTopLeftCorner

public void setTopLeftCorner(int x,
                             int y)

Sets this view's x and y offsets.

Parameters:

x - offset along the x-axis

y - offset along the y-axis

See Also:

getOffset(int)