SECTION 2.11 - THE PROGRESS BAR VIEW-OBJECT

2.11.1 INTRODUCTION

The progress bar view-object is used to indicate the progress of a time consuming operation e.g. reading in of a large file or performing a lengthy calculation. The progress bar is a window containing a title and the bar itself. The bar starts a an empty rectangle which is gradually filled in colour (or black on a black and white display) as the operation proceeds. The program needs to be able to pass the current degree of progress to the view-object at reasonably frequent intervals for its use to be effective.

The following sets of routines are available:

Create and Handle a Progress Bar View-Object

2.11.2 CREATE AND HANDLE A PROGRESS BAR VIEW-OBJECT

2.11.2.1 Introduction

The following routines are available:

Create a progress bar view-object - xdl_progress_bar
Set the current value - xdl_progress_bar_value

2.11.2.2 Create a progress bar view-object - xdl_progress_bar

The routine xdl_progress_bar (xdlf_progress_bar) is used to create a progress bar view-object.

 
Fortran call:
 
         CALL XDLF_PROGRESS_BAR (IVH, IXROOT, IYROOT, 
        +                        XDLSTR(TITLE), ITLEN,
        +                        IND_LEN, MAX_VAL, IFONT, ICOLR)

 
Parameters:
 
IVH        (R)  View-object handle (see vh)
IXROOT     (R)  Root x position for the window (see xroot)
IYROOT     (R)  Root y position for the window (see yroot)
TITLE      (R)  Fortran character string containing the title
                ** Pass address using the XDLSTR function **
                (cf title)
ITITL      (R)  The title length (> 0) (cf title_len)
IND_LEN    (R)  Length of the 'indicator bar' in pixels 
                (see ind_len)
MAX_VAL    (R)  Maximum value indicating completion (see max_val)
IFONT      (R)  Font type 1 to 5 very-small to extra-large (see 
                font_type)
ICOLR      (R)  Colour type 1 to 6 for red, yellow, green, cyan, 
                blue, magenta (see colr)

 
'C' call:
 
void xdl_progress_bar (vh, xroot, yroot, title, title_len, ind_len, 
                       max_val, font_type, colr)

 
Parameters:
 
int vh;             /* User selected view-object handle (R)*/
int xroot;          /* x root position for top left of window (may be
                       repositioned if necessary) (R) */
int yroot;          /* y root position for top left of window (may be
                       repositioned if necessary) (R) */
char * title;       /* Title string (R)*/
int title_len;      /* The length of the title string; if the string is
                       null terminated then 0 may be given and the 
                       program will determine the string length (R)*/
int ind_len;        /* Length of the indicator bar in pixels. This will
                       start as an open bar which will be filled up as
                       values indicating progress are supplied (R)*/
int max_val;        /* The maximum value which indicates completion of the 
                       task (R)*/
int font_type;      /* Font type 1 to 5 very-small to extra-large */
int colr;           /* Colour type for filling the indicator bar (if 
                       colour available) 1 to 6 for Red, Yellow, Green, 
                       Cyan, Blue, Magenta (R)*/
/*
     Note: Calls xdl_flush_events to enable initial painting.
*/

Return:  None

2.11.2.3 Set the current value - xdl_progress_bar_value

The routine xdl_progress_bar_value (xdlf_progress_bar_value) is used to pass the value indicating the current state of progress to the progress bar view-object. It must be called at reasonably frequent intervals to be effective. Note that each call also calls xdl_flush_events which therefore need not be called during a time consuming process monitored by using the progress bar as described.

 
Fortran call:
 
         CALL XDLF_PROGRESS_BAR_VALUE (IVH, IVAL, IERR)

 
Parameters:
 
IVH    (R)   View-object handle (see vh)
IVAL   (R)   The current value (see value)
IERR   (W)   The return from the xdl_progress_bar_value call

 
'C' call:
 
int xdl_progress_bar_value (vh, value)

 
Parameters:
 
int vh;          /* View-object handle for the progress bar object (R)*/
int value;       /* The current value indicating the progress (up to the
                    max_val value passed to xdl_progress_bar) (R)*/
/*
   Note: Calls xdl_flush_events on each valid call.
*/

Return:  = 0 OK, >0 error
           bit 0 set: View-object handle not found
           bit 1 set: View handle does not match view object;

John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998