|
*PROGBAR |
Progress Bar Display |
This routine can be used to display and update a progress bar on the workstation. Two styles of progress bars are provided: one that simply shows progress advancing from left to right and resets back to the left edge when the bar maximum is reached; the other that shows the percentage complete as a portion of the bar. Use the percentage complete when the total amount of work is known in advance.
The appearance of the progress bar can also be customized either by setting the progress bar global variables or by creating a new *ext/system/_progbar program. See Customizing the Progress Bar.
(The updated appearance of the progress bar and the ability to customize the progress bar were added in PxPlus 2025.)
|
Initialization: |
CALL "*progbar;Init", title$, barsize, [ , column, row, options$, ctlno ] |
|
Advance Bar: |
CALL "*progbar;Update" [, ERR=stmtref], text$ [ , image$ ] |
|
Show % Complete: |
CALL "*progbar;Update_percent" [, ERR=stmtref], text$, percent, [ , image$ ] |
|
Wrapup: |
CALL "*progbar;Wrap_up" |
Where:
|
title$ |
Required |
Input |
This string contains the title to be displayed on the top of the progress bar window. |
|
barsize |
Required |
Input |
This numeric value contains the width of the bar to be created in columns (minimum is 15). If omitted, the minimum width will be used. |
|
column, row |
Optional |
Input |
These numeric values contain the absolute column/row number for the upper left corner where the progress bar dialog will be created. If either or both of these values are not provided (or zero), the appropriate values will be calculated to center the progress bar dialog on the current monitor. |
|
options$ |
Optional |
Input |
This field contains the options to be used in the creation of the dialogue window. Typical use would be to make the dialogue windows concurrent, thereby allowing the user to access controls on the current window. |
|
ctlno |
Optional |
Input |
This parameter can be set to override the default CTL value to be generated by the Cancel button (Default is 4). |
|
text$ |
Required |
Input |
This string contains the text to be displayed in the progress bar window. |
|
image$ |
Optional |
Input |
This string contains the optional pathname to an image that will be displayed in the top/left corner of the progress bar window. |
|
percent |
Required |
Input |
This numeric value contains the percentage of the bar to show as complete. |
|
stmtref |
Optional |
Input |
Program line number or statement label to which to transfer control. |
(The image$ parameter was added in PxPlus v11.00.)
When using the progress bar, you first call the ;Init entry point with the desired window title and width (in columns) of the bar to display.
To update the bar, call the ;Update or ;Update_percent. If the user should hit the Cancel button on the window or close the window by pressing F4 or Escape, the routine will return with an Error code #4. This error code comes from the CTL value for the button and the fact that F4 (CTL 4) is used to close most panels.
When complete, call the ;Wrap_up entry point to remove the progress bar window.
To help customize the appearance of the progress bar, global variables have been provided to control different aspects of the progress bar. These values may be set in the START_UP program or anywhere prior to initializing a progress bar.
|
Global Variable |
Description |
|
%_PROGBAR_BACK_CLR$ |
Background color of the progress bar dialog (Default is White). |
|
%_PROGBAR_BAR_CLR$ |
Color of the progress bar (Default is RGB:100 149 237, which is medium Blue). |
|
%_PROGBAR_FONT$ |
Font to use for text passed in as the _text$ parameter, as well as for text on the Cancel button (Default is Black). |
|
%_PROGBAR_PERCENT_CLR$ |
Color of percentage indication passed in as the _percent parameter shown within the progress bar when using the Update_percent method (Default is Black). |
|
%_PROGBAR_TEXT_CLR$ |
Color of text passed in as the _text$ parameter (Default is Black). |
Additional Progress Bar Customization
If additional customization of the progress bar is needed beyond what can be controlled by these global variables, then a custom progress bar program can also be created. This program must be called *ext/system/_progbar and must also share the same methods and parameters as the standard *progbar program.
If this program exists, the Init, Update, Update_percent and Wrap_up methods from the *ext/system/_progbar program will be run instead of the corresponding methods in *progbar. This will allow more aspects of the progress dialog to be customized, such as the appearance or location of the Cancel button.