Dialog Gauges

The dialog gauge is used to show the progress of some operation. It looks like:

Screen shot of dialog with gauge

To implement a gauge requires the use of the Asynchronous Application Manager.

Setup the dialog

Set up your dialog, with appropriate fields: use dTEXT if you want to update text messages asynchronously. For progress bars/gauges use dDONEWN%:. Other controls are possible, see the Asynchronous Dialog Controls.

... GLOBAL dlg% :REM store dialog handle ... dINIT "Test progress bar dialog" dTEXT "", "Status text", 2 dDONEWN%:( &100 ) :REM set &100 as the maximum range of the progress bar dBUTTONS "Close", -27 dlg% = PEEKW( $36 ) ret% = wsDial%: IF ret% = 0 REM dialog cancelled ENDIF ...

In this example, the progress bar is item number 3 (dINIT is number 1, dTEXT is number 2). The item number is used to identify each dialog line.

dDONEWN%: starts off with a progress value of zero. As the progress value is updated between zero and the maximum value (100 in this example), it will draw an appropriately shaded portion of the bar.

Set the progress

Assuming that you've already setup your asynchronous I/O that you're showing the progress of, inside your I/O handler you will need to add a call to sDONEWN%: to update the progress bar. In case some other windows have popped up over your progress dialog (your program is operating asynchronously, and the user may have a help window visible) the call will need make sure you pass the correct dialog handle. If you don't do this, you could be trying to set the value of a control in an incorrect dialog, and if it is the wrong dialog, your program will PANIC.

Try and use smoothly incrementing values. For example, if you're doing a file transfer, set the limit to the number of bytes in the file, and update on the number of bytes you've actually transferred.

You can set the limit when you create the dialog:

... dDONEWN%:( filesz& ) ...

Or later on in your I/O handler (you may not know the file size at dialog creation time):

... sDWMAX%:( dlg%, 3, filesz& ) :REM 3=dialog line of progress bar ...

When you have a value to update the progress bar with, use the sDONEWN%: procedure:

... sDONEWN%:( dlg%, 3, xfr& ) :REM 3=dialog line of progress bar, xfr& REM is (for this example) the number of bytes REM transferred so far (out of filesz&) ...