Updated August 2017
A progress bar control is used to graphically indicate progress—or at least the suggestion of some activity—to the user. There are two variations. The standard version (shown below on the left) indicates the percent complete, and requires the application to make successive calls to progressively fill the bar appropriately. An alternate "Marquee" version (shown below on the right), updates itself, suggesting activity to the user without any indication of the percent complete.
|
|
In both cases, the ctype must be set to MBF_PROGRESS, and the coordinates should indicate the desired rectangle. The only parameters of interest are the ctlid (needed to reference the control for updating), ctype (must be set to MBF_PROGRESS), ctext (used to set the percentage or animation frequency), and the coordinates. And in the case of the marquee version, you must set the winstyle parameter to PBS_MARQUEE (&h0008). The parameters relating to colors, fonts, tooltips, and click events are not applicable. Additional details on each of the two versions follows.
Standard Progress Bar
Once the progress bar is created, you update the progress bar via repeated AUI_CONTROL calls using opcode = CTLOP_CHG opcode, cstate = MBST_CHANGE, and with the percentage in the ctext field. For example:
map1 percent,b,1
map1 pbid$,s,24,"prgbar1"
! create the control
percent = 0 ! starting at 0%
xcall AUI, AUI_CONTROL, CTLOP_ADD, pbid$, str(percent), MBST_ENABLE, MBF_PROGRESS, "", "", "", srow, scol, erow, ecol
! update it as we process
do while not done
<some processing>
percent = <some calculation>
xcall AUI, AUI_CONTROL, CTLOP_CHG, pbid$, str(percent), MBST_CHANGE
loop
! destroy it when done
xcall AUI, AUI_CONTROL, CTLOP_DEL, pbid$
Marquee Progress Bar
The marquee version of the progress bar does not require updating, and instead of the ctext parameter indicating the percent complete, it is used to specify the animation update frequency, in milliseconds. 0 turns off the animation. You can change the animation frequency via a CTLOP_CHG call, but typically you just set it when creating the control. For example:
map1 freq,b,2
map1 pbid$,s,24,"prgbar2"
! create the control
freq = 100 ! update marquee every 100 ms (1/10 sec)
xcall AUI, AUI_CONTROL, CTLOP_ADD, pbid$, str(freq), MBST_ENABLE, MBF_PROGRESS, "", "", "", srow, scol, erow, ecol, NUL_FGC, NUL_BGC, NUL_FONTATTR, NUL_FONTSCALE, NUL_FONTFACE$, NUL_TOOLTIP$, parentid$, PBS_MARQUEE
<some time-consuming operations here>
! destroy the control
xcall AUI, AUI_CONTROL, CTLOP_DEL, pbid$
Comments
As with any control update operation, the ctlid passed to, or returned from, the CTLOP_ADD operation (pbid$ in the above example), must be preserved for the subsequent CTLOP_CHG and CTLOP_DEL operations.
For the standard progress bar, you can set the initial percentage when creating the control to any value from 0 to 100; starting at 0 would be the most typical.
There is some overhead in updating the control, especially in the ATE environment, so you don't want to do it excessively. For example, if processing 100,000 records, it would be much more efficient to update the progress once per 1000 records—i.e., every 1%—than for every record.
The particular aesthetics and some aspects of the behavior are dependent on the Windows environment, theme, etc.
In some Windows environments, the bar is updated asynchronously via a background thread which may lag slightly behind the application. This may be more efficient for the PC, but the case of a fast-moving bar, the CTLOP_DEL operation to remove the bar may preempt the final updates, i.e. it may appear to go from 0 to 90% and then terminate without ever showing the final few percent. To eliminate this effect, you can add a small sleep—say, 0.5 seconds—prior to the CTLOP_DEL.
Often a progress bar is displayed inside of a dialog box which contains a message indicating the nature of the activity, and possibly a CANCEL button. As a convenience, there is a higher-level subroutine, PROGRS.SBX in SOSLIB:[907,21], which combines the elements text message, progress bar, optional cancel button, within a dialog box.
History
2012 August, A-Shell 1255: Marquee version implemented.
