pp108 : Radio

Radio

You can use the Radio control to add a radio button to an XForm. You can also add multiple radio buttons to an existing Radio control to create a group of radio buttons that represent various input options of a field in the XForm.

The Radio control enables you to provide mutually exclusive alternatives as input values for a field. You can select just one radio button from a group such that you can select only one input option at a time. When you select an option, the previously selected option, if any, is cleared.

Radio controls can be data-bound or free-form controls. When data-bound, a Radio control is bound to the model from which it fetches data. You can use a free-form Radio control to display any arbitrary data. Radio controls are not supported in tables.

Radio buttons are automatically generated when the WSDL from which the user interface is generated, contains an enumerated field with five or less values.

A group of radio buttons is represented as <control ID> such as radio1, while a single radio button in a group is represented as <control ID>[<index number>] such as radio1[2]. For example, you can programmatically set labels for radio buttons as follows:

  • radio1.setLabel("Payment Options"); for a group of radio buttons.
  • radio1[1].setLabel("Credit Card"); for an individual radio button.

Properties, Events, and Methods of the Control

The properties, events, and methods associated with the Radio control define its behavior. You can set them either through the control's property sheet or programmatically using the APIs.

Table 1. List of Properties

Design-time property

Run-time property

Description

ID

Sets the string that identifies the control on an XForm. If not specified, a unique ID is automatically generated. This applies to a group of radio button controls. Use the index to access the individual radio button; for example radio1[0].

Model

Sets the ID of the data model from which the data (specified using the Reference property) is displayed in the control. If model is not specified, it is inherited from the parent control's model.

Reference (xql)

Sets the location or expression for the XPath that contains the data (value) displayed in the control. The XPath refers to the child node or descendants of the immediate parent control's reference.

Value

Sets the value that a radio button control represents. This property is mandatory and unique for each radio button control on the XForm. If not specified, the value will remain empty.

Class Name

className

Sets or retrieves the class name applied on the control.

Tooltip

title

Sets the tool tip that appears on each radio button control when the mouse is moved over it. Programmatically, this property is set by specifying the title property of the control.

Task Part

Creates a task part for the control. Selecting the check box, displays the Task Part pane.

businessObject

Retrieves the root node of the XML data associated with the control; the location of the data is specified by the Reference property.

currentContext

Retrieves the immediate parent of the data that the control represents. This data is the child node of the business object.

data

Retrieves the XML node of the data (value) that the control represents. The location (XPath) of this XML inside the business object is set through the Reference property.

Table 2. List of Events

Event

Description

Change

This event is activated when you select a radio button, after the Validate event has been fired.This event is not fired if the Radio control does not have any value.

Data Bind

This event is activated before the data is bound to the control.

Validate

This event is fired when a radio button is selected. It is a custom-script validation, using which you can perform your own validation.

Table 3. List of Methods

Method

Description

addListener()

This method registers the control to receive notifications for an event.

disable()

This method disables the radio button on which it is invoked. It is invoked on a single radio button.

enable()

This method enables the radio button on which it is invoked. It is invoked on a single radio button.

getBusinessObject()

This method retrieves data or business object.

getLabel()

When invoked on a radio button, it returns the label object of the radio button, and when invoked on a group of radio buttons, it returns the common label object of the group.

getValue()

This method returns the original selection made on the group of radio buttons, as available in the database. It returns 'UNDEFINED', if no value is set. It is invoked on a group of radio buttons.

hide()

This method hides a radio button. It is invoked on a single radio button.

isEnabled()

This method retrieves the value that denotes whether the control is enabled or not.

rebind(oBusinessObject)

This method is available for all controls bound to a model. This method refreshes the control with data from the business object that is passed as a parameter. If no parameter is passed, the business object of the model's activeTuple node is used and the control is refreshed.

removeListener()

This method unregisters the control to cease receiving notifications for its events.

setLabel(sText)

When invoked on a radio button, it sets the label of the radio button, and when invoked on a group of radio buttons, it sets the common label of the group. It is available for all controls associated with labels.

setValue(sValue)

This method sets the value as specified in the group of radio buttons. The sValue parameter denotes the value to be set. If no value is specified, all control selections are removed. It is invoked on a group of radio buttons.

show()

This method makes the radio button visible. It is invoked on a single radio button.