Eclipse BIRT Report Object Model (ROM)

Image Element

Element Overview

Displays an image within the report.

Details

Display Name: Image
Since: 1.0
XML Element: image
Extends: ReportItem
Extendable: Yes
Abstract: No
Name Space: Report Items
Name Requirement: Optional
Allows User Properties: Yes
Has Style: Yes
Default Style: image

Property Summary

action
An optional hyperlink for this image.
altText
An optional text message to display in place of the image in a web browser.
altTextID
Resource key for the altText property.
helpText
An optional help text for the image.
helpTextID
imageName
The name of an embedded image if the Source type is Embedded.
scale
size
How to manage the relationship between image and item size.
source
The kind of image reference.
typeExpr
An expression that returns the type of the image expressed as a MIME type.
uri
The identifier for the image if the type is File or URL.
valueExpr
An expression which returns the image contents.

Method Summary

onCreate
Script executed when the element is created in the Factory.
onPageBreak
onPrepare
It is for a script startup phase. No data binding yet. The design of an element can be changed here.
onRender
Script executed when the element is prepared for rendering in the Presentation engine.

Inherited Properties

bookmark, boundDataColumns, comments, cube, customXml, dataBindingRef, dataSet, displayName, displayNameID, eventHandlerClass, extends, height, name, paramBindings, propertyMasks, refTemplateParameter, style, toc, userProperties, viewAction, visibility, width, x, y, zIndex

Inherited Property Notes

dataSet
Allows the user to fetch the image from a data set. The image is in the first row of the data set.
toc
While the image can appear in the TOC, it is generally not very useful to do so.

Style Properties

backgroundColor, borderBottomColor, borderBottomStyle, borderBottomWidth, borderLeftColor, borderLeftStyle, borderLeftWidth, borderRightColor, borderRightStyle, borderRightWidth, borderTopColor, borderTopStyle, borderTopWidth, color, display, fontFamily, fontSize, fontStyle, fontVariant, fontWeight, highlightRules, marginBottom, marginLeft, marginRight, marginTop, masterPage, paddingBottom, paddingLeft, paddingRight, paddingTop, pageBreakAfter, pageBreakBefore, pageBreakInside, showIfBlank, textAlign, textLineThrough, textOverline, textUnderline, verticalAlign

Description

Reports often display images in various formats: corporate logos, product images, icons, and so on. Popular image formats are JPEG for photographs, and GIF, PNG and SVG for computer-generated graphics such as logos.

The image item provides an image in one of a number of formats. The image can come from a number of sources. The image item can be sized to the image (in which case the height and width attributes are ignored), or the image can be sized or clipped to fit the item. Images are always scaled proportionately.

The image item is similar to the Image report element in RDL, the image control in AFC and the picture item in Crystal. Key features include:

The image element should provide a number of options for handling images that are larger or smaller than the size of the element itself:

The following table shows which properties are used for each image source type.

Property Embedded File URL Computed
Image Name X
URI X X
Value Expression X
Type Expression X
Size X X X X

Property Detail

action Property

An optional hyperlink for this image.

Details

Type: Action Structure
Since: 1.0
Required: No
Display Name: Action
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

Provides a hyperlink from this image.


altText Property

An optional text message to display in place of the image in a web browser.

Details

Type: string
Since: 1.0
Required: No
Display Name: Alternative text
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

An optional text message to display in place of the image in a web browser.

See Also

altTextID property


altTextID Property

Resource key for the altText property.

Details

Type: resourceKey
Since: 1.0
Required: No
Display Name: Alternative text key
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

Resource key that allows externalizing and localizing the value of the altText property.

See Also

altText property


helpText Property

An optional help text for the image.

Details

Type: string
Since: 1.0
Required: No
Display Name: Help text
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

An optional help text for the image. The help text can contain HTML formatting and can be externalized. The web viewer shows this as "balloon help."

See Also

helpTextID property


helpTextID Property

Details

Type: resourceKey
Since: 1.0
Required: No
Display Name: Help text key
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

imageName Property

The name of an embedded image if the Source type is Embedded.

Details

Type: structRef
Since: 1.0
Required: No
Display Name: Image name
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

The name of an embedded image if the Source type is Embedded.


scale Property

Details

Type: float
Since: 1.0
Required: No
Display Name: Scale
JavaScript Type:
Default Value: 1.0
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

size Property

How to manage the relationship between image and item size.

Details

Type: choice (imageSize)
Since: 1.0
Required: No
Display Name: Size
JavaScript Type:
Default Value: size-to-image
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
size-to-image Size to Image size-to-image
scale-to-item Scale to Item scale-to-item
clip Clip clip


source Property

The kind of image reference.

Details

Type: choice (imageRefType)
Since: 1.0
Required: Yes
Display Name: Source
JavaScript Type:
Default Value: none
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
none No image none
url URL url image is given by a URL to be evaluated at presentation time.
file FILE file The image is in a file.
expr Expression expr The image is returned by an expression. (Not in the first release.)
embed Embedded Image embed The image is embedded within the design.

Description

The image can be provided in a number of formats. The choice here determines which of the other properties that BIRT will consider when obtaining the image value.

The expr option is not available in Release 1.0. That is, the image cannot be retrieved from a database in Release 1.0.


typeExpr Property

An expression that returns the type of the image expressed as a MIME type.

Details

Type: expression
Context:
Expression Type: string
Since: 2.0
Required: No
Display Name: Type expression
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

An expression that returns the type of the image expressed as a MIME type: image/jpeg, image/png, image/gif, etc. If omitted, BIRT will attempt to infer the image type from the data in the image itself.


uri Property

The identifier for the image if the type is File or URL.

Details

Type: expression
Context:
Expression Type: string
Since: 1.0
Required: No
Display Name: URI
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

The identifier for the image if the type is File or URL. The type of image is inferred from the image file content or HTTP response.


valueExpr Property

An expression which returns the image contents.

Details

Type: expression
Context:
Expression Type: blob
Since: 2.0
Required: No
Display Name: Value expression
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

An expression which returns the image contents.

Method Detail

onCreate Method

Script executed when the element is created in the Factory.

Synopsis

None obj.onCreate( )

Details

Since: 1.0
Context: factory
Arguments: None
Return Type: None

Description

Executed when the element is created in the Factory. Called after the item is created, but before the item is saved to the report document file. See the scripting spec for additional information about this script. Applications should perform visual customization in the on-render script instead.


onPageBreak Method

Synopsis

None obj.onPageBreak( )

Details

Since: 2.1
Context: presentation
Arguments: None
Return Type: None

onPrepare Method

It is for a script startup phase. No data binding yet. The design of an element can be changed here.

Synopsis

None obj.onPrepare( )

Details

Since: 2.0
Context: startup
Arguments: None
Return Type: None

Description

It is for a script startup phase. No data binding yet. The design of an element can be changed here.


onRender Method

Script executed when the element is prepared for rendering in the Presentation engine.

Synopsis

None obj.onRender( )

Details

Since: 1.0
Context: presentation
Arguments: None
Return Type: None

Description

Executed when the element is prepared for rendering in the Presentation engine. Changes made to the element are written to the target output format, but not saved to the report document file. This is the preferred place for visual customizations.