CHAPTER 1 - USING XDL_VIEW IN APPLICATION SOFTWARE

1.1 INTRODUCTION

The XDL_VIEW software falls into two main categories:

1. A set of routines for managing a set of view-objects.

2. The software for the individual view-objects, some of which are of general use (menu area, parameter table etc.) and some of which are more application specific (e.g. the film image view-object).

The management software is required partly for convenience and partly as a consequence of requiring a Fortran interface to the view-object routines. The XLIB library routines interface provided is C based and makes extensive use of structures, and a variety of data types which do not map naturally on to Fortran 77. Because of the Fortran requirement, it was decided that the view-objects should be identified indirectly through a 'view-object handle' which is a unique integer, selected by the application programmer, for each view-object created within an application. (cf Fortran file logical unit numbers). One of the main functions of the management routines is to maintain a table relating the view-object handles to the actual view-objects and their associated data. The management routines also provide an initialisation routine and a routine for polling for input to the application from selected view-objects.

List of sections:

The Basic Structure of an Applications Program
Laying Out View-Objects
Application Program Example
Some Other Considerations

1.2 THE BASIC STRUCTURE OF AN APPLICATIONS PROGRAM

The basic structure for a program using XDL_VIEW view-objects is as follows:

1. Call the XDL_VIEW initialisation routine. This must be called and must be the first call to an XDL_VIEW routine.

   (xdl_open_view for C or xdlf_open_view for Fortran)

2. Create view-objects using calls to the appropriate routines

   (e.g. xdl_menu_area (xdlf_menu_area) for a menu area etc.)

3. Set up a list of the view-object handles for the view-objects from which the program is prepared to accept input.

4. Poll for input from the listed view-objects

   (call xdl_get_events in C or xdlf_get_events in Fortran)

5. Service the returned input.

   The polling routine returns the view-object handle of the view-object for which the input was made. Specific routines are then called to access the input data (e.g. xdl_menu_area_getitem (xdlf_menu_area_getitem) to determine the item selected from a menu) and the approriate action is taken by the program.

The procedure then followed will depend on the nature of the program. For example the program may return to step 4 to repeat the polling from the same view-objects or go back to step 3 to change the list of view-objects from which input can be accepted before next polling for input. Alternatively, when required, the user may create new view-objects (and/or delete unwanted ones) and then have a new polling loop. A program will normally have at least one polling loop and more complex programs will often have several.

The way in which colour is handled by the XDL_VIEW routines also needs some explanation. The routines were developed initially for workstations which have 8 bit pseudocolor available. Because of the nature of the handling of colour in X-windows, it was decided that an application should specify its colour requirements at the start. This is particularly important if a large number of colorcells or colorcells with overlay planes are required. It enables the allocation of read-write cells in the default colormap if available or the allocation of a new virtual colormap if required. The allocation of the colour requirements at the start means that the individual view-object routines need not be concerned about the colorcell availablity at the time that they are actually invoked thus simplifying one aspect of their coding. It also means that, provided no more than 256 colorcells are used, a single colormap will be used for the whole application. The application's colour requirements are specified when the XDL_VIEW intitialisation routine is called. The routines should however be able to run on other colour displays (in particular true or direct colour displays) and should provide some sort of monochrome option.

The handling of the Fortran/C interface, which may be of interest to some application programmers, is described in chapter 2.

1.3 LAYING OUT VIEW-OBJECTS

The xdl_view view-objects have routines which will return the required size of the window given the various program specific parameters which affect it. Given these values, it is possible to work out a layout manually or write a routine to work out a layout for a particular program. For even a moderately complicated layout, this may be quite tedious and so a set of routines, the 'xdl_view layout routines' have been written to assist with this task. using these routines, the basic look of the layout may be preserved and new positions and sizes automatically calculated if the size requirements of any of the individual objects are changed. The basic procedure requires that the layout is analysed so that it can be defined in terms of pairs of objects and/or previously defined pairs. Each newly defined pair may be in a horizontal or vertical direction. Minimum size requirements are given for the individual objects and recursive procedures are used to calculate the overall size requirement for the layout and to reset the sizes and positions of the individual objects. There is also an option to include a table (regular rows and columns of single objects) as an item of a pair.

1.4 APPLICATION PROGRAM EXAMPLE

This section shows how to write a simple program to perform a selected transformation on a set of data read from a file and write out a file of the transformed data. The program creates a base frame on which a menu area and an I/O window are positioned. The menu has the following items and a quit button:

• Read Data File

• Perform Transformation A

• Perform Transformation B

• Write Data File

Figure 1.1 Display from the Example Program

Versions of the program in both 'C' and Fortran are given below:

Programxdl_example.c

void rd_data(), wr_data(), trans_a(), trans_b();
main()
{
   float a[1000];            /* Data array */
   int ncolors[2];           /* Array for numbers of colours */
   int nplanes[2];           /* Array for numbers of overlay planes */
   int vhlist[2];            /* View-objects list for events input */
   int item;                 /* Returned menu item number */
   int quit;                 /* Returned menu quit option selected flag */
   int vh;                   /* Returned view-object handle from events
                                loop*/
   char filnam[101];         /* String to hold file name */
   static char *names[] =
   {"Read Data File",
    "Perform Transformation A",
    "Perform Transformation B",
    "Write Data File"
   };

   /* Initialise (only default short colour map needed)*/
   xdl_open_view (0, ncolors, nplanes);

   /* Set up base frame */
   xdl_base_frame (1, 530, 420, "Example", 0, "Examp", 0, -1, -1);

   /* Set up menu area and i/o window */
   xdl_menu_area (2, 1, 10, 10, 0, 6, 25, 2, 1, 25, 250, 400);
   xdl_io_window (3, 1, 270, 10, 0, 0, 0, 250, 400, 2, 100);

   /* Set menu details */
   xdl_menu_area_setmenu (2, 4, names, 0, "Options", 0, "Quit", 0, 2);

   /* Menu servicing loop */
   next:
   vhlist[0] = 2;
   vh = xdl_get_events (1, vhlist);
   if (vh==2)
   {
      xdl_menu_area_getitem (2, &item, &quit);
      if (quit==1) exit(1);
      switch (item)
      {
         case 1:
            /* Get file name and read data file */
            xdl_io_window_print (3, "Input file name: ", 0);
            vhlist[0] = 3;
            vh = xdl_get_events (1, vhlist);
            xdl_io_window_getstring (3, filnam, 100);
            rd_data (filnam, a);
            break;
         case 2:
            /* Transformation A on data */
            trans_a (a);
            break;
         case 3:
            /* Transformation B on data */
            trans_b (a);
            break;
         case 4:
            /* Get file name and write data file */
            xdl_io_window_print (3, "Output file name: ", 0);
            vhlist[0] = 3;
            vh = xdl_get_events (1, vhlist);
            xdl_io_window_getstring (3, filnam, 100);
            wr_data (filnam, a);
            break;
      }
   }
   goto next;
}

/* Dummy data processing routines */
void rd_data (filnam, a) char *filnam; float a;
{ printf ("\nOpen file %s and read data into 'a'", filnam); return;}
void wr_data (filnam, a) char *filnam; float a;
{ printf ("\nOpen file %s and write data from 'a'", filnam); return;}
void trans_a (a) float a; {printf ("\nTransformation A"); return;}
void trans_b (a) float a; {printf ("\nTransformation B"); return;}

      REAL A(1000)
      INTEGER XDLSTR
      INTEGER NCOLRS(2), NPLANS(2), IVHLIS(2)
      INTEGER ITEM, IQUIT, IVH, IERR
      CHARACTER*100 FILNAM
      CHARACTER*25 NAMES(4)
      DATA NAMES /'Read Data File',
     *            'Perform Transformation A',
     *            'Perform Transformation B',
     *            'Write Data File'/

C====== Initialise (only default short colour map needed)
      CALL XDLF_OPEN_VIEW (0, NCOLRS, NPLANS, IERR)

C====== Set up base frame
      CALL XDLF_BASE_FRAME (1, 530, 420, XDLSTR('Example'), 7,
     *                      XDLSTR('Examp'), 5, -1, -1)

C====== Set up menu area and i/o window
      CALL XDLF_MENU_AREA (2, 1, 10, 10, 0, 6, 25, 2, 1, 25,
     *                     250, 400, IERR)
      CALL XDLF_IO_WINDOW (3, 1, 270, 10, 0, 0, 0, 250, 400, 2, 100,
     *                     IERR)

C====== Set menu details
      CALL XDLF_MENU_AREA_SETMENU (2, 4, XDLSTR(NAMES), 25,
     *                             XDLSTR('Options'), 7,
     *                             XDLSTR('Quit'), 4, 2, IERR)

C====== Menu servicing loop
100   IVHLIS(1) = 2
      CALL XDLF_GET_EVENTS (1, IVHLIS, IVH)
      IF (IVH.EQ.2) THEN
         CALL XDLF_MENU_AREA_GETITEM (2, ITEM, IQUIT)
         IF (IQUIT.EQ.1) STOP
         IF (ITEM.EQ.1) THEN
            CALL XDLF_IO_WINDOW_PRINT
     *           (3, XDLSTR('Input file name: '), 17, 0, IERR)
            IVHLIS(1) = 3
            CALL XDLF_GET_EVENTS (1, IVHLIS, IVH)
            CALL XDLF_IO_WINDOW_GETSTRING (3, XDLSTR(FILNAM),
     *                                     100, IERR)
            CALL RDDAT (FILNAM, A)
            GO TO 100
         ELSE IF (ITEM.EQ.2) THEN
            CALL TRANSA (A)
            GO TO 100
         ELSE IF (ITEM.EQ.3) THEN
            CALL TRANSB (A)
            GO TO 100
         ELSE IF (ITEM.EQ.4) THEN
            CALL XDLF_IO_WINDOW_PRINT
     *           (3, XDLSTR('Output file name: '), 18, 0, IERR)
            IVHLIS(1) = 3
            CALL XDLF_GET_EVENTS (1, IVHLIS, IVH)
            CALL XDLF_IO_WINDOW_GETSTRING (3, XDLSTR(FILNAM),
     *                                     100, IERR)
            CALL WRDAT (FILNAM, A)
            GO TO 100
         ENDIF
      ENDIF
      GO TO 100
      END

C====== Dummy data processing routines
      SUBROUTINE RDDAT (FILNAM, A)
      CHARACTER*(*) FILNAM
      REAL A(1000)
      WRITE (6,*) 'Open file', FILNAM, 'and read data into ''a'''
      RETURN
      END
      SUBROUTINE TRANSA (A)
      REAL A(1000)
      WRITE (6,*) 'Transformation A'
      RETURN
      END
      SUBROUTINE TRANSB (A)
      REAL A(1000)
      WRITE (6,*) 'Transformation B'
      RETURN
      END
      SUBROUTINE WRDAT (FILNAM, A)
      CHARACTER*(*) FILNAM
      REAL A(1000)
      WRITE (6,*) 'Open file', FILNAM, 'and write data from ''a'''
      RETURN
      END

1.5 SOME OTHER CONSIDERATIONS

The application program should not, in general, have any form of input which will block the program i.e. it should avoid reading input from the terminal input stream using normal Fortran (or C) read statements; instead, it should use a window such as the I/O window for such input as this allows for event handling to continue while the input is awaited. (Some routines are now available to perform non-blocking reads from the standard input whilst events are being handled; however these are best avoided wherever possible as they depend on alarm functions etc.)

If the program enters a time consuming process, e.g. a long computation or reading a large file, then, if feasible, the routine xdl_flush_events, in 'C', or xdlf_flush_events, in Fortran, should be called at reasonably frequent intervals to allow background event handling to continue. Note that during such a process, the program is not waiting for any input from a view-object.

It should also be noted that pop-up view-objects, such as the pop-up dialogue box, lock out the display until a response is made to them. Their use should be avoided as much as possible and they should not be used as a means of inputting information to the program just to make life a bit easier for the programmer. Where possible an I/O window view-object on a control item view-object containing a panel I/O item should be used.