Class: dbList [Obsolete]

Properties • Events • Methods • Index of Classes

Enables users to select one or more values from a list of choices.

Hierarchy

• cObject
• cUIObject
  • DfBaseObject
  • DfBaseWindow
    • DfBaseUIWindow
    • DfBaseControl
      • DfBaseList
      • DfBaseForm
        • DfBaseEntry
        • DfBaseEntryList
          • EntryList
          • WideList_
            • WideList
            • DataList_
              • DataList
              • dbList_
                • dbListDS
                • dbList

Library

Windows Application Class Library

Package

Dfsellst.pkg

Mixins

Extended_DEO_Mixin

Description

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.

Sample

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

Syntax

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

Of Special Note

This class specifies a single- or multi-select list of choices from one or more database files. 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 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 selection-list needs. There are properties and message handlers for greater control; usually they are not required, but they can be used to refine behavior.

Using with a Data Dictionary

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.

The auto_label_state property specifies whether a list's header labels should be assigned explicitly with the Set Header_Label message or assigned from the data dictionary.

Selection List vs. Display List

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 behaviors required to support lookups are supported by a default dbList.

A dbList may also be used for non-lookup purposes, more like a dbGrid except that it does not support data entry into the cells. When used this way, disable startup behaviors (seed the list, find the right column) and shut-down behaviors (move the selected value to the invoking object) by setting the property move_value_out_state to false. When used in this fashion, it is important to set this property false; failing to do so can generate runtime errors.

Exporting the Selected Value

When used as a lookup list (move_value_out_state is true), the object must update the invoking object with a selected record or value ("export"). There are two types of export behaviors: relational and non-relational.

• Relational lookup: the list's main file is the same as the main file of the invoking object. The selected record must be returned to the invoking object's data-dictionary object so related parent/child records are found and view objects are updated.
• Non-relational lookup: the main file of the list and the invoking object are different. The list returns the selected item to the invoking object (no record finding in the view).

The object auto-detects relational vs. non-relational lookup and updates the invoking object accordingly. You may override this behavior by setting auto_export_state to false and then using export_item_state: set it to false to force a relational update, or true to force a non-relational update.

Main File, Server DSO, and Index

A main file must be specified either with an explicit Main_File declaration or by relying on the main_file of DSOname through the Server property. An index must be named unless one is named in DSOname or Auto_Index_State is used (recommended). 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, records are listed in recnum order.

To respect the finding constraints of the invoking view, set this object's auto_server_state to true. When true, the object latches onto the invoking view's data-server structure on activation and disconnects on deactivation.

Searching for Records in a List

If users need to jump to a row in a sorted column, they may start typing the target value. This pops up a search window; type the value and press Enter (or OK) to refresh the list around that item. This behavior is supported when popup_search_state is true and find_search_state is false (the default).

Other search options:

• If popup_search_state is false and find_search_state is false, the list supports an "in-place" incremental search (refreshes on each keypress). This can be inefficient for large databases and doesn't work well with numbers or dates.
• If popup_search_state is false and find_search_state is true, the list supports an "in-place" non-incremental search (works like popup search but without a visible search window).

The auto_shadow_state property specifies whether items should be shadowed if they cannot participate in a find. By default this is true. This often obviates the need to explicitly set list columns to display-only. Note this interacts with any data-dictionary No-enter assignments.

Searching with Parent File and Fields

Both non-incremental search methods support finding on a parent-file field. For example, an order lookup may search Order.Cust_Number or its parent Customer.Number — prefer the parent field. When finding on the parent field, the object first finds the parent record using the parent's index, identifies the relational link between parent and main fields (e.g., Customer.Number → Order.Cust_Number), then finds and displays the appropriate main-file records. You can even find on a parent field that does not directly relate to the main file (e.g., find on Customer.Name), and the object will resolve the relationship and display the correct main-file records.

Lists visually designed within DataFlex will automatically use the parent field instead of the relating child field. This has been standard behavior in DataFlex since its inception.

Setting Entry Parameters for Columns

Older revisions allowed column parameters using entry_item options inside braces (e.g., entry_item file.field {capslock, iPrompt =(myObj(Self)), iEntry =msg_MyMessage}). Data dictionaries now replace most of these settings and the Studio does not support command-line options on entry_item.

For rare cases where you need to set options per column inside row-based data-entry classes, a parallel set of messages exists (documented in the DataList class). These messages support get and set syntax for column-specific parameters.

Item and Row Color and Grid Lines

• Current row and current cell colors are set with CurrentCellColor and CurrentRowColor. These are RGB colors and by default are read from registry values to allow customization without recompilation.
• The ItemColor message lets you manage the background color of any cell(s) in a grid. When used inside Entry_Display, you can color items based on field values. Entry_Display is called every time a row is updated from the database.
• The background color precedence:
• CurrentCellColor overrides all other colors.
• CurrentRowColor (if highlight_row_state is true) overrides non-current row color.
• Non-current row uses ItemColor.

If you want to use ItemColor for custom row colors, set highlight_row_state to false.

Example (add to a dbGrid or dbList):

// 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 determines whether horizontal and vertical lines appear in the list. A registry setting (TableGrid) can also set this, using values 0–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.

The reason dbGrids and dbLists have unique registry settings for colors is to allow distinction between selection lists (dbLists) and entry tables (dbGrids). dbGrid uses the standard grid and color provided with the Grid class.

Placing Checkboxes in dbList Cells

If the data-dictionary field is defined as a checkbox field, display it as a checkbox by setting the column's column_checkbox_state to true. If the underlying field has an index, you can sort and search by that column. Different checkbox bitmaps are displayed for enabled (indexed) and disabled (non-indexed) fields automatically. A width of 25 is recommended for checkbox columns.

Example:

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 not using data dictionaries, you can still display checkboxes using Entry_Display (see the DataList class). Entry_Display can also display checkboxes and other bitmaps based on complex conditions.

Accelerator Keys

(Reserved — no specific accelerators documented in this file.)

Child Objects

• 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.