Skip to content

Class: cCJGridColumn

Properties | Events | Methods | Index of Classes

Models a grid column. Each column in a cCJGrid is represented by a grid column object.

Hierarchy

Library

Windows Application Class Library

Package

cCJGridColumn.pkg

Description

Every column in a grid is represented by a grid column object. Regular [cCJGrid](cCJGrid.md) objects use a cCJGridColumn object for each column, while data-aware [cDbCJGrid](cDbCJGrid.md) objects use a [cDbCJGridColumn](cDbCJGridColumn.md).

A cCJGridColumn object is used to handle all column level processing. It:

The cCJGridColumn is connected to both the grid and the datasource (cCJGridDataSource). Each grid column represents an element in a datasource row's [tDataSourceRow](../../LanguageReference/tDataSourceRow.md).sValue array. The element position is determined by the order that the grid column is created, which is stored in piColumnId.

Because you normally work with a grid's SelectedRow, you can get and set the value of any column in the SelectedRow with SelectedRowValue and UpdateCurrentValue. The value of any row's column is obtained with RowValue. Since you are not supposed to change a value that is not in the SelectedRow, there is no interface to update a value in other rows. You use DataSource and InitializeData for that.

A regular grid will normally consist of a single cCJGrid object, an internally created cCJGridDataSource object, and multiple cCJGridColumn objects to define the grid. All column information is set within the grid column objects. Data is loaded manually by creating a tDataSourceRow array and sending the grid message cCJGrid.InitializeData.

Object oCJGrid1 is a cCJGrid

    Object oCustomer_Customer_Number is a cCJGridColumn
        Set piWidth to 46
        Set psCaption to "Number"
        Set peDataType to Mask_Numeric_Window
        Set psMask to "######"
    End_Object

    Object oCustomer_Name is a cCJGridColumn
        Set piWidth to 231
        Set psCaption to "Customer Name"
    End_Object

    Object oCustomer_Status is a cCJGridColumn
        Set piWidth to 52
        Set psCaption to "Status"
        Set pbCheckbox to True
        Set psCheckboxTrue to "Y"
        Set psCheckboxFalse to "N"
    End_Object

    Procedure LoadData 
        Handle hoDataSource
        tDataSourceRow[] TheData
        Boolean bFound
        Integer iRows iNum iName iStatus

        Get phoDataSource to hoDataSource

        // Get the datasource indexes of the various columns
        Get piColumnId of oCustomer_Customer_Number to iNum
        Get piColumnId of oCustomer_Name to iName
        Get piColumnId of oCustomer_Status to iStatus

        // Load all data into the datasource array
        Clear Customer
        Find ge Customer by 1
        Move (Found) to bFound
        While bFound
            Move Customer.Customer_Number to TheData[iRows].sValue[iNum] 
            Move Customer.Name to TheData[iRows].sValue[iName] 
            Move Customer.Status to TheData[iRows].sValue[iStatus] 
            Find gt Customer by 1
            Move (Found) to bFound
            Increment iRows
        Loop

        // Initialize Grid with new data
        Send InitializeData TheData
        Send MovetoFirstRow
    End_Procedure

    Procedure Activating
        Forward Send Activating
        Send LoadData
    End_Procedure

End_Object

Grid Column Navigation

The grid column objects handle the column navigation events. When changing columns, the event OnValidating might be sent to the old column (OnValidating is sent on forward keyboard navigation), followed by the OnExiting event. The OnEntering event will then be sent to the new grid column. Any of these can be used to cancel the navigation. If the navigation proceeds, the events OnExit and OnEntry are sent to the old and new columns.

The column objects also assist in the grid's Next and Previous navigations. The grid sends the NextColumn or PreviousColumn message to determine which column should take the focus. These messages send CanNavigateIntoColumn to prospective grid column objects.

Grid Column Activation

Columns are normally created statically at design time. When a grid is activated, the grid and columns are initialized by the CreateGridControl message. Among other things, this sends the CreateColumns message, which sends the CreateColumn message to each column object. This binds COM ReportColumn objects to the cCJGridColumn object class and initializes the grid column. Each column also is sent the OnCreateColumn event.

Creating Dynamic Columns

Columns are normally created statically at design time. You can create columns dynamically at runtime as well. You must create the column object before the grid is activated or before the grid column COM objects are created (before the cCJGrid calls CreateColumns). You could create the objects within OnCreateGridControl.

Object oMyGrid is a cCJGrid
    Set Size to 156 504
    Set Location to 25 15
    Set peAnchors to anAll

    Procedure OnCreateGridControl
        Integer i 
        Handle hoCol

        Send DestroyColumnObjects // destroy existing columns
        For i from 0 to 4
            Get Create (RefClass(cCJGridColumn)) to hoCol
            Set piWidth of hoCol to 80
            Set psCaption of hoCol to ("Column" + String(i+1))
        Loop
        Forward Send OnCreateGridControl        
    End_Procedure

    Procedure LoadData
        tDataSourceRow[] Data
        Integer iCol iCols iRow
        Boolean bFound

        Get ColumnCount to iCols
        For iRow from 0 to 100
            For iCol from 0 to (iCols-1)
                Move ("Row"+String(iRow) * "Col"+String(iCol+1)) to Data[iRow].sValue[iCol]
            Loop
        Loop
        Send InitializeData Data
        Send MovetoFirstRow
    End_Procedure

    Procedure Activating
        Send LoadData
    End_Procedure

End_Object

If you wish to dynamically create columns in an active grid, you can do so (see DestroyColumnObjects for more).

Cell Level Display Customizations

Display attributes can be set at the grid level, the column level, and the cell level. Grid level display attributes are set with grid properties, grid column level display attributes are set with grid column properties, and cell level properties are set using the OnSetDisplayMetrics event. This event is called every time a cell is painted and can be used to customize colors, fonts, and alignment. It can also be used to place images within a cell. See OnSetDisplayMetrics for a complete description of this process.

Using Hidden Columns

The grid control allows the end user to remove a column by dragging the column header off of the grid. The column can be restored by dragging it from the Field Chooser panel back onto the grid. You can also do this under program control with the pbVisible property.

If you set both the pbVisible and pbShowInFieldChooser properties to False, you can create a hidden "virtual" column. This type of column cannot be controlled by the end user and, unless you make it visible programmatically, it will always be hidden. This can be very useful. It provides a mechanism for storing additional row information, which, while needed for processing, should never be displayed. These column values can be accessed using the standard SelectedRowValue and RowValue methods. Their values are created when you create your datasource or set within InitialValue or UpdateCurrentValue.

For example, if you have a list of customers and you want to display all customer names who are credit risks, you could use a hidden column to highlight the credit risk information and then use OnSetDisplayMetrics in the customer name column to set the color as needed. This example uses a data-aware grid, but the technique can be used with all types of grid columns.

Object oCreditRisk is a cDbCJGridColumn
    Entry_Item Customer.Balance
    Set pbVisible to False
    Set pbShowInFieldChooser to False
End_Object

Object oNameCol is a cDbCJGridColumn
    Set piWidth to 183
    Set psCaption to "Customer Name"

    Entry_Item Customer.name

    Procedure OnSetDisplayMetrics Handle hoGridItemMetrics Integer iRow String sValue
        Number nDue
        Get RowValue of oCreditRisk iRow to nDue
        If (nDue > 1000) Begin
           Set ComForeColor of hoGridItemMetrics to "clRed"  
        End
    End_Procedure

End_Object

Hidden columns can also be used to display tooltip text in OnGetToolTip to display information in a tooltip that is not visually represented in the row.