cObject
---cUIObject
------DfBaseObject
---------DfBaseWindow
------------DfBaseUIWindow
---------------DfBaseControl
------------------DfBaseList
---------------------DfBaseForm
------------------------DfBaseEntry
---------------------------DfBaseEntryList
------------------------------EntryList
---------------------------------WideList_
------------------------------------WideList
---------------------------------------DataList_
------------------------------------------DataList
---------------------------------------------dbList_
------------------------------------------------dbListDS
---------------------------------------------------dbList
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.
dbList is used to enable users to select one or more values from a list of choices. The choices must come from database file(s). DbLists must be placed inside a DEO container. When used as selection lists, they are placed inside a dbModalPanel object.
Use dfAllEnt.pkg
Object Salesp_sl is a dbModalPanel
Set Label to "Sales People List"
Set Size to 119 265
Object SalesP_DD is a SalesP_DataDictionary
Procedure OnConstrain
Constrain SalesP.Status eq "A"
End_Procedure
End_Object
Set Main_DD to SalesP_DD
Set Server to SalesP_DD
Object oList is a dbList
Set Main_File to Salesp.File_Number
Set Size to 71 251
Set Location to 6 6
Begin_Row
Entry_Item Salesp.Id
Entry_Item Salesp.Name
End_Row
Set Form_Width 0 to 40
Set Header_Label 0 to "Id"
Set Form_Width 1 to 200
Set Header_Label 1 to "Name"
End_Object // oList
Object OK_bn is a Button
Set Label to "&Ok"
Set Location to 84 99
Procedure OnClick
Send Ok of oList
End_Procedure
End_Object // OK_bn
Object Cancel_bn is a Button
Set Label to "&Cancel"
Set Location to 84 153
Procedure OnClick
Send Cancel of oList
End_Procedure
End_Object // Cancel_bn
Object Search_bn is a Button
Set Label to "&Search..."
Set Location to 84 207
Procedure OnClick
Send Search of oList
End_Procedure
End_Object // Search_bn
On_Key Key_Alt+Key_O Send KeyAction of Ok_bn
On_Key Key_Alt+Key_C Send KeyAction of Cancel_bn
On_Key Key_Alt+Key_S Send KeyAction of Search_bn
End_Object // Salesp_sl
Use dfSelLst.pkg
Object oObjectName is a dbList
Set Size to Height Width
Set Location to Row Column
Set Main_File to FileName.File_Number
Set Ordering to Index#
Set Main_DD to (DDO(Self))
Set Server to (DDO(Self))
Set Auto_Index_State to true| false
Set Auto_Column_State to true| false
Set Auto_Server_State to true| false
Set Auto_Shadow_State to true| false
Set Auto_Label_State to true| false
:
Begin_Row
entry_item {file.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 CurrentRowColor to RGBColor
Set Highlight_Row_State to true| false
Set Gridline_Mode to GridVisibleMode
// Column-based properties. repeat for each column
Set Form_Width col# to ColumnWidth
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}
Set Header_Label col# to HeaderLabel
Set Header_Justification_Mode col# to Mode
End_Object
This class specifies a single- or multi-select list of choices from a database file(s). By default, a selection list will seed itself with the contents of the object item from which it was invoked, start in the column of the list that matches the field for the item from which it was invoked, employ a fast, non-incremental search method for jumping around the list, and automatically update the invoking object without its needing to share that object's DDO.
The default behaviors of the dbList are quite powerful. With auto_index_state true (which causes the sort order to change automatically when users switch from column to column) and auto_column_state true (which causes the column to be selected automatically upon startup based on the file.field of the invoking item), it will handle most of your selection-list needs. There are a number of properties and message handlers that can allow even greater control over selection lists. You will normally not need to use these, but when needed, they can make the difference between a good selection list and a great one.
Objects of this class can and should be used with data dictionaries. A dbList may contain its own data-dictionary object (create a DDO structure and connect the DEO with the set server message.) or it may use the DDO of its invoking object (set auto_server_state to true). When a dbList is connected to a DDO, it uses information about a column's shadow state (DD_DisplayOnly), mask type and value, Capslock status, and, if auto_label_state is true, its label. Using data dictionaries therefore makes lookup lists much easier to program.
DD objects are also used to provide finding constraints for a list. If a dbList uses its own DDO, that DDO may be used to define constraints. If the dbList uses an auto-server, the constraints of the invoking DDO will be used.
Auto_label_state is used to specify whether a list's header labels should be assigned explicitly with the set header_label message or if the labels should be assigned from the data dictionary.
The dbList class is normally used as a modal popup selection list. It is placed inside a modal panel object (dbModalPanel) and is used by views to select a record. All of the behaviors required to support lookups are supported by a default dbList.
A dbList may also be used for non-lookup purposes. In this case, it is used more like a dbGrid except that does not support data entry into the cells. When using one this way, you need to disable a number of the startup (seed the list, find the right column) and shut-down (move the selected value to the invoking object) properties. You do this by setting the property move_value_out_state to false. When used in this fashion, it is very important to set this property false. Failing to do will generate a number of runtime errors.
When used as a lookup list (move_value_out_state is true), this object will need to update the invoking object with a selected record or value, a process called "export." There are two types of export behaviors: relational and non-relational. Usually a lookup is "relational". This means that the list's main file is the same as the main file of the invoking object. In such a case, the selected record must be returned to the invoking object. In fact, the selected record must be returned to the invoking object's data-dictionary object. This way, all other records (parent and children) are found as needed and all objects in the view are properly updated with the new record.
This object might alternatively be used to find a non-relational record. In this case, the main file of the list and of the invoking object are different. The list will return the selected item back to the invoking object (no record finding in the view is involved).
This object will determine if it is being used for a relational or non-relational lookup and will update the invoking object accordingly. If you wish, you may override this automatic behavior by setting the property auto_export_state to false, and setting the property export_item_state to false to force a relational update, and true to force a non-relational update. There should be little need to do this.
A main file must be specified for the object, either through an explicit main_file declaration, or by relying on the main_file of DSOname through the server property. Likewise, an index must be named unless one is named in DSOname or Auto_index_State is used (which is suggested). The selection list can use a different main_file and index from that of a named DSO, 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.
Often you will want this object to respect the finding constraints of the view that invoked it. Technically, you will want it to acquire the constraints of the invoking object's server. This is done by setting this object's auto_server_state to true. When this property is true, this object will latch onto the invoking view's data-server structure upon activation and disconnect upon deactivation.
If users need to jump from one row in a sorted column to another, they may simply start typing the new target value. This pops up a search window. Type in the value and press Enter (or press the OK button) and the list will refresh itself around the new target item. This is the preferred method of searching through a list. It is fast, easy, and intuitive. This behavior is supported when the property popup_search_state is true, and the property find_search_state is false. This is the default. Several other search options are supported.
If popup_search_state is false and find_search_state is false, the list will support an "in-place" incremental search. When used this way, the list is refreshed each time a key is pressed. Each refresh results in a refinding of each record in the list. Since this method often requires many keystrokes before getting close to the target, this is not a particularly effective way to find records in a large database It also does not work well with numbers or dates.
If popup_search_state is false and find_search_state is true, the list will support an "in-place" non-incremental search. This works exactly like a popup search except that a search window is never displayed.
The auto_shadow_state property specifies whether items should be shadowed if they cannot participate in a find. By default, this property is set to true. This means that you normally do not need to explicitly set list columns to display-only. Note that this will be used in combination with any data-dictionary No-enter assignments.
Both of the non-incremental search methods support the ability to find the main-file field based on a parent-file field. For example, in an order lookup, you might use a field named Order.Cust_Number or its parent field named Customer.Number. When faced with such a choice, you should use the parent field. When a find occurs with the parent field, the object will first find the record using the parent field's index (e.g., it finds the Customer record). It will then find the relational link between the parent and main field (e.g., it finds a relationship between Customer.Number and Order.Cust_Number). It will then find and display the appropriate records in the main file. You may even find on a parent field that does not directly relate to the main file. For example, you could find on Customer.Name. It would find the record by the customer-name index, find the relational link between the Customer and Order files (which will not be the name field), and find the records in the main file. While this capability might appear abstruse at first, it is a powerful feature.
Lists that are visually designed within DataFlex will automatically use the parent field (and not the relating-to child). This is standard behavior for all objects and has in fact been a standard requirement of DataFlex since the very beginning (always use parent.fields and not the relating child fields).
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= |
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 key values 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 >= 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 determines if 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.
A special method is provided for assigning checkboxes to data-dictionary-aware objects of this class. If the data-dictionary field is defined as a checkbox field, you may display the value as a checkbox by setting the column's column_checkbox_state to true. If the underlying field has an index associated with it, you will be able to sort and search by that column (as you would with any indexed column). Different checkbox bitmaps are displayed for enabled (indexed) and disabled (non-indexed) fields. All of this is automatic. The following example shows how this is used. Note that a width of 25 is good for checkboxes.
Object oSelList is a dbList
Set Main_File to Progrmr.File_Number
Set Size to 105 239
Set Location to 6 6
Begin_Row
Entry_Item Progrmr.Resp_programmer
Entry_Item Progrmr.Name
Entry_Item Progrmr.Knows_oop
Entry_Item Progrmr.Knows_procedrl
Entry_Item Progrmr.Knows_c
End_Row
Set Form_Width 0 to 30
Set Header_Label 0 to "ID"
Set Form_Width 1 to 124
Set Header_Label 1 to "Name"
Set Form_Width 2 to 25
Set Header_Label 2 to "OOP"
Set Form_Width 3 to 25
Set Header_Label 3 to "DF"
Set Form_Width 4 to 25
Set Header_Label 4 to "C"
// Display columns 2, 3, and 4 are checkboxes.
set Column_CheckBox_State 2 to True
set Column_CheckBox_State 3 to True
set Column_CheckBox_State 4 to True
End_Object // oSelList
If you are not using data dictionaries, you can still use checkboxes by using the entry_display method described in the DataList class. You can also use the entry_display method to display checkboxes and other types of bitmaps based on other, more-complex data conditions.
| Name | Message Sent |
|---|---|
| kbegin_of_data | beginning_of_data |
| kcancel | cancel |
| kend_of_data | end_of_data |
| kenter | find_or_ok |
| kspace | toggle_select |
element - prototype_entry
This component is forward referenced by the class and actually defined by the begin_row...end_row macros. It is used as a prototype for the items in a row of the list.