Eclipse BIRT Report Object Model (ROM)

Label Element

# Element Overview

Displays a static piece of text. The text can be externalized.

### Details

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

### Property Summary

action
  Optional hyperlink defined for the label.
helpText
  Optional tool-tip text that appears when the user hovers the cursor over the item.
helpTextID
text
  The text to display in the label. The text can be externalized.
textID

### 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

ACLExpression, allowExport, bookmark, bookmarkDisplayName, boundDataColumns, cascadeACL, comments, cube, customXml, dataBindingRef, dataSet, displayName, displayNameID, eventHandlerClass, extends, height, multiViews, name, newHandlerOnEachEvent, paramBindings, propertyMasks, pushDown, refTemplateParameter, style, theme, toc, userProperties, viewAction, visibility, width, x, y, zIndex

### Style Properties

backgroundAttachment, backgroundColor, backgroundImage, backgroundPositionX, backgroundPositionY, backgroundRepeat, bidiTextDirection, borderBottomColor, borderBottomStyle, borderBottomWidth, borderLeftColor, borderLeftStyle, borderLeftWidth, borderRightColor, borderRightStyle, borderRightWidth, borderTopColor, borderTopStyle, borderTopWidth, canShrink, color, display, fontFamily, fontSize, fontStyle, fontVariant, fontWeight, highlightRules, letterSpacing, lineHeight, marginBottom, marginLeft, marginRight, marginTop, masterPage, orphans, overflow, paddingBottom, paddingLeft, paddingRight, paddingTop, pageBreakAfter, pageBreakBefore, pageBreakInside, showIfBlank, textAlign, textLineThrough, textOverline, textTransform, textUnderline, verticalAlign, whiteSpace, widows, wordSpacing

### Description

A label is just that: a static piece of text displayed in the report. In the simplest case, the label directly contains the text. Label items are for use with grids, free-form containers, matrices, tables and other items that need a short, discrete block of text.

The text in the label does not normally contain multiple lines. However, if the text provided is too long to fit into the available width, BIRT will automatically break the text into multiple lines. However, one would normally want to use the Text element if the intent is to display multiple lines, especially if control over the indentation, line spacing and formatting is needed.

The Label element is a kind of Report Item and inherits the `dataSet` property. However, labels display static text, so no data set should be associated with a label.

### See Also

Text Item element

Data Item element

# Property Detail

## action Property

Optional hyperlink defined for the label.

### Details

Type: | List of Action Structures
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

Optional hyperlink defined for the label. Like the label itself, the hyperlink is static. Use the Data Item to create a hyperlink that varies depending on the value of data rows.

### See Also

Action structure

## helpText Property

Optional tool-tip text that appears when the user hovers the cursor over the item.

### 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

Reports often display large amounts of data on a single page. Labels are often short: acronyms, single words and so on. While this works well once the user is familiar with the labels, it can make the report confusing to the first-time user. Help-text helps bridge the gap. It allows the user to us a label such as "ROI" in the report. If the user needs more information, he can hover the cursor over the label and help text will appear that says something like, "Return on Investment: defined as the ratio of profit to funds invested."

The help text is optional. If no text is present, then no tool-tip text will appear. The help text can be externalized.

## 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

## text Property

The text to display in the label. The text can be externalized.

### Details

Type: | literalString
Since: | 1.0
Required: | No
Display Name: | Content
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Description

The text to display in the label. The text can be externalized. The text cannot contain internal formatting.

## textID Property

### Details

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

# 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.