Eclipse BIRT Report Object Model (ROM)

Cell Element

# Element Overview

Represents a cell element within a grid row or table row.

### Details

Display Name: | Cell
Since: | 1.0
XML Element: | `cell`
Extends: | None
Extendable: | No
Abstract: | No
Name Space: | None
Name Requirement: | Not Supported
Allows User Properties: | Yes
Has Style: | Yes
Default Style: | None

### Property Summary

antidiagonalColor
antidiagonalNumber
antidiagonalStyle
antidiagonalThickness
bookmark
bookmarkDisplayName
colSpan
  The number of columns that this cell spans.
column
  The column in which the cell starts.
diagonalColor
diagonalNumber
diagonalStyle
diagonalThickness
drop
  Whether the cells defined in this row should expand to fill the entire table or group.
eventHandlerClass
  The full qulified name of the event handler class.
headers
height
  Minimum cell height.
newHandlerOnEachEvent
rowSpan
  The number of rows that this cell spans.
scope
style
  Name of the style applied to this cell.
viewAction
width
  Minimum cell width.

### Method Summary

onCreate
  Script executed when the element is created in the Factory.
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.

### Slot Summary

content
  Report items that appear inside the cell.

### Style Properties

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

### Description

Each grid or table row contains some number of cells. A cell can span multiple columns. The design need not specify a cell for each column; columns without cells are presumed empty.

If the cell contains more than one item, the items appear vertically within the cell. The developer should generally use a container to better control the positioning of items when the cell contains multiple items.

The cell height and width are optional and are seldom needed. However, they are available for situations where it is required to force a cell to a particular size.

# Property Detail

## antidiagonalColor Property

### Details

Type: | color
Since: | 2.5
Required: | No
Display Name: | Antidiagonal color
JavaScript Type: |
Default Value: | black
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Hidden
Property Sheet Group: | Diagonal

### Choices

Name | Display Name | Value | Description
maroon | Maroon | maroon |
red | Red | red |
orange | Orange | orange |
yellow | Yellow | yellow |
olive | Olive | olive |
purple | Purple | purple |
fuchsia | Fuchsia | fuchsia |
white | White | white |
lime | Lime | lime |
green | Green | green |
navy | Navy | navy |
blue | Blue | blue |
aqua | Aqua | aqua |
teal | Teal | teal |
black | Black | black |
silver | Silver | silver |
gray | Gray | gray |

## antidiagonalNumber Property

### Details

Type: | integer
Since: | 2.3
Required: | No
Display Name: | Antidiagonal number
JavaScript Type: |
Default Value: | 0
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Hidden
Property Sheet Group: | Diagonal

## antidiagonalStyle Property

### Details

Type: | choice (lineStyle)
Since: | 3.2
Required: | No
Display Name: | Antidiagonal style
JavaScript Type: |
Default Value: | none
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Hidden
Property Sheet Group: | Diagonal

### Choices

Name | Display Name | Value | Description
none | No Line Style | none |
solid | Solid | solid |
dotted | Dotted | dotted |
dashed | Dashed | dashed |
double | Double | double |
groove | Groove | groove |
ridge | Ridge | ridge |
inset | Inset | inset |
outset | Outset | outset |

## antidiagonalThickness Property

### Details

Type: | dimension
Since: | 3.2
Required: | No
Display Name: | Antidiagonal thickness
JavaScript Type: |
Default Value: | medium
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Hidden
Property Sheet Group: | Diagonal

### Choices

Name | Display Name | Value | Description
thin | Thin | thin |
medium | Medium | medium |
thick | Thick | thick |

## bookmark Property

### Details

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

## bookmarkDisplayName Property

### Details

Type: | string
Since: | 2.5
Required: | No
Display Name: | Bookmark display name
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

## colSpan Property

The number of columns that this cell spans.

### Details

Type: | integer
Since: | 1.0
Required: | No
Display Name: | Column span
JavaScript Type: |
Default Value: | 1
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Read-only
Property Sheet Group: | Top

### Description

The number of columns that this cell spans. Defaults 1 one, meaning that the cell appears in only one column.

## column Property

The column in which the cell starts.

### Details

Type: | integer
Since: | 1.0
Required: | No
Display Name: | Column
JavaScript Type: |
Default Value: | One after the previous column.
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Hidden
Property Sheet Group: | Top

### Description

The column in which the cell starts. Columns are numbered from 1.

## diagonalColor Property

### Details

Type: | color
Since: | 2.5
Required: | No
Display Name: | Diagonal color
JavaScript Type: |
Default Value: | black
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Diagonal

### Choices

Name | Display Name | Value | Description
maroon | Maroon | maroon |
red | Red | red |
orange | Orange | orange |
yellow | Yellow | yellow |
olive | Olive | olive |
purple | Purple | purple |
fuchsia | Fuchsia | fuchsia |
white | White | white |
lime | Lime | lime |
green | Green | green |
navy | Navy | navy |
blue | Blue | blue |
aqua | Aqua | aqua |
teal | Teal | teal |
black | Black | black |
silver | Silver | silver |
gray | Gray | gray |

## diagonalNumber Property

### Details

Type: | integer
Since: | 2.3
Required: | No
Display Name: | Diagonal number
JavaScript Type: |
Default Value: | 0
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Diagonal

## diagonalStyle Property

### Details

Type: | choice (lineStyle)
Since: | 3.2
Required: | No
Display Name: | Diagonal style
JavaScript Type: |
Default Value: | none
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Diagonal

### Choices

Name | Display Name | Value | Description
none | No Line Style | none |
solid | Solid | solid |
dotted | Dotted | dotted |
dashed | Dashed | dashed |
double | Double | double |
groove | Groove | groove |
ridge | Ridge | ridge |
inset | Inset | inset |
outset | Outset | outset |

## diagonalThickness Property

### Details

Type: | dimension
Since: | 3.2
Required: | No
Display Name: | Diagonal thickness
JavaScript Type: |
Default Value: | medium
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Diagonal

### Choices

Name | Display Name | Value | Description
thin | Thin | thin |
medium | Medium | medium |
thick | Thick | thick |

## drop Property

Whether the cells defined in this row should expand to fill the entire table or group.

### Details

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

### Choices

Name | Display Name | Value | Description
none | None | none | No drop header is created.
detail | Detail | detail | The header is merged with the cells of the detail rows, but not footer rows.
all | All | all | The header is merged with the cells of the detail rows and footer rows.

### Description

Whether the cells defined in this row should expand to fill the entire table or group. Allows creating a "drop" header within a table. See explanation in the ROM List and Table Specification. Ignored for grids, and for cells that are not in group headers.

## eventHandlerClass Property

The full qulified name of the event handler class.

### Details

Type: | string
Since: | 2.0
Required: | No
Display Name: | Event handler class
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Description

Full quilified name of the event handler class, used to specify an external Java class which define the scripting behavior that will be executed at runtime.

## headers Property

### Details

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

## height Property

Minimum cell height.

### Details

Type: | dimension
Since: | 1.0
Required: | No
Display Name: | Height
JavaScript Type: |
Default Value: | The height is automatically sized to its content.
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Description

Minimum cell height. Generally omitted. The size of the cell is the minimum of the height of its contents and the minimum cell height. The final cell height is set by the overall row.

A better practice is to set the height of the row instead the height of a cell.

## newHandlerOnEachEvent Property

### Details

Type: | boolean
Since: | 2.5
Required: | No
Display Name: | New handler on each event
JavaScript Type: |
Default Value: | false
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

## rowSpan Property

The number of rows that this cell spans.

### Details

Type: | integer
Since: | 1.0
Required: | No
Display Name: | Row span
JavaScript Type: |
Default Value: | 1
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Read-only
Property Sheet Group: | Top

### Description

The number of rows that this cell spans. Defaults to 1, meaning the cell appears in only one row.

## scope Property

### Details

Type: | choice (scopeType)
Since: | 2.5
Required: | No
Display Name: | Scope
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Choices

Name | Display Name | Value | Description
row | Row | row |
col | Column | col |
rowgroup | Row Group | rowgroup |
colgroup | Column Group | colgroup |

## style Property

Name of the style applied to this cell.

### Details

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

### Description

Rows provide many style properties. The style properties are defined in the ROM Styles Specification. A cell can inherit its style properties from a parent element, from a named style, or from a style that identifies the context in which the item appears. This property provides the name of the shared style to use.

This cell can also set the value of style properties. Properties set on this element "override" those inherited from a parent element or a shared style.

### See Also

Style element in the ROM Styles Specification.

## viewAction Property

### Details

Type: | choice (viewAction)
Since: | 2.1
Required: | No
Display Name: | View action
JavaScript Type: |
Default Value: | NoChange
Inherited: | No
Runtime Settable: | No
Property Sheet Visibility: | Hidden
Property Sheet Group: | Top

### Choices

Name | Display Name | Value | Description
NoChange | No Change | NoChange |
Changed | Changed | Changed |
Added | Added | Added |
Deleted | Deleted | Deleted |

## width Property

Minimum cell width.

### Details

Type: | dimension
Since: | 1.0
Required: | No
Display Name: | Width
JavaScript Type: |
Default Value: | Cell width will be computed by the table or grid based on contents.
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Description

Minimum cell width. Can be an absolute or relative width. If omitted, then BIRT or the browser computes the cell width based on content. Many users find it more intuitive to set the width on the column, rather than on individual cells. The overall column width is the minimum of the column width and the width of each cell within the column. All cells are then sized to the width of the column.

### See Also

`width` property of the Column element

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

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

# Slot Detail

## content Slot

Report items that appear inside the cell.

### Details

Display Name: | Content
Since: | 1.0
XML Element: | None. (The contents appear directly within the container element.)
Contents: | List of AutoText, Data, ExtendedItem, FreeForm, Grid, Image, Label, Line, List, Table, TemplateReportItem, Text, TextData
Default Style: | None

### Description

A cell can contain zero, one or more of the following items. The size of the item is defined to be the size of the cell. The (x, y) properties of the item are ignored. The normal case is one item. When a single item appears in a cell, the items within a row are aligned along the text baseline. If multiple items appear within a cell, alignment is undefined. Some rendering environments may baseline-align the first line, others may not.

When multiple items appear within a cell, each item acts a bit like a section: a like break occurs after each item, causing the items to be vertically stacked. The user can set the "display" property of the items to create an in-line layout: items flow from one line to the next with like breaks imposed by the cell width. In-line layout applies to the following only:

- Text (text is treated as a string of text, not a box)
- Label
- Data item
- Image

When items appear in-line, an implied space separates the items. That is, if a grid has two labels "Sample" and "Labels", and they are marked as in-line, the resulting display is "Sample Label", not "SampleLabel".

Alignment within the cell is set by the elements themselves. When multiple items appear, each can have a distinct horizontal alignment. The set of items as a whole can be vertically aligned by setting all items to the same vertical alignment: top, middle, base-line or center. (Note the caveat above for base-line alignment.) If the multiple items have different vertical alignment, then the behavior is undefined. In BIRT-controlled rendering environments, the vertical alignment is determined by the first element.

The user can also put multiple items in a cell by first adding a container, then adding the other items into the container. A container provides greater control over item positioning, including enhanced ability to place items side-by-side.