cObject
---cUIObject
------DfComUIObject
---------DfInPlaceComObject
------------DfComActiveXControl
---------------cComActiveXControl
------------------cCJGridControl
---------------------cCJGrid
------------------------cDbCJGrid
---------------------------cDbCJGridPromptList
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.
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 it assigns this to the appropropriate 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.
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). In 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.
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 be enabled
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
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 prompts 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.
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 and, therefore, you should not use multi-select with dynamic lists.
cDbCJGridPromptList objects are meant to 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.
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 extends the cDbCJGrid to supporting prompts.