Updating and Deleting Instance List Entries
A special parameter Mode(DYNAMIC) can be used on the BeginListUpdate method.
Instance list activities typically fall into two broad modes of processing:
- Search and Refresh: Typically a search button clears the instance list and then completely refills it from a user initiated search. This is called Mode(REFRESH) processing because the whole instance list is refreshed. Sometimes the list is not cleared, but progressively added to allow the end-user to easily perform "and" style searches.
- Individual Entry Updating and Deleting: Typically a command handler has performed some action that it knows should be reflected into a small number of entries already in the instance list. This is called Mode(DYNAMIC) processing because only a few entries in the instance list need to have their visual content dynamically updated or removed.
Mode(REFRESH) is the default style of list processing.
There's some differences between how Mode(REFRESH) and Mode(DYNAMIC) requests are handled by the Framework:
- When you use the default Mode(REFRESH) method, the visualization of the instance list is performed when the EndListUpdate method is executed. This is done by clearing the entire existing visualization and rebuilding it from scratch. This means selections and focus are lost and trees are collapsed, even if you replace the list with the exactly the same content.
- When you use Mode(REFRESH) you can execute a default command and set instance selections.
- When you use Mode(DYNAMIC) the visualization of the change to the instance list is performed immediately. You can't execute a default command and set or change the instance selection because all you are intending to do is change or remove its visualization, but existing selections and focus are not lost and trees are not collapsed.
- You can't use #ListManager.ClearList when using Mode(DYNAMIC) updating. This will cause an error message to be displayed.
Finally, there's two ways to update an instance list entry: You can use #ListManager.AddtoList or #ListManager.UpdateListEntryData. Both will cause an existing entry to be updated, but only AddtoList will create a new entry when the specified one does not exist.
The main difference between them is:
- UpdateListEntryData only updates the list entry values that you specify as parameters. For example you can just update additional column 3.
- AddtoList updates all the values in the instance list entry using either the values you pass as parameters or their default values. So to update additional column 3 you probably need to pass values for additional columns 1 and 2 as well, and maybe 4, 5 and 6 as well.
- The preceding points mean you should not use UpdateListEntryData in MODE(REFRESH) updates.
Warning:
- Do not attempt to update the identifying keys of an instance list entry either by using UpdateListEntryData or using RemoveFromList followed by an AddtoList. The identifying keys (Akey, NKey) should be values that are not changed by any command handlers. Use additional columns for instance list values that can be changed.
When a Relationship handler is used to dynamically expand he nodes in an instance list displayed as a tree you can use the #avListManager.RefreshRelationship method to programmatically cause a level in the tree to be completely refreshed.
For example, the shipped demonstration filter DF_FILT08 contains this logic listening for the event DEM_EMP_UPDATED ….
* If an employee update has been triggered
When (= DEM_EMP_UPDATED)
* Get the department and section this employee belonged to at the time they were added to the instance list
Invoke #avListManager.GetCurrentInstance AKey1(#Original_Deptment) AKey2(#Original_Section) AKey3(#Empno)
* Refresh the tree node that the employee was in originally (this might cause the employee to be removed from the node).
* This method causes the relationship handler function DFREL01 to be called again to refresh the whole tree node.
Invoke #avListmanager.RefreshRelationship BusinessObjectType(DEM_ORG_SEC_EMP) AKey1(#Original_Deptment) Akey2(#Original_Section)
* Now see what department and section the employee is in now. If either has changed, update the tree node for the
* the new department/section. If this node has never been expanded this request will be ignored, because the employee
* will be shown later if / when the user decides to expand this node.
Fetch Fields(#Deptment #Section) from_file(PslMst) with_key(#Empno)
If ((#Deptment *ne #Original_Deptment) or (#Section *ne #Original_Section))
Invoke #avListmanager.RefreshRelationship BusinessObjectType(DEM_ORG_SEC_EMP) AKey1(#Deptment) Akey2(#Section)
Endif