Skip to content

Class: cDbCJGridPromptList

Properties | Events | Methods | Index of Classes

Used to provide Prompt Lookup Lists for your DataDictionary tables.

Hierarchy

Library: Windows Application Class Library

Package: cDbCJGridPromptList.pkg

Description

The cDbCJGridPromptList is the grid component to be used when creating lookup lists. Normally, a lookup list will consist of a modal panel parent (dbModalPanel), a child DataDictionary server object (DDO), a child prompt list grid (cDbCJGridPromptList), and some child buttons. When Popup is sent to the modal panel, the child prompt list grid is populated, a selection is made, and the invoking view is updated with the choice.

The cDbCJGridPromptList class extends the cDbCJGrid class. It uses the cDbCJGridColumn class for its column objects and uses an internally created cDbCJGridDataSource class for its datasource object, which is created automatically.

The following provides an overview of the cDbCJGridPromptList class. You should refer to Using Grids for a complete overview of the grid classes. The Class Reference will provide you with syntactical and usage information about the grid classes.

The cCJGridPromptList class is a non-data-aware version of this class.

Using Prompt Lists

Below is a typical lookup list. You can create the object automatically by using the Studio's "Lookup Wizard" (File > New > Dialog/Lookup). This creates the lookup list and assigns it to the appropriate fields in your DataDictionary class by setting the Field_Prompt_Object property.

Object Customer_sl is a dbModalPanel
    Set Border_Style to Border_Thick
    Set Minimize_Icon to False
    Set Label to "Customer List"
    Set Size to 134 238
    Set Location to 4 5
    Set piMinSize to 97 174

    Object Customer_DD is a Customer_DataDictionary
    End_Object 

    Set Main_DD to Customer_DD
    Set Server to Customer_DD

    Object oSelList is a cDbCJGridPromptList
        Set Size to 106 227
        Set Location to 6 6
        Set peAnchors to anAll

        Object oCustomerNumber is a cDbCJGridColumn
            Entry_Item Customer.Customer_Number
            Set psCaption to "Number"
            Set piWidth to 50
        End_Object

        Object oCustomerName is a cDbCJGridColumn
            Entry_Item Customer.Name
            Set psCaption to "Customer Name"
            Set piWidth to 100
        End_Object

    End_Object

    Object oOK_bn is a Button
        Set Label to "&Ok"
        Set Location to 116 77
        Set peAnchors to anBottomRight
        Procedure OnClick
            Send OK To oSelList
        End_Procedure
    End_Object    // oOK_bn

    Object oCancel_bn is a Button
        Set Label to "&Cancel"
        Set Location to 116 130
        Set peAnchors to anBottomRight
        Procedure OnClick
            Send Cancel To oSelList
        End_Procedure
    End_Object    // oCancel_bn

    Object oSearch_bn is a Button
        Set Label to "&Search..."
        Set Location to 116 183
        Set peAnchors to anBottomRight
        Procedure OnClick
            Send Search To oSelList
        End_Procedure
    End_Object    // oSearch_bn

    On_Key Key_Alt+Key_O Send KeyAction To oOk_bn
    On_Key Key_Alt+Key_C Send KeyAction To oCancel_bn
    On_Key Key_Alt+Key_S Send KeyAction to oSearch_bn
End_Object

Most of the lookup list work is performed by the prompt list object.

Modes of Operation

The above example uses the prompt list in its most commonly used mode. The prompt list is invoked by a data entry object (DEO) that uses the same table as the prompt list. An item is selected, and the invoking object's DataDictionary is updated. This is a relational update.

The prompt list can be used in other non-relational modes. It can be used to update just the value of the invoking object (a value update). It may be used in a custom fashion where the invoking object determines what is updated (a custom update). It can also be used without any invoking object at all (a non-invoking update).

This is controlled by the peUpdateMode property.

  • umPromptRelational, the default, is used for relational updates.
  • umPromptValue is used for automatic non-relational updates.

Some of the update modes (umPromptCustom or umPromptNonInvoking) require that you process your selections manually. The pbCanceled property and the SelectRowValues and SelectedRowIds methods are used for this purpose.

Prompt List Properties

By default:

  • A prompt object is relational (peUpdateMode is umPromptRelational).
  • The prompt object uses information from the invoking object to determine which column to start in, how to seed the list, and which index order to use.
  • The prompt object uses its own DataDictionary server.
  • Clicking on an indexable column header changes index ordering. Clicking a second time reverses the order.
  • Switching columns will change the index ordering.
  • Non-indexed columns are non-focusable.
  • You can search for a value in the indexed column via a search dialog. If you start typing, the search dialog is invoked.

These behaviors can all be changed. Some of the important properties are:

  • pbAutoSeed - Determines if the list should be seeded from the invoking object.
  • pbAutoServer - Determines if the list should attempt to use the invoking DEO's DataDictionary server object. This lets you acquire and use the constraints of the invoking view.
  • pbAutoColumn - Determines if the list should attempt to use the best column based on the invoking object as its choice for initial column and initial index ordering.
  • pbAutoOrdering - Determines if the list automatically changes ordering upon a column change.
  • pbAutoSearch - Determines if a search window appears when you start typing, allowing you to search for data within the list.
  • pbAutoEnableColumns - Determines if non-indexed columns can be enabled.

Callbacks

When used with an invoking object, a callback message, Prompt_Callback, is sent to the invoking object. This lets you customize peUpdateMode and the other prompt list properties. This callback is surrounded by events, which store and restore the prompt list's default settings (StoreDefaults / RestoreDefaults). This makes it easy for the invoking object to customize instances of prompt list usage without worrying about messing up the defaults. When it is closed, the list is restored back to its original default state. This makes it possible to use the same prompt list in a variety of places within your application.

Object oStartCustNumber is a Form
    Set Label to "Customer Number:"
    Set Size to 13 85
    Set Location to 10 92
    Set Form_DataType to 0
    Set Prompt_Button_Mode to pb_PromptOn

    // The following code connects the customer selection list to this form  
    Set Prompt_Object to Customer_sl

    // This forces a simple value update for column 0
    Procedure Prompt_Callback Integer hPrompt
          Set peUpdateMode of hPrompt to umPromptValue
          Set piUpdateColumn of hPrompt to 0
    End_Procedure

End_Object

Static and Non-static cDbCJGridPromptLists

Normally, cDbCJGridPromptList and cDbCJGrid objects use a cached data source where only a section of the data is loaded at a single time. As you navigate through the grid, data rows are loaded, added to the cache, and removed from the cache automatically as needed. When you change ordering by clicking on a header column, the datasource is refreshed around the table index that is best for that column. If you search for a new value, the datasource is refreshed around that target. This is usually the desired behavior because it ensures that your prompt lists load quickly but still support flexible searching and ordering.

If you wish, you can make your cDbCJGridPromptList static by setting the pbStaticData property to true. When you do this, all of the data is loaded once when the list is activated. When used in this fashion, you can reorder your list based on any column because the datasource is now sorted and not refreshed by a back-end index find. This type of static list may be a good choice when the number of rows is small enough so that they load and sort quickly.

Multi Select Lists

Static prompt lists support multi-selection. To do this, you must set peUpdateMode to an appropriate mode for multi-select (umPromptCustom or umPromptNonInvoking) and you must set pbMultipleSelection to true. After you have made your selections, you can then use the SelectedColumnValues or SelectedRowIds methods to return an array of selected data.

All data must be loaded to use multi-select lists; therefore, you should not use multi-select with dynamic lists.

cDbCJGridPromptList versus Read Only cDbCJGrid Objects

cDbCJGridPromptList objects are meant to be used for lookups (modal popup objects that return a value). If you need to use data-aware grids for non-modal, non-prompt conditions, don't use the cDbCJGridPromptList class; use the cDbCJGrid class and make it read-only. You can do this by setting the pbReadOnly property to True. You may wish to change other properties such as pbFocusSubItems (to False), pbSelectionEnable (to True). You can also set pbPromptListBehavior to True, which disables some of the column change events (entering, exiting, validating) and other events (Prompt_Object, navigation, autofind) that you don't want with read-only grids.

Non-data-aware Prompt Lists

If you need to create a non-data aware prompt list, you should start with the cCJGrid class and build up from there. This will probably be easier than trying to "dumb down" a cDbCJGridPromptList. In such a case, you may wish to study the code in the cDbCJGridPromptList to see how it extends the cDbCJGrid to support prompts.