This command is used to manage the window system focus so that the user does not re-initiate an incomplete action, or initate a competing action before the current action is complete.
The verb argument is either grab, lock, release, or update. You may optionally specify a status message and window title, which the user sees in a modal popup window. The window pathname argument, win is usually a child of the current application window so the focus lock behavior locks the desired window.
Any of the verb argument values grab, lock, or update will create the modal popup window with the optional message displayed. The lock call is intended for use as a mutex. It returns 1 without changing the displayed message if the window already exists. The return value to the lock call is 0 if the focus is newly locked. The grab and update values will update a displayed message. The caller needs to supply the same value of the win argument to the release call as was used to create the modal popup window. You need to structure your application so you never fail to invoke the release action after creating the focus grab window. You may need to use catch to insure that an error does not prevent making the release call.
The command is part of the Humelib package and can be imported from the namespace humelib.
package require Humelib
package require msgcat
namespace import -force humelib::*
set cmd [list eval dc_user_group_read $group_id]
if { [dc_ui_focus lock [msgcat::mc READING_ITEM]] } return
set reply [dc_ui_hub_xact $cmd $dc_ui(dmh)]
dc_ui_focus release