SeedData - cDbCJGridPromptList

Called during prompt list activation to seed and find the starting target record

Type: Function
Return Data Type: Boolean

Parameters

Parameter	Type	Description
hoUpdateColumn	Handle	The column object that is either relationally connected to the invoking object or is the column designated as the update column
hoInitialColumn	Handle	The column object that is determined by piInitialColumn

Syntax

Function SeedData Handle hoUpdateColumn Handle hoInitialColumn Returns Boolean

Call Example

Get SeedData hoUpdateColumn hoInitialColumn to BooleanVariable

Description

Normally, you want your prompt list to start at some target position. In most cases, this target is determined by the contents of the control that invoked the list. The SeedData function performs this task. The seeding process is controlled by other properties, such as peUpdateMode, pbAutoSeed, piUpdateColumn and phmPromptSeedBufferCallback. This is a complex process and should normally not be interfered with. If you do choose to augment this function, you should first carefully study the code in this class.

When a prompt list is invoked, the message SeedData is called. Depending on your update mode (peUpdateMode), the seeding process is handled different ways.

Relational Prompt Lists

If your prompt list is relational (peUpdateMode is umPromptRelational) and pbAutoSeed is True, the seeding process will consist of performing an entry-update based on the data in the invoking view. This moves the data from your invoking object's view into the table buffer. It then attempts to find the closest match to this data. This makes the seed behave in a similar fashion to a Request_Find GE, with the exception that, if the find fails, it will attempt to then find the data in opposite direction (LT).

Since most prompt lists are relational, this could be considered the normal seeding behavior.

Value Prompt Lists

If your prompt list is an update by value list (peUpdateMode is umPromptValue) and pbAutoSeed is True, the seeding process will consist of moving the invoking object's value into the table buffer and performing a find on this value. The table buffer value that is seeded and the index to be used are determined by piUpdateColumn, which you must set, usually in the invoking object's Prompt_Callback event.

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

Custom Prompt Lists

If your prompt list is a custom update list (peUpdateMode is umPromptCustom) and pbAutoSeed is True, the seeding process will consist of moving the value of psSeedValue into the table buffer and performing a find on this value. The table buffer value that is seeded and the index to be used are determined by piUpdateColumn. You must set psSeedValue and piUpdateColumn yourself, usually in the invoking object's Prompt_Callback event.

Procedure Prompt_Callback Integer hPrompt
    String sValue
    Set peUpdateMode of hPrompt to umPromptCustom
    Set piUpdateColumn of hPrompt to 1 // on name column
    Set phmPromptUpdateCallback of hPrompt to (RefProc(PromptUpdate))
    Get Value of oMyStartForm to sValue
    If (sValue="") Begin
        Move "M" to sValue // if empty jump in middle of list
    End
    Set psSeedValue of hPrompt to sValue
End_Procedure

Non Invoking Prompt Lists

If your prompt list is not called from an invoking object (peUpdateMode is umPromptNonInvoking) and pbAutoSeed is True, the seeding process will consist of moving the value of psSeedValue into the table buffer and performing a find on this value. The table buffer value that is seeded and the index to be used are determined by piUpdateColumn. You must set psSeedValue and piUpdateColumn yourself, usually before invoking the object.

// This would be added to the prompt list's panel object.
Function GetSelectedName String sSeed String ByRef sName Returns Boolean
    Boolean bCancel
    String[] SelectionValues

    Send OnStoreDefaults of oSelList

    Set peUpdateMode of oSelList to umPromptNonInvoking
    Set piUpdateColumn of oSelList to 1
    Set psSeedValue of oSelList to sSeed

    Send Popup

    Send OnRestoreDefaults of oSelList

    Get pbCanceled of oSelList to bCancel
    If not bCancel Begin
        Get SelectedColumnValues of oSelList 1 to SelectionValues
        If (SizeOfArray(SelectionValues)) Begin
            Move SelectionValues[0] to sName
            Function_Return True
        End
    End
    Function_Return False
End_Function

And it could be called from any object as follows:

Object oButton1 is a Button
    Set Location to 100 100
    Procedure OnClick
        String sName
        Boolean bCancel
        Get GetSelectedName of  Customer_sl "M" (&sName) to bCancel
        If not bCancel Begin
            Send ProcessChoice sName
        End
    End_Procedure
End_Object

Custom Seeding

You can override the seeding process by setting the callback property phmPromptSeedBufferCallback. If set, this will contain a callback event that will be sent to the invoking object and that event is then used to seed your table buffer. If you seed the buffer, that inactive seeded buffer will be used for the find. If you seed the buffer and find the record yourself, that active record will be used as your seed.

Procedure SeedBuffer Handle hoPrompt
    Get Value to Customer.Customer_Number
    Get Value of  oDivision to Customer.Division       
End_Procedure

 Procedure Prompt_Callback Integer hPrompt
      Set peUpdateMode of hPrompt to umPromptValue
      Set piUpdateColumn of hPrompt to 0
      Set phmPromptSeedBufferCallback of hPrompt to (RefProc(SeedBuffer))
End_Procedure

When phmPromptSeedBufferCallback is used, it overrides the regular seeding behavior in all modes except umPromptNonInvoking.

The default search behavior of OnSeedData only works if the data is sorted. With a typical auto-ordering cCJGridPromptList, this event will detect that the data has not yet been sorted and sort it by the "updating" column. This detection will work for most conditions.

There will be situations where the finding for a seed will require custom code. This is why this event was created. For example, if you needed to find your seed data in a list that is not and should not be sorted, you will need to augment this event to get the behavior you want. I such a case you would need to perform a find EQ search to find the seed data, which will search the list until an exact match is found.

Procedure OnSeedData
    String sValue
    Get psSeedValue to sValue
    // passing False, forces a Find EQ
    Send RequestFindColumnValue 0 sValue False 0  
End_Function

In general, the prompt lists were designed to work best with sorted data - if possible, allow the data to be sorted either automatically (pbAutoOrdering=T) or by making sure that the data is sorted manually by sending SortGridByColumn after initialzing the data.

Procedure DoFillList
    tDataSourceRow[] lsData

    Move "B" to lsData[0].sValue[0]
    Move "A" to lsData[1].sValue[0]
    Move "C" to lsData[2].sValue[0]

    Send InitializeData lsData

    // make sure it is sorted by the column used for updating.
    Send SortGridByColumn oCJGridColumn1 False
End_Procedure

Return Value

True if a seeded record is in the buffer.