Class: cWebCheckbox

cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseControl
---------------cWebBaseDEO
------------------cWebCheckbox
---------------------cWebColumnCheckbox

Use the cWebCheckbox class to create a click-to-toggle checkbox control in your web view or dialog. A checkbox is ideal for representing yes-no or true-false values or options in your web application.



A checkbox appears as a square box with text. The checked state may be toggled on or off by placing the cursor on it and pressing spacebar or clicking it with the mouse or by directly setting the control value (via psValue or SetChecked).

A checkbox can be used with or without a data binding. When used with a data binding, the checkbox provides automatic 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.

The appearance of the box indicates whether it is checked with a checkmark.

Sample

This sample demonstrates a cWebView with a DataDictionary object (DDO) and a cWebCheckbox object with a data binding to the Customer table, Status column.

Object oCustomerView is a cWebView
    Object oCustomer_DD is a Customer_DataDictionary
    End_Object

    Set Main_DD to oCustomer_DD
    Set Server to oCustomer_DD

    Object oCustomer_Status is a cWebCheckbox
        Entry_Item Customer.Status
        Set psCaption to "Active Status"
    End_Object
End_Object

Sample

This sample demonstrates the use of a cWebCheckbox object with no data binding. When the checked state changes (intercepted in the OnChange event), a message is displayed at the client displaying the new checkbox value.

Object oConfigView is a cWebView
    Object oAllowSave is a cWebCheckbox
        Set psCaption to "Allow save"
        Set pbServerOnChange to True
    
        Procedure OnChange String sNewValue String sOldValue
            Forward Send OnChange sNewValue sOldValue
            Send ShowInfoBox to ghoWebApp ("New State: " + sNewValue)
        End_Procedure
    End_Object
End_Object

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

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

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

Data Binding

Checkbox objects support a data binding to display values from a database Table.Column. When the control has a data binding, it will display the column value of the current record in the binding table. Changes entered into the control will update the table.column value in the correct way according to data dictionary data binding rules.

Use the Entry_Item command to set a data binding.

Sample

Entry_Item Customer.Name

The data binding table.column must map to a data dictionary object in the server data dictionary object structure. This data dictionary object should have a Field_Checkbox_Value setting for the binding table.column. Field_Checkbox_Value determines which data value is represented as 'checked' and which data value represents 'unchecked'. Refer to the Data Dictionary Guide for more information.

Entry_Item expressions, e.g. (Customer.IsActive or Customer.IsNew) are not supported in web object data bindings. Use OnSetCalculatedValue to define a data binding expression.

A data binding provides data-aware behaviors that include: Change verification (save, delete, and data-loss verifications), tooltip, control focus rules, control blur rules and much more. These settings may also be controlled manually by setting properties.

Accessing the Control Value

The checkbox control can be used without a data binding by reading and changing the control's value.

The psValue property allows you to get or set the current 'value' of the checkbox control.

The control determines the 'checked' or 'unchecked' state by comparing psValue to the psChecked and psUnchecked properties, respectively.

Send the SetChecked message to check or uncheck the control without knowing anything about the psValue, psChecked or psUnchecked properties. The GetChecked function retrieves the current checked state.

An event is triggered whenever the checked state changes. This event can be handled on the server by writing DataFlex code. It can also be handled on the client (browser) by writing JavaScript code. Writing a server-side DataFlex handler is the simplest way to handle change events.

Set pbServerOnChange to True to instruct the client to send the OnChange event to the server object whenever the checked state is changed. Write an OnChange event handler in your cWebCheckbox object to perform some action when the checked state changes.

To write a client-side change event handler using JavaScript, set the psClientOnChange property to the name of the JavaScript function that will execute when the checked state changes.

If the control has a data dictionary server, but does not have a data binding, then a special event (OnSetCalculatedValue) is triggered for the checkbox object whenever a find or clear operation is performed on the data dictionary object. Write an OnSetCalculatedValue event handler in your checkbox object to generate a 'calculated' value for the control for each record in the server data dictionary object's table.

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 checkbox control in a particular column of the parent container.

Set piColumnSpan to determine the width of the checkbox 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 checkbox control has a pre-determined height according to the web application's CSS theme (psTheme).

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.

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 cWebCheckbox control is considered superfluous and unusual as the label positioning system does not match the expected checkbox caption position. Instead, use psCaption to assign a descriptive string to checkbox controls.

Set pbShowLabel to true to shift the checkbox 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.

Caption

Set psCaption to display a caption string to the right of the checkbox control. Use this instead of psLabel.

Color

The color of a checkbox 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 checkbox control.

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

See Styling Web Applications for more information.