Class: cWebColumnCheckbox

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

Web list and grid controls provide the basis for creating multi-row, multi-column display and entry. Each column in a grid is represented by a column object. Web lists and grids (cWebList, cWebGrid) use the cWebColumn, cWebColumnButton, cWebColumnCheckbox, cWebColumnCombo, cWebColumnDate, cWebColumnImage and cWebColumnLink classes for column objects.



cWebColumnCheckbox represents a column of checkbox items, for example, a list of orders with a checkbox column that represents whether the order has been filled, or not.

A Checkbox appears as a square box. 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.

A checkbox column 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

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
    
    Procedure OnLoad
        Send Find of oCustomer_DD FIRST_RECORD Index.1
    End_Procedure

    Object oCustomerList is a cWebGrid
        Set pbFillHeight to True
                      
        Object oCustomer_Name is a cWebColumn
            Entry_Item Customer.Name
            Set psCaption to "Customer Name"
            Set piWidth to 50
        End_Object
    
        Object oCustomer_City is a cWebColumn
            Entry_Item Customer.City
            Set psCaption to "City"
            Set piWidth to 50
        End_Object
    
        Object oCustomer_State is a cWebColumnCombo
            Entry_Item Customer.State
            Set psCaption to "State"
            Set piWidth to 40
        End_Object
    
        Object oCustomer_Status is a cWebColumnCheckBox
            Entry_Item Customer.Status
            Set psCaption to "Active"
            Set piWidth to 15
        End_Object
    End_Object
End_Object

The above sample demonstrates a web view (cWebView) containing a data dictionary object (DDO) and a grid (cWebGrid) whose rows and columns are populated from the data dictionary.

The grid contains four column objects, each with a data binding to the Customer table. Two cWebColumn objects are used to display the customer name and city text values; a cWebColumnCombo object is used to display a list of combo items to display and select a state; a cWebColumnCheckbox object is used to display the customer active status in a column of checkboxes.

The OnLoad event is fired when the view is first loaded to the client. This has been augmented to 'seed' the Customer data dictionary with the first record in the table. This seeding will cause the grid to fill its rows with data from the customer table starting with the record found in the OnLoad event.

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 column must have a unique name).

Object Placement

Column controls must be placed within a web list or grid object (e.g. cWebList or cWebGrid).

Data Binding

Checkbox column objects support a data binding to display values from a database Table.Column. When the grid is connected to a data dictionary server object and the column has a data binding then it will display column values from the binding table. Changes entered into the column 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. (IsCustomerActive(Self)) are not supported in web object data bindings. Use the 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 column 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 column's current row.

See also: cWebGrid, psCurrentRowID and OnChangeCurrentRow.

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.

If the grid has a server data dictionary server but the column does not have a data binding, then a special event (OnSetCalculatedValue) is triggered for the column whenever the row value needs to be updated. Write an OnSetCalculatedValue event handler in your column object to generate a 'calculated' value for each record in the server data dictionary object's table.

Size and Location

Grid columns are ordered left to right according to the order of column object declarations in your code. In the above example, the leftmost column would be "Customer Name" and the rightmost column "Customer Status".

Set piWidth to determine the width of the column relative to all the columns in that grid, i.e. relative to the piWidth value of all the other columns.

The actual width of each column is determined by dividing the dividing the column piWidth value 'c' by the total piWidth of all columns 't', multiplied by the actual width of the grid 'g':

Column width = (c / t) * g

Caption

Set psCaption to give the column a title in the grid's header section.

Sorting

If the grid is populated from a data dictionary structure and the column has a data binding, then each grid column with a data binding to an indexed table.column is sortable at runtime. The user can sort the column by clicking in the column header.

Sortable data bound columns will have the pbSortable property set to true by default. Set pbSortable to false to override the ability to sort a column at runtime.

See also cWebGrid and piOrdering, pbReverseOrdering, piSortColumn.

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 colors of a column and the column caption are 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 column.

Styling Web Applications