Class: dbGrid [Obsolete]

Properties  Events  Methods    Index of Classes

Enables users to view and edit a scrolling, multi-column list of field values from a database file



Library: Windows Application Class Library

Package: Dftable.pkg


This class is obsolete. It has been replaced with the cDbCJGrid class.

As of revision 16.0, DataFlex includes full support for Codejock Software's COM Report Control package for creating grids. See Using Grids for more information.

dbGrid is used to enable users to view and edit a scrolling, multi-column list of column values from a database table. The dbGrid class supports combo forms, checkboxes, spin forms and prompt buttons in individual columns or cells.


Object OrderDtl_Grid is a dbGrid
    Set Main_File to Orderdtl.File_Number
    Set Server to Orderdtl_DD
    Set Ordering to 1
    Set Wrap_State to True
    Set Size to 63 377
    Set Location to 90 3
        Entry_Item Invt.Item_id
        Entry_Item Invt.Description
        Entry_Item Invt.Unit_price
        Entry_Item Orderdtl.Price
        Entry_Item Orderdtl.Qty_ordered
        Entry_Item Orderdtl.Extended_price
    Set Form_Width    0 to 55
    Set Header_Label  0 to "Item Id"
    Set Form_Width    1 to 116
    Set Header_Label  1 to "Description"
    Set Form_Width    2 to 55
    Set Header_Label  2 to "Unit Price"
    Set Form_Width    3 to 43
    Set Header_Label  3 to "Price"
    Set Form_Width    4 to 43
    Set Header_Label  4 to "Qty"
    Set Form_Width    5 to 55
    Set Header_Label  5 to "Total"
    Set Child_Table_State to True     // Saves when exit object
End_Object    // OrderDtl_Grid


Use dftable

Object oObjectName is a dbGrid
    Set Size to Height Width
    Set Location to Row Column
    Set Main_File to FileName.File_Number
    Set Ordering to Index#
    Set Server to DDOName
    Set Child_Table_State to true|false
    Set Wrap_State to true|false
    Set Allow_Bottom_Add_State to true|false
    Set Allow_Top_Add_State to true|false
    Set Allow_Insert_State to true|false
    Set No_Create_State to true|false
    Set No_Delete_State to true|false
    Set Read_Only_State to true|false
    Set Auto_Regenerate_State to true|false
        entry_item {table.field | expression}
    Set Highlight_Row_State to true|false
    Set Gridline_Mode to GridVisibleMode
    Set Header_Visible_State to true|false
    Set Resize_Column_State to true|false
    Set CurrentCellColor to RGBColor
    Set CurrentCellTextColor to RGBColor
    Set CurrentRowColor to RGBColor
    Set CurrentRowTextColor to RGBColor
    Set Highlight_Row_State to true|false
    Set Gridline_Mode to GridVisibleMode
    Set Form_width col# to ColumnWidth
    Set Header_Label col# to HeaderLabel
    Set Header_Justification_Mode col# to Mode
    // These are set when there is no data-dictionary
    Set Status_Help col# to StatusHelpText
    Set Form_DataType col# to type
    Set Form_Mask col# to Mask
    Set Numeric_Mask col# to leftDigits rightDigits {template}
    Set Currency_Mask col# to leftDigits rightDigits {template}

Of Special Note

A dbGrid displays multiple records from a main file and any ancestor (parent) files, and allows users to edit them one at a time. At any given moment, the row of the grid the cursor is on is considered the current row, and the record in the main file whose data is displayed therein, the current record. Thus, the dbGrid appears for purposes of editing and display the same as a dbForm.

DbGrids should always be placed inside a dbView object or a data-aware container (dbContainer3d, dbGroup, dbTabPage, dbTabView). The DataDictionary used by the object should be above the entry grid and inside the entry-view container.

Data Entry Object

The dbGrid is a multi-item data entry object (DEO). A DEO is an object whose native capabilities (in this case a grid) are augmented with data-aware behaviors. These behaviors include:

Setting Entry Parameters for Columns

Previous revisions of DataFlex allowed you to set column parameters by placing special parameters on the entry_item command line. These options would be placed inside French braces (entry_item file.field {capslock, iPrompt =(myObj(Self)), iEntry =msg_MyMessage} ). Data dictionaries all but obviate the need for these settings. Normally these settings can and should be placed inside your data-dictionary subclasses. In addition, the Studio does not support the use of these command-line options.

In the rare case where you need to set any of these options for columns within your data entry object, a complete interface is provided for getting and setting any of them. The single-item data entry classes use one set of messages for setting these parameters, while the row-based data entry classes (such as this class) provide a parallel set of messages for setting these parameters on a column-by-column basis. These messages are documented in the datalist class. Below is a summary of all these messages. This list shows the single-item-based message, its equivalent row-based message, and the entry_item option it replaces. Each of these messages supports a get and a set syntax.

Form-Based Messages dbForm, dbComboForm Grid Column-Based Messages dbGrid, dbList Old Entry_Item {option} (no longer used)
Item_Options Column_Options Required, FindReq, NoEnter, NoPut, DisplayOnly, AutoFind, etc.
Item_Option Column_Option (same as above)
Enabled_State (formerly object_shadow_state) Column_Shadow_State DisplayOnly
Capslock_State Column_Capslock_State Capslock
Prompt_Object Column_Prompt_Object iPrompt=
Zoom_Object Column_Zoom_Object iZoom=
Item_Entry_msg Column_Entry_msg iEntry=
Item_Exit_msg Column_Exit_msg iExit=
Item_Validate_msg Column_Validate_msg iValidate=

Using Data Dictionaries

When this object's server is a data dictionary, this object will acquire a great deal of "knowledge" from the server. It will "know" data types, input masks, status-help and prompt objects, validation rules, entry rules, exit rules, display formats (capslock, etc., noput, displayonly, etc.) and much more regarding the data file and its fields. If you use data sets, these settings may all be controlled by setting properties. While possible, this requires a great deal more work and greatly increases the chances of errors and inconsistencies.

Navigating with Arrow Keys

By default, the up and down arrow keys navigate within the dropdown list. This can be changed to navigate between rows in the grid by setting the pbComboNavigation property to False.


This class supports input and display masking for a variety of data-types (text, numeric, currency, and dates). When using data dictionaries, the mask and mask type of the object's items will usually be defined within the data file's data-dictionary subclass. The only time you will need to deal with masks is when you are creating masks for non-data-dictionary based items (expressions and variables).

When manually setting masks, the type of masking used is determined by the object's column form_datatype (which supports both masked and non-masked types) and the object's column form_mask. Two additional messages, currency_mask and numeric_mask, make it particularly easy to define currency and numeric data types and fields with a single message.

Saving and Deleting a Row

Any time a user navigates off of a grid line, any changes made must be saved or cleared. The auto_save_state of a dbGrid is, by default, set to true Anytime a user attempts to move off a line on which they have made a change, a save is done. Tables are usually most-intuitive when saves occur automatically.

The verify_save_msg is set to get_no_confirmation. This disables a verification message with each record save. If desired, you may set this property to get_line_save_confirmation, which causes a line-save confirmation to appear each time a record is about to be saved. The verify_delete_msg has been changed to get_line_delete_confirmation which causes a line-delete confirmation to appear before a delete.

Prompt Headers

This class automatically supports prompt-button labels. If a prompt object is defined for this object, its header becomes "prompt-button-enabled". When any column heading is clicked, the prompt message will be sent and a prompt object (usually a selection list) will appear. Prompt objects are usually acquired from the data-dictionary object, but may be specified in this object by setting the prompt_object property. When a header is prompt-button-enabled, the symbols >> are added to the right of the header label to indicate that a prompt is available.

If you do not want automatic prompt-button creation, you may disable this feature by setting the property prompt_button_mode to PB_PromptOff.

The Server

All dbGrid objects should always be connected to a server (a data-dictionary object). When used as a child table (e.g. order entry detail table), it is quite likely that the server property will be set explicitly within the dbGrid object. If not set in the object, it must be set within a parent (or other ancestor) container object.

Main File, Server DDO, and Index

A main file must be specified for this object, either through an explicit main_file declaration, or by relying on the main_file of DDOname through the server property. Likewise, an index must be named unless one is named in DDOname. The selection list can use a different main_file and index from that of a named DDO, but the index must be one of the indexes of the main_file. If no index is specified at any level, records are listed in recnum order.

Descended from Grid Super-class

The dbGrid class is descended from the grid class. There are numerous messages supporting header labels, form width, grid lines, etc. Refer to the Grid class for a full description of these properties.

Most of the default column-property settings will perform as desired. Normally you will only need to set the form_width and header_label properties.

Item and Row Color and Grid lines

The color of the current row and current item is set with the CurrentCellColor and the CurrentRowColor. These are rgb colors. By default, these values are set by reading keys from the registry. This allows for the customization of colors without recompiling. The colors must be set in the registry because there is no standard Windows default color for highlighted rows and cells.

The ItemColor message allows you to manage the background color of any cell or cells in a grid. When used inside the entry_display procedure, this message can be used to color items according to a field's value. The entry_display message is called every time a row is updated with information from the database. By using the value in the current record buffer, a set ItemColor statement, a get base_item statement (to ascertain the first cell in the current row), and a get item_limit statement (to ascertain the number of cells in a row), you can manage row and cell colors.

The background color of an item is determined by three states. An item may be the current item, an item may be an item within the current row, or an item may be a member of a non-current row. The precedence of color assignment is as follows:

1. CurrentCellColor overrides all other colors.
2. CurrentRowColor, if used (highlight_row_state is true), overrides non-current row color.
3. Non-current row uses ItemColor.

If you wish to use ItemColor to create custom row colors, you will probably wish to set the highlight_row_state property to false.

The following example, which could be added to a dbGrid or a dbList, shows how ItemColor could be used to set a custom color for a row and a cell.

// Changes the color of all items in the current row to RGB color 'iColor'
// This should be sent from Entry_Display as shown later...
Procedure Change_Row_Color Integer iColor
    Integer iBase iItem iItems
    Get Base_Item to iBase               // first item of current row
    Get Item_Limit  to iItems              // items per row
    Move (iBase+iItems-1) to iItems     // last item in the current row
    For iItem from iBase to iItems         // set all items in row to color 
        Set ItemColor iItem to iColor
End_Procedure // Change_Row_Color
// Augmented in order to get the row, and possibly cell, highlighted
// with a specific color depending on its file-buffer values
Procedure Entry_Display Integer iFile Integer iType
    integer iColor iItem
    // set current row color based on value of extended price
    If (OrderDtl.Extended_Price < 0) ;
        Move clRed to iColor
    Else ;
        If (OrderDtl.Extended_Price = 0 ) ;
            Move clYellow to iColor
        Else ;
            Move clTeal to iColor

    Send Change_Row_Color iColor
    // Set single cell (column 5) based on contents of qty_ordered
    If OrderDtl.Qty_Ordered ge 10 Begin
        Get Base_Item to iItem // first item of the current row
        Set ItemColor (iItem+4) to clPurple // Fifth column
    Forward Send Entry_Display iFile iType
End_Procedure // Entry_Display

The gridline_mode, which specifies whether horizontal and vertical lines should appear in the list, can also be set with a registry setting. If you set the key TableGrid in the registry, you must use the values 0 through 3 (0=Grid_Visible_none, 1=Grid_Visible_Horz, 2=Grid_Visible_Vert, 3=Grid_Visible_Both).

Refer to the Grid class for more information on these properties.

The purpose of supporting unique settings for colors in dbGrids and dbLists (which have their own registry key values) is to provide a mechanism for distinguishing between selection lists (dbLists) and entry tables (dbGrids). DbGrid uses the standard grid and color provided with the grid class.

Creating Checkbox Columns in dbGrids

Any column in a dbGrid may be represented as a checkbox by setting the column property column_checkbox_state to true. If that column's field is defined as a checkbox field in its data dictionary, the column will the display the field's true and false values (which are defined in the data dictionary) in a checkbox format.

In the following example, assume that Column 3 in a dbGrid represents the data field Customer.Active. Within the data dictionary, this field is defined to be a checkbox field with a true value of T and a false value of F. If this field is represented in normal non-checkbox format, Column 3 will be displayed as a column of Ts and Fs. Users can edit these values by changing their value to either T or F. All other values will result in a validation error. This column can be converted to a checkbox column with the following code.

    Set Column_CheckBox_State 3 to True

When set in this fashion, all data values of T will appear as a checked item and all data values of F will appear as an unchecked item. If the checked state of a cell is changed by a user, the underlying data value will also be appropriately changed to T or F.

Accelerator Keys

Name Message Sent
kadd_mode add_or_remove_row
kbegin_of_data beginning_of_data
kclear request_clear
kclear_all request_clear_all
kdelete_record request_delete
kend_of_data end_of_data
kfind find_ge
kfind_next find_next
kfind_previous find_previous
ksave_record request_save
ksuper_find superfind
ksuper_find_next superfind_next
ksuper_find_previous superfind_previous