Eclipse BIRT Report Object Model (ROM)

ScalarParameter Element

# Element Overview

Defines a simple single-value parameter.

### Details

Display Name: | ScalarParameter
Since: | 1.0
XML Element: | `scalar-parameter`
Extends: | AbstractScalarParameter
Extendable: | Yes
Abstract: | No
Name Space: | Parameters
Name Requirement: | Required
Allows User Properties: | Yes
Has Style: | No

### Property Summary

alignment
  How the items should appear in the UI. Choices are auto (default), left, center or right.
autoSuggestThreshold
boundDataColumns
  Bindings the data set column and expressions with the property values..
concealValue
  Hides the user’s entry by displaying asterisks or similar characters. Often used for passwords.
controlType
  The suggested type of UI control to use when displaying the parameter.
fixedOrder
  Whether to display the list sorted in unsorted (fixed) order.
format
  Formatting pattern for showing the parameter in the UI.
mustMatch
  If true, then the value that the user provides must match one of the values in the static or dynamic selection list.
paramType

### Method Summary

getDefaultValueList
getSelectionValueList

### Inherited Properties

comments, customXml, dataSetName, dataType, defaultValue, displayName, displayNameID, distinct, eventHandlerClass, extends, helpText, helpTextID, hidden, isRequired, labelExpr, listLimit, name, newHandlerOnEachEvent, promptText, promptTextID, propertyMasks, selectionList, sortBy, sortByColumn, sortDirection, userProperties, valueExpr, valueType, viewAction

### Inherited Methods

validate

### Description

The data type for the parameter. The data type controls how the Requester formats, parses and validates the parameter. Every type can optionally provide a choice list. And, the parameter can require that the user select one of the choices.

### See Also

`selectionList` property

`defaultValue` property

# Property Detail

## alignment Property

How the items should appear in the UI. Choices are auto (default), left, center or right.

### Details

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

### Choices

Name | Display Name | Value | Description
auto | Auto | auto | Numbers are left aligned, all others are right aligned.
left | Left | left | Values are left-aligned.
center | Center | center | Values are centered.
right | Right | right | Values are right-aligned.

### Description

The parameter selection list provides a developer-defined list of choices. Every choice has two parts: a choice and a label. The label can be externalized and appears in the UI. The choice is the value passed to the report. For example, labels may be "Open? and "Closed?, while the values are ?0? and ?1?.

The items in the list are of the type given by the parameter data type.

### See Also

`mustMatch` property

`fixedOrder` property

`controlType` property

## autoSuggestThreshold Property

### Details

Type: | integer
Since: | 2.3
Required: | No
Display Name: | Auto suggest threshold
JavaScript Type: |
Default Value: | 1
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Hidden
Property Sheet Group: | Top

## boundDataColumns Property

Bindings the data set column and expressions with the property values..

### Details

Type: | List of ComputedColumn Structures
Since: | 2.1
Required: | No
Display Name: | Bound data columns
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Hidden
Property Sheet Group: | Top

### Description

Property values of a scalar parameter can bind to a data set column through bound data columns' names. If a data set column or expression are not bound in the data columns, the exeuction of the expression fails.

### See Also

## concealValue Property

Hides the user’s entry by displaying asterisks or similar characters. Often used for passwords.

### Details

Type: | boolean
Since: | 1.0
Required: | No
Display Name: | Conceal value
JavaScript Type: |
Default Value: | false
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Description

Type of the parameter, can be static or dynamic

### See Also

listLimit

List limitation number.

## controlType Property

The suggested type of UI control to use when displaying the parameter.

### Details

Type: | choice (paramControl)
Since: | 1.0
Required: | No
Display Name: | Control type
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Choices

Name | Display Name | Value | Description
text-box | Text Box | text-box | The user can type in the value.
list-box | Combo/List Box | list-box | Requires a list of choices: static or dynamic. Shown as a list box if set of choices are fixed, combo-box if set of choices is open.
radio-button | Radio Button | radio-button | Only allowed for a fixed set of choices.
check-box | Check Box | check-box | Only for Boolean values
auto-suggest | Text Box - Auto Suggest | auto-suggest |

### Description

The suggested type of UI control to use when displaying the parameter. The default depends on the parameter properties:

- text-box ? Default for non-Boolean values when no choices are available.
- list-box ? Default for parameters with choices.
- check-box ? Default for Boolean values.

The list-box control is rendered in the UI depending on the value of the `mustMatch` property. If `mustMatch` is true, then the user much choose a value from the list, and the control is rendered as a UI list box. However, if `mustMatch` is false, then the user can chose an item from the list, or type in a different value, and the control is rendered as a UI combo box.

### See Also

`mustMatch` property

## fixedOrder Property

Whether to display the list sorted in unsorted (fixed) order.

### Details

Type: | boolean
Since: | 1.0
Required: | No
Display Name: | Fixed order
JavaScript Type: |
Default Value: | true
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Selection list

### Description

An expression on the data row from the dynamic list data set that returns the prompt for the choice. If omitted, then BIRT uses the value as the label.

### See Also

## format Property

Formatting pattern for showing the parameter in the UI.

### Details

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

### Description

Formatting instructions for the parameter value within the parameter UI. For UIs that are able to show formatted parameter values, provides a BIRT format used to display the value. The format is dropped, and the unformatted value presented, when the user edits the parameter value.

Formatting instructions for the parameter value within the parameter UI. By default the UI should use the following rules:

- Text ? No formatting.
- Number, Float, Date-Time ? Default locale formatting.

The format string must be one of the valid BIRT format strings (see the Style element for a list.) The format is used by the UI to display the value after the user moves away from a field. For example, to format a number as a dollar amount.

## mustMatch Property

If true, then the value that the user provides must match one of the values in the static or dynamic selection list.

### Details

Type: | boolean
Since: | 1.0
Required: | No
Display Name: | Must match
JavaScript Type: |
Default Value: | true
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Selection list

### Description

If true, then the value that the user provides must match one of the values in the list. If false, then the values in the list are a reference; the use can enter additional values as well. Ignored if the property does not have a selection list.

## paramType Property

### Details

Type: | choice (scalarParamType)
Since: | 2.2
Required: | No
Display Name: | Scalar parameter type
JavaScript Type: |
Default Value: | simple
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Choices

Name | Display Name | Value | Description
simple | Simple | simple |
multi-value | Multi Value | multi-value |

# Method Detail

## getDefaultValueList Method

### Synopsis

`list obj.getDefaultValueList( )`

### Details

Since: | 2.5
Context: | factory
Arguments: | None
Return Type: | list

## getSelectionValueList Method

### Synopsis

`list obj.getSelectionValueList( )`

### Details

Since: | 2.5
Context: | factory
Arguments: | None
Return Type: | list