cObject
---cUIObject
------DfBaseObject
---------DfBaseWindow
------------DfBaseUIWindow
---------------DfBaseControl
------------------DfBaseList
---------------------DfBaseForm
------------------------DfBaseEntry
---------------------------DfBaseEntryList
------------------------------EntryList
---------------------------------WideList_
------------------------------------WideList
---------------------------------------DataList_
------------------------------------------DataList
---------------------------------------------dbGrid_
------------------------------------------------dbGridDS
---------------------------------------------------dbGridDD
------------------------------------------------------dbGrid
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
Begin_Row
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
End_Row
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
:
Begin_Row
entry_item {table.field | expression}
:
End_Row
:
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}
End_Object
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.
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:
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= |
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.
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.
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.
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.
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.
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.
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.
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
Loop
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
End
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.
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.
| 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 |