The layout of a report is constructed by combining basic graphical report objects into a final template. There are 7 such objects: Ellipse, Image, Line, Rectangle, Static Text, Text Field, Subreport. To form the layout these objects are placed inside report sections (Section 6.7, “Report Sections”).
All the report objects are sharing a common set of properties. These properties determine the position, size, color and printing behavior of the object.
Common Properties
Key
A unique string that identifies the object throughout the report. It is useful to obtain a reference to the object at runtime through the JasperReports API.
Location.X
X coordinate of the object relative to the parent band. The coordinate is specified in report units.
Location.Y
Y coordinate of the object relative to the parent band. The coordinate is specified in report units.
Size.Width
Width of the object specified in report units.
Size.Height
Height of the object specified in report units.
Foreground
The foreground color of the object.
Background
The background color of the object.
Mode
Determines whether the background of an object is transparent or opaque.
Stretch Type
Determines the object's stretch behavior when the report section is affected by stretch.
No Stretch - The object does not stretch.
Relative To Tallest Object - The object stretches to the height of the tallest object in the group. (Section 6.9.8, “Element Group”)
Relative To Band Height - The object stretches to the height of the report section.
Position Type
Determines the object's position when the report section is affected by stretch.
Float - The object is positioned relative to the surrounding objects.
Fix Relative To Top - The object is positioned relative to the top of the band.
Fix Relative To Bottom - The object is positioned relative to the bottom of the band.
Print In First Whole Band
Flag that determines whether the object gets printed in the first section of a new page or column that is not an overflow from a previous page or column.
Print Repeated Values
Flag that determines whether the repeating values are printed for the dynamic objects such as text fields and images.
Print When Detail Overflows
Flag that determines whether the object is be printed when the band overflows to a new page or a new column.
Print When Expression
A boolean expression that determines whether the object is printed or not.
Print When Group Changes
The object is printed when the specified group changes.
Remove Line When Blank
Flag that determines whether the section should be removed or not when the object is not printed. If the flag is true and the object is not printed, and there are no other objects occupying the same horizontal space, then the report section is removed.
The following properties are shared only by Ellipse, Image, Line and Rectangle objects.
Pen
Determines the line type used to draw the object.
None - No line.
1 Point - Normal width line.
2 Point - Medium width line.
4 Point - Thick line.
Dotted - Dotted line.
Thin - Thin line.
Fill
Determines the fill pattern used to fill the object.
Solid - Solid fill.
Ellipse object represents an ellipse graphical element. Ellipse object does not define other properties in addition to common properties.
Image object represents an image graphical element. Image data can be obtained from various locations such as disk file, web URL or a database field.
Image Properties
Expression
Expression that determines the source of image data. The type of image source is determined by the expression's value class:
java.lang.String - Image location. First, the report engine tries to determine whether the String represents an URL. If not, it tries to interpret the String as a disk file path. Finally, if the String does not represent a file path, the image is searched in the CLASSPATH using the String as a resource path.
java.io.File - Image data is loaded from the java.io.File object that represents a file on disk.
java.net.URL - Image data is loaded from the location represented by the java.net.URL object. URL represents a pointer to an image on the World Wide Web.
java.io.InputStream - Image data is loaded from a java.io.InputStream object. The value class is frequently used with JDBC data sources to extract the image data from database.
java.awt.Image - Image is represented by a java.awt.Image object.
net.sf.jasperreports.engine.JRRenderable - Image is drawn directly on the graphic context by a serializable instance of this interface.
Evaluation Time
Determines the moment of the Image's expression evaluation.
Now - The expression is evaluated at the section fill time.
Report - The expression is evaluated when the end of the report is reached.
Page - The expression is evaluated when the end of the current page is reached
Column - The expression is evaluated when the end of the current column is reached.
Group - The expression is evaluated when the group specified by the Evaluation Group property changes.
Evaluation Group
Specifies the group required by the Evaluation Time property when its value is Group.
Horizontal Alignment
Specifies the horizontal alignment of the Image object.
Left - Left.
Center - Center.
Right - Right.
Vertical Alignment
Specifies the vertical alignment of the Image object.
Top - Top.
Middle - Middle.
Bottom - Bottom.
Scale
Specifies the image scale type.
Clip - The image is clipped if it does not fit the bounds of the Image object.
Fill Frame - The image is scaled to fit the bounds of the Image object. The scaled image does not preserve the aspect ratio.
Retain Shape - The image is scaled to fit the bounds of the Image object. The scaled image preserves the aspect ratio.
Using Cache
Flag indicating whether the images that are loaded from the same location should be cached.
Anchor Name Expression
Expression that determines the name of the local anchor that will mark the Image object. This anchor name can be later referred to in document hyperlinks.
Hyperlink Type
Specifies the type of the hyperlink associated with the Image object.
None - No hyperlink.
Reference - The hyperlink points to an external resource specified by the Hyperlink Reference Expression property. This is usually a URL.
Local Anchor - The hyperlink points to a local anchor (same document) specified by the Hyperlink Anchor Expression property.
Local Page - The hyperlink points to a local page (same document) specified by the Hyperlink Page Expression property. The page number is 1 based.
Remote Anchor - The hyperlink points to an anchor (external document) specified by the Hyperlink Anchor Expression property. The external document is specified by the Hyperlink Reference Expression property.
Remote Page - The hyperlink points to a page (external document) specified by the Hyperlink Page Expression property. The external document is specified by the Hyperlink Reference Expression property. The page number is 1 based.
Hyperlink Anchor Expression
Expression that determines the document anchor to which points the hyperlink associated with the Image object.
Hyperlink Page Expression
Expression that determines the document page to which points the hyperlink associated with the Image object.
Hyperlink Reference Expression
Expression that determines the external document or resource to which points the hyperlink associated with the Image object.
Hyperlink Target
Specifies the target of the hyperlink associated with the Image object.
Self - The hyperlink destination document is opened in the same window.
Blank - The hyperlink destination document is opened in a new window.
Box
Specifies the box properties such as border type, border color and padding. Each property can be set individually for each box side or globaly for all sides.
Line object represents a line graphical element. The endpoints of the line are determined by its bounding box. The line is drawn along one of the bounding box diagonals.
Line Properties
Direction
Determines the diagonal of the bounding box along which the line is drawn
Top Down - The line is drawn from the top-left corner to the bottom-right corner.
Bottom Up - The line is drawn from the bottom-left corner to the top-right corner.
Rectangle object represents a rectangle graphical element.
Rectangle Properties
Radius
Specifies the radius of the rectangle's corner arc.
There are two special report objects for printing text values. These two objects are Static Text and Text Field. Static Text is used to for static text information. Text Field is used for dynamic text.
Static Text and Text Field objects share a set of common properties.
Common Properties
Font
Specifies the font for the text object. The font property is defined through a number of sub-properties. These sub-properties are the same as used by the report font definition (Section 6.3, “Fonts”). A special Report Font sub-property allows to specify a report font that is used as the base font for the font definition. If not specified, then the default report font is used for this scope. By specifying other sub-properties, the font definition basically overrides the properties of the corresponding base font.
Text Alignment
Specifies the alignment for the text object.
Left - Left.
Center - Center.
Right - Right.
Justified - Justified.
Vertical Alignment
Specifies the vertical alignment of the text object.
Top - Top.
Middle - Middle.
Bottom - Bottom.
Line Spacing
Specifies the line spacing type.
Single - Single line spacing.
1 and 1/2 - One and a half line spacing.
Double - Double line spacing.
Rotation
Specifies the rotation type.
None - No rotation.
Left - Text is rotated 180 degrees counter wise.
Right - Text is rotated 180 degrees clock wise.
Styled Text
Flag that indicates whether the text object contains styled text or regular text. Styled text can contain style information that is specified using <style> tag. <style> tag supports the following attributes : fontName, size, isBold, isItalic, isUnderline, isStrikeThrough, pdfFontName, pdfEncoding, isPdfEmbedded, forecolor, backcolor.
Box
Specifies the box properties such as border type, border color and padding. Each property can be set individually for each box side or globaly for all sides.
Static Text object represents a text element whose value is known at the report design time.
Static Text Properties
Text
Specifies the object's text.
Text Field object represents a text element that can present dynamic values that are calculated at the time of report execution. The most frequent use of this object is for printing text values obtained from a data source.
Text Field Properties
Expression
Expression that determines the Text Field's value. The class of the value can be one of the following:
java.lang.Boolean
java.lang.Byte
java.util.Date
java.sql.Timestamp
java.sql.Time
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.Short
java.math.BigDecimal
java.lang.Number
java.lang.String
Evaluation Time
Determines the moment of the Text Field's expression evaluation.
Now - The expression is evaluated at the section fill time.
Report - The expression is evaluated when the end of the report is reached.
Page - The expression is evaluated when the end of the current page is reached
Column - The expression is evaluated when the end of the current column is reached.
Group - The expression is evaluated when the group specified by the Evaluation Group property changes.
Evaluation Group
Specifies the group required by the Evaluation Time property when its value is Group.
Pattern
Specifies the pattern that is used to format the value of the Text Field's expression. For date type values the pattern is defined by the java.text.SimpleDataFormat class. For numerical type values the pattern is defined by the java.text.DecimalFormat.
Blank When Null
Flag that indicates whether the blank character instead of null should be displayed when the Text Field's expression evaluates to a null value.
Stretch With Overflow
Flag that indicates whether the height of the object should be increased when the text does not fit the specified object height.
Anchor Name Expression
Expression that determines the name of the local anchor that will mark the Text Field object. This anchor name can be later referred to in document hyperlinks.
Hyperlink Type
Specifies the type of the hyperlink associated with the Text Field object.
None - No hyperlink.
Reference - The hyperlink points to an external resource specified by the Hyperlink Reference Expression property. This is usually a URL.
Local Anchor - The hyperlink points to a local anchor (same document) specified by the Hyperlink Anchor Expression property.
Local Page - The hyperlink points to a local page (same document) specified by the Hyperlink Page Expression property. The page number is 1 based.
Remote Anchor - The hyperlink points to an anchor (external document) specified by the Hyperlink Anchor Expression property. The external document is specified by the Hyperlink Reference Expression property.
Remote Page - The hyperlink points to a page (external document) specified by the Hyperlink Page Expression property. The external document is specified by the Hyperlink Reference Expression property. The page number is 1 based.
Hyperlink Anchor Expression
Expression that determines the document anchor to which points the hyperlink associated with the Text Field object.
Hyperlink Page Expression
Expression that determines the document page to which points the hyperlink associated with the Text Field object.
Hyperlink Reference Expression
Expression that determines the external document or resource to which points the hyperlink associated with the Text Field object.
Hyperlink Target
Specifies the target of the hyperlink associated with the Text Field object.
Self - The hyperlink destination document is opened in the same window.
Blank - The hyperlink destination document is opened in a new window.
Subreport object is used for inserting a report within report. This report nesting mechanism allows the creation of complex reports and also adds the possibility of report fragments reuse. A frequent use of sub-reports is for creating master-detail type of reports.
Nested reports usually require a number of parameters. These parameters can be passed in using the Parameters Map Expression property. The parameters can also be specified individually by right-clicking on the Subreport object in the Outline View and selecting the Add Parameter action.
Subreport Properties
Expression
Expression that determines the source of the sub-report. Type of the sub-report source is determined by the expression's value class:
java.lang.String - Subreport location. First, the report engine tries to determine whether the String represents an URL. If not, it tries to interpret the String as a disk file path. Finally, if the String does not represent a file path, the image is searched in the CLASSPATH using the String as a resource path.
java.io.File - Subreport is loaded from the java.io.File object that represent a file on disk.
java.net.URL - Subreport is loaded from the location represented by the java.net.URL object. URL represents a pointer to a resource on the World Wide Web.
java.io.InputStream - Subreport is loaded from a java.io.InputStream object.
net.sf.jasperreports.engine.JasperReport - Subreport is supplied directly by the expression as a net.sf.jasperreports.engine.JasperReport object.
Using Cache
Flag indicating whether the sub-reports that are loaded from the same location should be cached.
Connection Expression
Optional expression that supplies the JDBC connection (an instance of java.sql.Connection) for the sub-report. This property is used in conjunction with a JDBC data source. Most of the time, expression specifies the connection used by the master report. This is done by using a built-in parameter $P{REPORT_CONNECTION}.
Data Source Expression
Optional expression that supplies an instance of net.sf.jasperreports.engine.JRDataSource to the sub-report.
Parameters Map Expression
Optional expression that supplies the sub-report parameters that are passed in as an instance of java.util.Map. The most frequent use of this expression is to propagate to the sub-report the parameters that have been received by the master report. This is achieved by using a built-in parameter $P{REPORT_PARAMETERS_MAP}.
Subreport Parameter Properties
Name
Name of the parameter as declared by the nested report.
Expression
Expression that determines the value of the parameter.