# Progress Bar Control

_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.

| | |
|------|------|
| _(./images/ashref_img131.png)_ | _(./images/ashref_img132.png)_ |


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](https://bitbucket.org/microsabio/soslib/src/master/907021/progrs.bas) 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.