| ST_PROGRESS_BAR | Type (Structure)

AMS 2.00 or higher | statline.h

typedef struct {
| WINDOW *w; /* parent window */
| WIN_RECT rect; /* scroll bar area */
| long value; /* current progress */
| long low, high; /* minimum and maximum values for progress */
| long logwidth; /* equal to high-low */
| short physwidth; /* equal to rect.x1-rect.x0+1 */
} ST_PROGRESS_BAR;

A structure describing a progress bar.

ST_PROGRESS_BAR describes a progress bar, which is used with the following functions: ST_progressBar, ST_progressDismiss, ST_progressIncrement, ST_progressUpdate.
You do not need to fill the structure by hand; this is done automatically by ST_progressBar. In addition to this, this function already draws the outline of the progress bar.
However, if you want to fill an ST_PROGRESS_BAR structure by hand, you can do it easily:

- w is a pointer to the window in which you want to display the progress bar. This window has to be initialized with WinOpen before you use it. Of course, you can use DeskTop as well.
- rect is the structure that represents the rectangle where the progress bar will be on the screen. Note that the coordinates have to be in the right order (i.e. xmin as rect.x0, xmax as rect.x1).
- value represents the current progress of the task. It must be between low and high.
- low is the minimum value for value. That is to say, if value is equal to low, the progress bar is empty.
- high is the maximum value for value. If value is equal to high the progress bar is filled completely. Of course, high must always be greater than low.
- logwidth must be equal to `high - low`.
- physwidth is the length in pixels of the progress bar on the screen. It must be equal to `rect.x1 - rect.x0 + 1`.

Beware that the functions dealing with progress bars are very slow. They take more than 20 ms, that is to say half of the time between two timer ticks. You can go up to a bit less than 1 second when a progress bar taking the full screen of the 92+ is filled. Filling the screen pixel by pixel with a double loop using logical operations with masks, or better, bit operations, is up to about 10 times faster...
So it is not a good idea to use these functions if you want to clock the process whose progress is represented by the bar. Take a look at the "Progress Bar" example for an implementation demonstrating this pitfall:

    // Progress bar example for TIGCC

    // Define this to display the progress bar in a window
    //#define USE_WINDOW_PB

    #define USE_TI89              // Compile for TI-89
    #define USE_TI92PLUS          // Compile for TI-92 Plus
    #define USE_V200              // Compile for V200

    #define MIN_AMS 200           // Compile for AMS 2.00 or higher

    #include <tigcclib.h>         // Include All Header Files

    // Main Function
    void _main(void)
    {
      short j;

    #ifdef USE_WINDOW_PB
      ST_PROGRESS_BAR spb = {NULL, {0, 0, 0, 0}, 0, 0, 100, 100, 0};
      WINDOW w;
      memcpy (&(spb.rect), ScrToWin (ScrRect), sizeof (WIN_RECT));
      spb.physwidth = spb.rect.x1 - spb.rect.x0 + 1;
      WinOpen (&w, &(spb.rect), WF_SAVE_SCR | WF_NOBORDER);
      spb.w = &w;
    #else
      ST_PROGRESS_BAR spb;
      ST_progressBar (&spb, 0, 100); // Create the progress bar in spb. low=0, high=100.
                                     // It will be created in the status line.
    #endif

      for (j = 0; j < 20; j++)
        {
          OSFreeTimer (USER_TIMER);
          OSRegisterTimer (USER_TIMER, 1);
          while (!OSTimerExpired (USER_TIMER)); // Wait a little...
          ST_progressIncrement (&spb, 1); // Increment the progress bar by 1/100.
        }
      ST_progressUpdate (&spb, 50); // Increment the progress bar up to 50/100.
      OSFreeTimer (USER_TIMER);
      OSRegisterTimer (USER_TIMER, 20);
      while (!OSTimerExpired (USER_TIMER)); // Wait for about 1 second...
      OSFreeTimer (USER_TIMER);
      ST_progressUpdate (&spb, 100); // Fill the progress bar entirely.

      GKeyIn (NULL, 0);
      ST_progressDismiss (&spb); // Remove the progress bar, redraw status line.
    #ifdef USE_WINDOW_PB
      WinClose (&w);
    #endif
    }