The Progress Bar namespace is a small set of stand-alone utilities to create, update and check an ‘in your face’ progress box which you should use when you have a very long-running process. Typically it might look like:

The problem here is that you cannot ‘dequeue’ the form, as you will thereby suspend your long-running process. Instead you repeatedly check the state of the cancel button and abort the process if it has been pressed since you last checked.

#.GuiPbar.Open'Preparing Sales Summary'
#.GuiPbar.Set 0 total

... where total is the number you will be counting up to. If you leave this out, the default is 100, and the progress bar will show progress as a percentage.

#.GuiPbar.Close

... will remove the progress bar. To update it you call GuiPbar.Set repeatedly with the new counter and total values.

To check if the user recently hit the Cancel button:

abort„GuiPbar.State

Setting the message format and button caption
The default format for the message text is “? of #’ where ? is used as a placeholder for the counter and # for the total. You could also have “Printing page ? of #’ or ‘Processing files, ~ remaining of #” to count down.

To set the message format, pass it as the second item of the argument to GuiPbar.Open. You can also set the caption on the ‘Cancel’ button by passing a third argument – note that you should not use the standard ‘hotkey’ technique here as it will not be effective. The user must press the button with the mouse here!

Progress box example
This is a typical example of a long-running callback which might be set as the ‘Select’ action on a button:

 PBarStart
© Run our progress bar until they stop us
 #.GuiPbar.Open'Off we go' 'Printing page ? of #' 'Abort Print!'
 :While 1000>ct„ct+1
   #.GuiPbar.Set ct 1000
  © Check every 100 - ensure the memory effect works!
   :If 0=100|ct
     :If 1=#.GuiPbar.State
       #.GuiPbar.Close
       :Return
     :End
   :End
 :End

If you call this from a causeway form, it will automatically be made as a child of the top form in the DQ. To use it stand-alone, you should pass the name of a suitable parent form as the left argument.