PROGRESS bar

A progress bar is intended to provide feedback to the user as to how far along some time-consuming operation has progressed. The user does not operate the progress bar. It is merely for visual feedback. A progress bar is divided up into a number of "blocks" or steps. Each step can be highlighted in turn, with the intent being that, when all steps are finally highlighted, the operation is complete.


Styles

A PROGRESS bar must be created with one of the following 2 styles for its Orientation:

Horizontal Orients the bar horizontally.
Vertical Orients the bar vertically.

In addition to the above, the progress bar may have any, all, or none of the following styles:

Smooth The progress bar scrolls smoothly.
No Sibling (NOSIBLING) Prevents this control from drawing into any overlapping controls.
Group Marks this control as the first of a group of controls in which the user can move from one control to the next with the arrow keys. All subsequent controls (after this first control) belong to the same group up to the next control that has its GROUP flag set. (ie, One group ends where the next begins).
Tabstop The user can move to this control using the TAB key.
Disabled Control is initially disabled. You can later enable it with a call to GuiSetCtlPlacement.
Hide Control is hidden. You can later make it visible with a call to GuiSetCtlPlacement.
Border Has a border.


Extra styles

A PROGRESS bar can have the following extra styles:

Quiet Do not report any events for this control.
Modal Frame (MODALFRAME) Has a double border.
Static Edge (STATICEDGE) Has a three-dimensional border intended to be used for windows that do not accept user input.
Client Edge (CLIENTEDGE) Has a 3D look comprised of a border with a sunken edge.
Accept files (FILES) Accepts drag-and-drop files (ie, the WM_DROPFILES event).
Transparent The control is to be transparent. Any controls that are beneath this one are not obscured.


Events

A PROGRESS bar generates no events.


REXX Variable

A PROGRESS must have a REXX variable associated with it. You do not need to initialize the variable before opening the window.


Dynamically add/remove a PROGRESS bar

You can dynamically add a PROGRESS bar to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:

PROGRESS X, Y, Width, Height, Styles, ExtraStyles, VariableName
X and Y is the position of the top left corner of the control, relative to the window's top left corner.

Width and Height are the size of the control, in DLUs.

Styles and ExtraStyles are those listed above, with each style separated by a | character.

VariableName is the variable name to be associated with the control.

For example, here we add a PROGRESS bar at an X Y position of 10, 10, with a width and height of 80 and 20, with extra styles of CLIENTEDGE and QUIET, and a REXX Variable name of MyProgress.

error = GuiAddCtl("PROGRESS 10,10,80,20, , CLIENTEDGE|QUIET, MyProgress")
You can dynamically remove a PROGRESS bar by calling GuiRemoveCtl. Here we remove the above bar:
error = GuiRemoveCtl("MyProgress")

Step (increment) the position

You can cause the PROGRESS bar to advance to (ie, highlight) its next step(s) by sending it a STEPIT message. Each time you send a STEPIT message, the PROGRESS bar increments to the next step(s). Here we increment the above PROGRESS bar twice:

error = GuiSendMsg("MyProgress", "STEPIT")
error = GuiSendMsg("MyProgress", "STEPIT")


Set the range

The steps in the progress bar have a range. By default this range is 0 (for the leftmost step) to 100 (for the rightmost step). But, you can alter this range by sending a SETRANGE32 message. For the third arg, pass the desired value for the lowest step (usually 0). For the fourth arg, pass the desired value for the highest step. Here we set the low step to 0 and the high step to 19. (Omitting a value is the same as passing 0).

error = GuiSendMsg("MyProgress", "SETRANGE32", , 19)


Set the step increment amount

You can set how much the PROGRESS bar increments each time it receives a STEPIT message. You do this by sending a SETSTEP message. Here we set it to increment by 1 for each STEPIT message:

error = GuiSendMsg("MyProgress", "SETSTEP", 1)
Note: By default, the step increment is set to 10.

If we also set the range to "0 to 19", then our progress bar will have 19 steps (ie, passing it 19 STEPIT messages will completely fill the bar).


Set the current position

You can set the PROGRESS bar to a particular position by sending it a SETPOS message. You also pass a number indicating the desired position. Here we set it to a position of 5:

error = GuiSendMsg("MyProgress", "SETPOS", 5)

In lieu of the STEPIT message, you can increment the position (from its current position) by sending a DELTAPOS message. You also pass a number indicating the amount to advance the position. Here we advance the current position by 5:

error = GuiSendMsg("MyProgress", "DELTAPOS", 5)

Query the current position

You can query a PROGRESS bar's position by sending it a "GETPOS" message. This causes the variable GuiSignal to be set to the current position. For example, here we query the above bar:

error = GuiSendMsg("MySlider")
IF error == "" THEN SAY "Position:" GuiSignal

Change colors

You can set the background color by sending a "SETBKCOLOR" message. For the fourth arg, pass the desired RGB color number. (The third arg is omitted). Pass a 0 to restore the default color.

You can set the bar color by sending a "SETBARCOLOR" message. For the fourth arg, pass the desired RGB color number. Pass a 0 to restore the default color.


Marquee mode

A PROGRESS bar offers "marquee mode". When marquee mode is enabled, if you haven't advanced the bar for a certain amount of time, Windows automatically animates the bar just to let the user know that your script hasn't locked up.

You can enable marquee mode by sending a "SETMARQUEE" message. For the third arg, pass a 1 to enable marquee mode, or 0 to disable. If enabling marquee mode, for the fourth arg, pass the amount of milliseconds you desire Windows to wait for you to advance the bar before the marquee effect happens.