Part 2 - JdlView Programmer's Guide

  John W. Campbell

2.1 Introduction

The Java based JdlView set of objects has been based on an X-windows based toolkit XDL_VIEW which was written in 'C'. It may be helpful for the application programmer to understand something of the considerations behind the development and philosophy of that package and to highlight some similarities and differences in the JdlView package.

This programmer's guide is concerned primarily with the use of JdlView to program similarly structured programs to those which were originally developed using XDL_VIEW.

It should be emphasised however that the JdlView objects do not need to be used in the manner described below but can be incorporated into Java programs as would be the case with other window based objects using the normal callback (Listener) mechanisms. The more specialised JdlView objects (e.g. those for displaying crystallographic images and simulations) are those most likely to be of interest for use outside the complete package. The more general purpose JdlView objects (such as menus and parameter tables) are designed to fit together as a package of consistent style with strong similarities to the XDL_VIEW package.

When JdlView is used in a similar manner to XDL_VIEW, a characteristic is that many of the objects will display an 'active strip'. When the objects are used in different circumstances (specifically the JdlViewManager object is not instantiated), no such active strips will be present.

List of sections:

Philosophy behind the package
JdlView Management
The Basic Structure of a JdlView application program
Special Types of Input
Laying Out JdlView Objects
Application Program Example
Coding New JdlView Classes
Some Other Considerations

2.2 Philosophy behind the package

This section first summaries the reasons and requirements of the XDL_VIEW package and then compares and contrasts these with the JdlView package.

In developing the original XDL_VIEW, the basic requirements were considered to be as follows:
  1. To use X-windows.

  2. To make use of a colour display.

  3. To provide 'high level' view-objects for easy use in building application software.

  4. To be able to set up and manipulate such objects via Fortran callable routines (as well as providing a C interface).

  5. To provide code which would be portable across a range of workstations with a certain minimum specification.

  6. To enable view-objects to appear in individual windows or to be laid out in a tiled fashion on a larger window.

  7. To provide a means for specifying the view-objects from which the application is prepared to accept input at any particular time.

  8. To provide documentation to cover user and programmer requirements.
The most obvious item which has been removed from this list is the fact that the XDL_VIEW package was designed to be used with both 'C' and Fortran based programs. JdlView is designed purely for use within the Java environment.

The other objectives are achieved in JdlView though the package, being Java based, works on any windowing operating system which supports Java. These days colour based displays are considered to be the norm and JdlView no longer attempts to deal with monochrome only displays.

The general look and feel of the software has been preserved though modernised to use a grey background and 3-D buttons and frames etc. as well as using proportional fonts in most situtaions.

Most importantly, the package enables programs to be structured in a similar manner to that used with the XDL_VIEW package; this normally involves the use of a hierarchical menu structure. The philosophy, of having an active strip at the top of objects from which program input may be received, is preserved.

Structuring programs in this way, gives a clear indication of what options are appropriate and available at each stage. This contrasts with the common use in applications of a menu bar with items such as 'File', 'Edit' etc. Implementing such a menu bar was considered but rejected as it does not really fit with the basic structuring envisaged in the development of JdlView; however, as already noted, a programmer can use JdlView objects without using the JdlView manager and in such a case use a menu bar if desired.

When used with the JdlView manager, a simple set of fonts and a consistent set of colours is used.

Also a layout may be calculated by using a given set of methods and defining the layout in terms of horizontal or vertical pairs of JdlView objects and/or other previously defined pairs.

2.3 JdlView Management

When the JdlView package is to be used in a similar manner to that of XDL_VIEW a JdlViewManager object needs to be created at the start of the program. This has the following main functions:
  1. To initialise JdlView management.

    This sets up the context for managing the JdlView objects for the program and sets standard fonts and colours.

  2. To indicate the context to new JdlView objects.

    Any JdlView objects created following the creation of the JdlViewManager object will automatically be set up to be used within that context and with active strips for those objects which can return data to the calling program

  3. To manages the list of JdlView objects.

    Methods of the JdlViewManager object enable JdlView objects to be added or removed from the list of objects to be managed.

  4. To layout JdlView objects.

    Methods of the JdlViewManager object enable a layout to be calculated and implemented for a managed set of JdlView objects.

  5. To handle events.

    Methods of the JdlViewManager object are used to manage the user/data input from a selected set of JdlView objects.

2.4 The Basic Structure of a JdlView application program

The basic structure for a program using JdlView objects managed by the JdlViewManager object is as follows:
  1. Create a JdlViewManager object. This must be done before any other JdlView objects, which are to be managed, are created.

  2. Create any JdlView objects required by the program.

  3. Add the JdlView objects to the managed list using the addViewObject(..) method of the JdlViewManager object.

  4. Then, at any stage where program input is awaited, do the following:

    1. Set up a list of the JdlView objects from which the program is currently prepared to accept input.

    2. Wait for input from one of these JdlView objects by calling the waitForViewActions(..) method of the JdlViewManager object.

    3. Service the returned input.

      The waitForViewActions(..) method returns a reference to the JdlView object from which the input was received. Methods from that object may then be called to get details of the input as appropriate.
After a return from the waitForViewActions(..) method, the procedure followed will depend on the nature of the program. For example the program may return to repeat the polling from the same set of JdlView objects or change the list of JdlView objects from which input can be accepted before next calling the waitForViewActions(..) method. Alternatively, when required, the user may create new JdlView 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 in a hierarchical structure.

2.5 Special Types of Input

In addition to events generated by the displayed JdlView objects, it is possible to handle input from several other sources through options available when using the waitForViewActions(..) method. These are:
  1. Terminal I/O.

    This enables non-blocking input to be processed from the window from which the program was run (i.e. the standard input stream).

  2. Timeout return.

    There is an option to generate a return if no input is received from one of the listed JdlView objects within a given time interval.

  3. Timer return.

    There is a JdlViewTimer object which, though it has no associated window, may be included in the list of objects (or may be used as the only object in the list) for the waitForViewActions(..) method. It generates an action after a requested time interval.

  4. Interrupt.

    If interrupt processing is enabled (using the allowInterrupt(..) method) then the waitForViewActions(..) method may be forced to return by calling the interrupt(..) method.

  5. Window closure.

    The waitForViewActions(..) method may respond to the attempted closure of JdlView object windows for which the 'PROGRAM_CLOSE' option was set for their base frames.

2.6 Laying Out JdlView Objects

The JdlViewManager and JdlViewLayout classes have equivalent methods for calculating a layout and setting sizes and positions for a set of JdlView objects where several objects are to be fitted together to give a tidy looking layout. 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 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 various options, on what to do if JdlView objects are to be expanded, are available. Recursive procedures are used to calculate the overall size requirement for the layout and to reset the sizes and positions of the individual objects. In contrast to the standalone set of methods in the JdlViewLayout object, the methods from the JdlViewManager class access JdlView objects which have been registered with the manager using the addViewObject(..) method; also the layout is also set as well as being calculated.

2.7 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. A copy is available in the 'example' sub-directory of the JdlView source code directory. The program creates a JdlBaseFrame object on which a JdlMenuArea and a JdlIOWindow object are positioned. The menu has the following items and a quit button: Note that the methods for reading, writing and transforming the data are just dummy methods in the code given below and output messages to the terminal indicating that their functions have been carried out.

import Jdl.JdlView.*;

public class JdlExample extends Object {

  static JdlBaseFrame base_fr;
  static JdlIOWindow io;
  static JdlMenuArea menu;

  public static void main (String args[])
     JdlViewManager vm;
     JdlViewObject[] act_obj = new JdlViewObject[2];
     String[] menstr = {"Read Data File",
                        "Perform Transformation A",
                        "Perform Transformation B",
                        "Write Data File"};
     int item=1;
     float[] a = new float[100];
     String filnam;
     JdlViewObject vobj;

  // Create JdlViewManager object

     vm = new JdlViewManager();

  // Create base frame, menu area and I/O window objects
  // and add them to the managed list of JdlView objects

     base_fr = new JdlBaseFrame("Example", 100, 100);
     vm.addViewObject("base", base_fr, null, 1, 100, 100, 0);

     menu = new JdlMenuArea("Options", menstr, 0, "Quit", 6, 0, 
                             true, true, 0, 0, null, null);
     vm.addViewObject ("men1", menu, base_fr, 2, 10, 10, 0);

     io = new JdlIOWindow(10, 20, null, null);
     vm.addViewObject("io1", io, base_fr, 2, 20, 20, 0);

  // Determine and set the layout

     vm.layoutSetHorizontalPair("top", "men1", "io1", 1, 30.0);
     vm.layout("top", base_fr);

  // Main polling loop (with inner event loops)
  // ==========================================

        // Now input from menu only
        act_obj[0] = menu;
        vobj = vm.waitForViewActions(act_obj, 1, false, true, null, 0L);

        if (vobj==menu)
           item = menu.getReturnedData();
           if (item==0) System.exit(1);
           switch (item)
              case 1:
	         // Get file name and read data file
                 io.outputString("Input file name: ", 1);
                 // Now input from I/O object only
                 act_obj[0] = io;
                 vm.waitForViewActions(act_obj, 1, false, true, null, 0L);
                 filnam = io.getReturnedData();
                 rd_data (filnam, a);
              case 2:
	         // Transformation A on data
                 trans_a (a);
              case 3:
	         // Transformation B on data
                 trans_b (a);
              case 4:
	         // Get file name and write data file
                 io.outputString("Output file name: ", 1);
                 // Now input from I/O object only
                 act_obj[0] = io;
                 vm.waitForViewActions(act_obj, 1, false, true, null, 0L);
                 filnam = io.getReturnedData();
                 wr_data (filnam, a);
  // Dummy data processing methods
  static void rd_data (String filnam, float[] a)
  {System.out.println("Open file "+filnam+" and read data into 'a'"); return;}
  static void wr_data (String filnam, float[] a)
  {System.out.println("Open file "+filnam+" and write data from 'a'"); return;}
  static void trans_a (float[] a)
  {System.out.println("Transformation A"); return;}
  static void trans_b (float[] a)
  {System.out.println("Transformation B"); return;}

Figure 1: The Example Program

2.8 Coding New JdlView Classes

Coding new JdlView classes is best done by following the example of existing classes. As the code was developed, the common features in the coding were standardised as far as possible and three templates have been produced to form a framework for new classes. These are held in the 'templates' sub-directory of the directory containing the JdlView source code. The standard documentation items, which can be processed by the program 'DocExtractor' are included in the templates. Such documentation is compatible with the 'javadoc' documentation tool though 'DocExtractor' only uses a sub-set of the available options. The three template source code files are as follows:

This is the template on which the supporting 'panel items' coding is based.

This is the template for the high level JdlView objects which can be managed by the JdlViewManager object. They implement the JdlViewObject interface.

This is a template for coding supporting interface classes.

2.9 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 standard input methods; 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. The JdlViewManager object also has methods to read from the standard input stream if it is necessary to do so.
⇑ Up 2   ⇑ Up 1   ⇑ Top of this