Class: cWebRadio

cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseControl
---------------cWebBaseDEO
------------------cWebRadio

Use the cWebRadio class to create a group of multi-choice radio controls in your web view or dialog. Radio controls are ideal for presenting a set of options or settings, for example choosing between "Portrait" or "Landscape" in a print options dialog.



Radio controls are selected by clicking on the control with the mouse or by navigating to the control and pressing the spacebar. When one radio control in a group is selected, the other controls in that group are cleared.

Radio controls can be used with or without a data binding. When used with a data binding radio controls provide support to display and allow editing of data from a database table.column. When used without a data binding, you will use the class interface to read or write the control value.

Sample

Object oCustomer is a cWebView
    Object oCustomer_DD is a Customer_DataDictionary
    End_Object 

    Set Main_DD To oCustomer_DD
    Set Server  To oCustomer_DD

    //...

    Object oCustomerActive is a cWebRadio
        Entry_Item Customer.Status
        Set psRadioValue to "Y"
        Set psCaption to "Active"
    End_Object 

    Object oCustomerInactive is a cWebRadio
        Entry_Item Customer.Status
        Set psRadioValue to "N"
        Set psCaption to "Inactive"
    End_Object
End_Object

The above example demonstrates two radio controls with data-binding to the Customer.Status column. One radio control is required for each possible value in Customer.Status. The psRadioValue property determines what Customer.Status value is represented by which radio control.

Object oRadioDlg is a cWebModalDialog
    Set piColumnCount to 6
    
    Object oRed is a cWebRadio
        Set psRadioValue to "RED"
        Set psCaption to "Red"
    End_Object 

    Object oGreen is a cWebRadio
        Set psRadioValue to "GREEN"
        Set psCaption to "Green"
    End_Object 

    Object oBlue is a cWebRadio
        Set psRadioValue to "BLUE"
        Set psCaption to "Blue"
    End_Object

    Send SetSelected to oGreen

    Object oShowChoice is a cWebButton
        Set psCaption to "Choose"
        
        Procedure OnClick
            String sValue
            WebGet psValue of oBlue to sValue
            Send ShowInfoBox to ghoWebApp ("You chose " + sValue)
        End_Procedure
    End_Object
End_Object

The above example demonstrates a group of three radio controls. By default, the first radio object (oRed) is the selected radio object. In this example we send SetSelected to oGreen to make that the default selected radio.

In the OnClick event of the button object, we read the value of the currently selected radio object in this group (psValue) and display it in a message. Here we WebGet psValue of the oBlue radio, but we could have chosen to read psValue from any radio object in the group and the answer would be the same.

Object Name

The Web Framework uniquely identifies each web object via a combination of the object hierarchy (object nesting), and object name. This means that web object names must be unique within their parent (i.e. each sibling web object must have a unique name).

Object Placement

Radio controls must be placed within a web container (e.g. cWebPanel, cWebView or cWebModalDialog).

Radio controls may not be nested inside other web controls. You may not mix web panels and web controls as sibling objects.

Grouping Radio Controls

Radio controls are designed to form groups by object placement. By default, all sibling radio controls belong to the same group, i.e. all direct child radio controls of a container object, such as cWebPanel or cWebView, belong to the same group.

If you wish to have multiple radio groups inside a container, then you can:
- Divide the container into sub containers (e.g. using panels - cWebPanel) and place the radio controls inside these panels, or,
- Explicitly assign a group name to each radio control.

Set psGroupName to assign a group name to a radio control. All radio controls that belong to a particular group should have the same unique group name.

Setting and Getting the Selected Radio

Send SetSelected to any radio object in a group to make that object the currently selected radio.

Call GetSelected of any radio object in a group to test if it is the currently selected radio.

WebGet psValue of any radio object in a group to get the selected radio object's radio value (i.e. that object's psRadioValue).

Set pbServerOnSelect to True to instruct the client to send the OnSelect event to the server object whenever the radio object is selected by the user. Write an OnSelect event handler in your radio object to perform some action when it is selected. This event only fires when the user selects the radio object by clicking or pressing spacebar when the object has the focus. It does not fire when you programmatically select the radio object.

Data Binding

Radio objects support a data binding to display values from a database Table.Column. When the control has a data binding then it will be selected if the column value of the current record in the binding table matches that radio object's psRadioValue property.

Changes entered into the control will update the table.column value in the correct way according to DataDictionary data binding rules.
Use the Entry_Item command to set the data binding. You must also set each radio object's psRadioValue property to cover the total set of possible values for that Table.Column.

Example:

Entry_Item Customer.Status
Set psRadioValue to "Y"

Use the OnSetCalculatedValue event to define a data binding expression.

The data binding table.column must map to a data dictionary object in the server data dictionary object structure. Refer to the Data Dictionary Guide for more information.
A data binding provides data-aware behaviors that include:
- Finding, clearing, saving, and deleting records
- Prompt-object support
- Change verification (save, delete, and data-loss verifications)

Size and Location

Web controls are positioned by HTML flow layout (left to right, top to bottom). The relative position of the control in this flow is determined by the location of the object declaration in your code.

In addition to the flow layout, each web container is divided into a fixed number of equal-width columns (piColumnCount). Child controls are aligned to these columns to determine their horizontal position and width.

Set piColumnIndex to position a radio control in a particular column of the parent container.

Set piColumnSpan to determine the width of the radio control i.e., the number of columns occupied by the control. The actual width is determined by the number of columns and the width of the parent container.

For more information, see Positioning and Layout of Controls.

Each radio control has a pre-determined height according to the web application's CSS theme (psTheme). You can also instruct a radio control to occupy all available vertical height in its parent container by setting pbFillHeight to true.

Label Support

All web controls support the ability to display a label. A label is a text string which is positioned outside the control and is used primarily to describe the control.

When the width of a control is calculated via its column span, a fixed portion of this width is assigned to the label (usually around 120px); the remaining space is used by the control itself.

The use of labels in a cWebRadio control is considered superfluous and unusual as the label positioning system does not match the expected radio caption position. Instead, use psCaption to assign a descriptive string to radio controls.

Set pbShowLabel to true to shift the radio and create space for the control's label and to show the label. By default, pbShowLabel is False. Set psLabel to set the label text.

Drag and Drop Support

This control can be used as a valid drop target by registering it as such in a cWebDragDropHelper object.

The supported actions for this control are:
- C_WebDropOnControl

This allows the control to accept data dragged from elsewhere in the control (if configured that way) and can also be used to accept files when registered within a cWebDragDropFileHelper.

Color

The color of a radio control is determined by the web application's CSS theme (psTheme). You can define additional or replacement CSS styles in your web application's application.css file. Set psCSSClass to the CSS class name you would like to be applied to a radio control.

Set psTextColor to directly override the control's CSS themed color.

Styling Web Applications