Class: DataList [Abstract]

cObject
---cUIObject
------DfBaseObject
---------DfBaseWindow
------------DfBaseUIWindow
---------------DfBaseControl
------------------DfBaseList
---------------------DfBaseForm
------------------------DfBaseEntry
---------------------------DfBaseEntryList
------------------------------EntryList
---------------------------------WideList_
------------------------------------WideList
---------------------------------------DataList_
------------------------------------------DataList
---------------------------------------------dbGrid_
---------------------------------------------dbList_

This class is obsolete. It's subclasses dbList and dbGrid have been replaced with the cDbCJGrid class.



DataList implements the behavior common to virtual scrolling lists, including dbList and dbGrid. DataList provides an interface to a DSO to support virtual list viewing.

Of Special Note

DataList defines the properties, procedures, and functions necessary to interface a virtual scrolling list with a DSO. The behavior of DataList is inherited by the dbList and dbGrid classes.

Customizing Cell Values with Entry_Display

Normally the contents of a cell is determined by the parameter defined in the entry_item command. This parameter is usually a data field value (entry_item customer.cust_name) or an expression ( entry_item (Customer.Balance/100) ). The values of row are updated by the Entry_Display message. This message is a good augmentation point and can be used to customize display output. When this procedure is called the proper record data is in the file buffers. When using this data you want to use the data from the file buffers and not from the data-dictionary buffers (the data-dictionary buffer only contains the refreshed data for the single selected row and not for the data for every row in the table).

You can use this procedure the value of cell and to change other attributes (fonts, colors, etc.). For example, in a dbList you may wish to display the values "Yes" and "No". In the following example, assume that column 0 is customer name, column 1 is customer name and column 2 shows if the customer's credit limit is exceeded. Your row structure would look like the following:

Begin_Row
    Entry_Item Customer.number
    Entry_Item Customer.Cust_Name
    Entry_Item ("") // we will fill this in Entry_Display
End_Row

Entry_display will be used as follows. Note that we must set values relative to column zero of the current row. This offset is determined by getting the Base_Item property.

Procedure Entry_Display integer i1 integer i2
    Integer iBase
    Boolean bIsOver
    Forward Send Entry_Display i1 i2 // normal display
    Move (Customer.Balance>Customer.Credit_Limit) to bIsOver 
    Get Base_Item to iBase  // Item value of first column
    // we will use the if function to select a text value
    Set Value (iBase+2) to (If(bIsOver, "Yes", "No"))
End_Procedure

Placing Bitmaps in Grid Cells

You can place bitmaps in individual cells of DbLists and dbGrids by setting the form_bitmap property. Normally this property will be set within the Entry_Display procedure. The named bitmap will be displayed within the cell along with whatever data (the item's value) may be set. Normally, a cell should contain data or a bitmap, but not both. If you are placing a bitmap in a cell, you will probably want to clear the cell's data contents by assigning its entry_item to a blank string (e.g. entry_item ("") ).

When setting form_bitmaps within Entry_Display, the program must set the item number by finding the item number of the first column and then adding the column offset. The following example adds a bitmap to a dbList based on the value of data field.

Object oSelList is a dbList
    Set Main_File to Salesp.File_Number
    Set Ordering to 1
    Set Size to 71 251
    Set Location to 6 6
 
    Begin_Row
        Entry_Item Salesp.Id
        Entry_Item Salesp.Name
        Entry_Item ("") // we will place our bitmap here
    End_Row
 
    Set Form_Width    0 to 40
    Set Header_Label  0 to "Id"
        
    Set Form_Width    1 to 175
    Set Header_Label  1 to "Name"
 
    Set Form_Width 2 to 25
    Set Header_Label to "Region"            
 
    // display a bitmap for each of the four regions in the company.
    Procedure Entry_Display integer i1 integer i2
        integer iBase // Item value of first column
        Forward send Entry_Display i1 i2 // normal display
        Get Base_Item to iBase
        If (Salep.Region = "A") Set Form_BitMap (iBase +2) to "RegionA.bmp"
        Else If (Salep.Region = "B") Set Form_BitMap (iBase +2) to "RegionB.bmp"
        Else If (Salep.Region = "C") Set Form_BitMap (iBase +2) to "RegionC.bmp"
        Else Set Form_BitMap (iBase +2) to "RegionD.bmp"
    End_Procedure
          
End_Object    // oSelList

It is up to you to provide appropriately designed and sized bitmaps. A good starting size is a width of 26 pixels and a height of 16 pixels.

Checkboxes are often represented with checkboxes and four bitmaps are provided in DF's bitmap area that may be used for display or as a starting point for your customizations. These are bitmaps that represent four states of a checkbox used by dbLists:


1. Checked / Enabled (ChkOnE.bmp)

2. Not checked / Enabled (ChkOffE.bmp)

3. Checked / Disabled (ChkOnD.bmp)

4. Not checked / Disabled (ChkOffD.bmp)


These bitmaps may be used in a fashion similar to the above example. A special message, OnDisplayCheckBox, is provided that automatically displays the appropriate checkbox bitmap. You send this message an item number and a state and the procedure will display the appropriate bitmap based on the passed information and the item_shadow_state of the passed item. The following two samples would accomplish the same thing:

// display a check if Customer.Balance exceeds Customer.Credit_Limit.
// assume column 0 is customer number, column 1 is name, and
// column 2 is the credit exceeded checkbox
Procedure Entry_Display integer i1 integer i2
    Integer iBase
    Boolean bIsOver
    Forward send Entry_Display i1 i2 // normal display
    Move (Customer.Balance >Customer.Credit_Limit) to bIsOver 
    Get Base_Item to iBase  // Item value of first column
    // we will use the if function to select a bitmap 
    Set Form_Bitmap (iBase +2) to (If(bIsOver, "ChkOnD.Bmp", "ChkOffD.Bmp"))
End_Procedure
 
Procedure Entry_Display integer i1 integer i2
    Integer iBase
    Boolean bIsOver
    Forward send Entry_Display i1 i2 // normal display
    Move (Customer.Balance >Customer.Credit_Limit) to bIsOver 
    Get Base_Item to iBase  // Item value of first column
    Send DoDisplayCheckBox (iBase +2) bIsOver
End_Procedure

Using Checkboxes in dbGrids and dbLists

If your data dictionary defines a field as a checkbox field, you may display these as checkboxes in dbGrids and dbLists by setting the column's column_checkbox_state to true. The dbGrid and dbList class automatically create and support checkboxes. The method of display and interaction is distinctive to each class. The dbGrid displays a standard checkbox that may be used for editing and saving data. The dbList uses bitmaps to represent checkboxes that may be used for display and searching. Refer to the appropriate class for more information.

Child Objects

element - prototype_entry - user

This child is forward referenced by this object, and actually created by the begin_row/end_row commands. It serves as the prototype for all rows in the list.

records - array - self

This child holds the record numbers in the main file corresponding to the rows of the currently displayed page of items.