Updated August 2012; see History

A progress bar (MBF_PROGRESS) is similar to a hollow static rectangle which you can progressively fill during the course of an operation to give a visual indication of the percentage of the job completed.

The control is similar to a static text control, except that you must specify the MBF_PROGRESS flag instead of MBF_STATIC, and currently the colors are ignored.

You must retain the ctlid returned when creating the control so that it can subsequently be updated. For example:

MAP1 CTEXT,S,5,"0"       ! % completed

xcall AUI, AUI_CONTROL, CTLOP_INFO, prgbid, ctext, MBST_ENABLE, MBF_PROGRESS, "", "", status, srow, scol, erow, ecol

Initially the progress bar will be empty. To update it, you can use opcode 2 (change), specifying the ctlid (PRGBID in the above example) returned from the create operation, placing a string representation of the percent completed in the ctext parameter, and specifying the MBST_CHANGE flag in the cstate parameter, e.g.:

CTEXT = str(PERCENT) ! percentage complete (round to integer)

xcall AUI, AUI_CONTROL, CTLOP_CHG, prgbid, str(pct), MBST_CHANGE

The above call would move the progress bar over to the position representing whatever percentage is in the variable PERCENT. Note that we omitted unnecessary parameters, which not only saves typing but in the case of ATE would eliminate the need for it to return the status parameter to us, cutting down on network traffic. (In any case you probably do not want to update the progress bar more often than necessary to convey the sense of action. For example, in a report of 100,000 records, it probably would not make that much sense to update the progress bar for every single record.)

Often a progress bar is displayed inside of a dialog box which contains a message indicating the nature of the activity, an possibly a CANCEL button. As a convenience, we provide a higher-level subroutine, PROGRS.SBX, which combines these elements (text message, progress bar, optional cancel button, within a dialog box).

History

2012 August, A-Shell 1255:  the progress bar control (MBF_PROGRESS) can now be given the "marquee" style by setting the winstyle parameter to PBS_MARQUEE (&h0008). This version of the progress bar is used to indicate activity without indicating a percentage complete. As with the normal progress bar, you use the ctext parameter (either in the CTLOP_ADD or CTLOP_CHG operation) to adjust the animation, except that instead of being interpreted as the percent complete, it is interpreted as the refresh rate of the animation, in milliseconds. Setting ctext to "" or "0" turns off the animation, leaving an empty progress bar.