John W. Campbell
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
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:
- To use X-windows.
- To make use of a colour display.
- To provide 'high level' view-objects for easy use in building
application software.
- To be able to set up and manipulate such objects via Fortran
callable routines (as well as providing a C interface).
- To provide code which would be portable across a range of
workstations with a certain minimum specification.
- To enable view-objects to appear in individual windows or to be
laid out in a tiled fashion on a larger window.
- To provide a means for specifying the view-objects from which
the application is prepared to accept input at any particular
time.
- 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.
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:
- To initialise JdlView management.
This sets up the context for managing the JdlView objects for the program
and sets standard fonts and colours.
- 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
- 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.
- To layout JdlView objects.
Methods of the JdlViewManager object enable a layout to be calculated
and implemented for a managed set of JdlView objects.
- To handle events.
Methods of the JdlViewManager object are used to manage the user/data input
from a selected set of JdlView objects.
The basic structure for a program using JdlView objects managed by
the JdlViewManager object is as follows:
- Create a JdlViewManager object. This must be done
before any other JdlView objects, which are to be managed, are created.
- Create any JdlView objects required by the program.
- Add the JdlView objects to the managed list using the
addViewObject(..) method of the JdlViewManager object.
Then, at any stage where program input is awaited, do the following:
- Set up a list of the JdlView objects
from which the program is currently prepared to accept input.
- Wait for input from one of these JdlView objects by calling
the waitForViewActions(..) method of the JdlViewManager object.
- 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.
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:
- 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).
- 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.
- 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.
- Interrupt.
If interrupt processing is enabled (using the allowInterrupt(..)
method) then the waitForViewActions(..) method may be forced
to return by calling the interrupt(..) method.
- 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.
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.
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:
- Read Data File
- Perform Transformation A
- Perform Transformation B
- Write Data File
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 {
//Main:
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.layoutInitialize();
vm.layoutSetHorizontalPair("top", "men1", "io1", 1, 30.0);
vm.layout("top", base_fr);
// Main polling loop (with inner event loops)
// ==========================================
while(true)
{
// 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);
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
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);
break;
}
}
}
}
// 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
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:
- JdlTemplate1.java
- This is the template on which the supporting 'panel items' coding
is based.
- JdlTemplateView.java
- This is the template for the high level JdlView objects which can
be managed by the JdlViewManager object. They implement the JdlViewObject
interface.
- JdlInterfaceTemplate.java
- This is a template for coding supporting interface classes.
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