The Progress Bar type

Purpose

The purpose of this type is to display a progress bar, with more or less refinements. In its basic type, the progress bar will just display a bar, corresponding to the progress (as compared to 100%) made up to now. It is possible to add text inside the bar, or to have the bar also display the percentage as a text (or even to combine both).

The bar can be drawn even if control is not passed back to Prowess (e.g. within a loop).

Using the type from Basic and C

For the Basic Programmer, a file is included, called "pbar_extns". This contains all the necessary tags for the new type. This file must be loaded first with the LoadPWdefn keyword, as follows:

LoadPWdefn device_pbar_extns

Once the file is loaded in this way, the new tags are available from Basic with the PW keywords.

For the C programmer, the file 'pbar_h' contains all the necessary definitions and defines.

The Type Word

When creating this type of object, the type parameter is:

PW('TYPE_PBAR') or PW_TYPE_PBAR for C.

The tags

Here are the tags for this object.
The creation tag

There is one tag that can only be used when creating the object:

PW('PBAR_UPDOWN') - PW_PBAR_UPDOWN
Normally, the bar will fill from left to right. With this tag, which you MUST use when creating the type, you can indicate that the bar should fill from bottom to top.
The change (and creation) tags These tags can be use when creating and/or changing the type.
PW('PBAR_TEXT') - PW_PBAR_TEXT
Set the text in the bar. The parameter should be a string in Basic, and a type "char *" in C. The text should not contain a CHR$(10) or '\n'. It will be centered within the bar. If the bar is updown, then the text is displayed from top to bottom. Please note that the bar will attempt to resize itself if the text is too large to fit in the window - but only if control is passed to Prowess before the bar is drawn.
PW('PBAR_TOTAL') - PW_PBAR_TOTAL
Set the total, in user units. This would correspond to 100% of the bar. The parameter is a number, or a type "int". For example, if you where to read a file byte by byte and the filelength would be 3659 bytes, then you could set the total to 3659. After each byte read, you could then call the Progress Bar with the tag below, to show the progress.
PW('PBAR_PROGRESS') - PW_PBAR_PROGRESS
Set the progress, in user units, up to now. This will cause the bar to redraw itself, with the new percentage. The bar calculates how much the progress is in percent and then displays that. The parameter is a number(Basic), or a type "int" (C). The bar never displays negative percentages or percentages higher than 100%. In the above example, you would pass the number of bytes read. Please note that the granularity of the Progress bar is one percent.
PW('PBAR_PROGRESS_PERCENT') - PW_PBAR_PROGRESS_PERCENT
Set the progress, in percent. If you already happen to have the progress expresed as a percentage, this is marginally faster than the above alternative, The parameter is a number, or a type "int".
PW('PBAR_SHOW_PERCENT') - PW_PBAR_SHOW_PERCENT
Instead of a user defined string, the bar can also automatically display the percentage as a string (e.g. 20%, 100% etc). The parameter for this tag is either TRUE or FALSE. If TRUE, the percentage will be shown as a string inside the bar. If you also set a string, then both will be shown.
PW('PBAR_PERCENT_LAST') - PW_PBAR_PERCENT_LAST
By default, when the bar has been set up to show a text as well as the percentage, the percentage precedes the string. If the parameter for this tag is set to TRUE, then the percentage is shown after the string. If you use both a percentage and a string, you should include a space at the appropriate end of the string.
The query tags There are no query tags for this object.

The Definitions

PBAR-INK-COLOUR
The RGB Colour which has to be used to display the text. The ProWesS foreground colour will be used as default when not defined.
PBAR-BAR-COLOUR
The RGB Colour which has to be used to display the bar. The ProWesS middleground colour will be used as default when not defined.
PBAR-PAPER-COLOUR
The RGB Colour which is used as background for the bar. The ProWesS background colour will be used as default when not defined.
PBAR-FONT
Set the font to display the text and/or percentage. The ProWesS default font will be used when not defined.
PBAR-FONTSIZE
Set the fontsize to display any text. The ProWesS default fontsize will be used when not defined.

Wolfgang LENERZ 6, rue Daunou 77340 PONTAULT-COMBAULT FRANCE
last edited 1997 Jul 01