CHAPTER 2 - THE DESIGN OF XDL_VIEW
2.1 INTRODUCTION
The basic requirements that the XDL_VIEW software was designed to meet and the basic philosophy of the routines have already been described in section 1.1 of Volume 1 and section 1.1 of this volume. A more detailed description of items relating to the XDL_VIEW management routines is given in the following sections. The items described are:- The view-object list
- The initialisation routine
- The event handling routine(s)
List of sections:
The View-Objects List
'C' Structures Associated with the View-Objects List
Routines for Managing the View-Objects List
The Initialisation Routine
Event Handling
The Fortran to 'C' Interface
Fonts
2.2 THE VIEW-OBJECTS LIST
The heart of the management of the XDL_VIEW view-objects is an array of C structures with one element for each view-object currently present for the application. The structure includes a list of all windows associated with the view-object, pointers to global data areas associated with the view-object and the names of callback and other routines for use for example in the event handling.
The view-object routines are coded in such a way that multiple copies of any particular view-object may be used as required. In most cases, when a new view-object is created, the routine which is called to create it allocates an area of memory for a view-object specific C structure to hold any items of data which are required for communication bewteen the various routines associated with that view-object. Thus each instance of a view-object has its own 'global data' area.
2.3 'C' STRUCTURES ASSOCIATED WITH THE VIEW-OBJECTS LIST
The format of the view-objects list structure is as follows:
typedef struct
{
int vh; /*The view object handle as set in the
application program*/
Window wid; /*The (top level) window id for this
view-object*/
int vh_parent; /*View object handle of parent if view-object is
a sub_window of another view-object in the
XDL_view_objects list*/
int type; /*A unique integer value identifying the
view-object type. This is for safety checking
to ensure that, when a routine is called to
manipulate or get data from a view-object
identified by the view-object handle, the
view-object is of the correct type*/
char *gd; /*Pointer to structure of data items used for
communicating between the functions of the
view-object ('global data' area)*/
int num_win ; /*Number of window objects associated with
this view-object (subwindows etc.)*/
XDl_window *win_list; /*Array of window objects associated with
this view-object. (includes the top level
window of the view-object*/
void (*on_off)(); /*Pointer to view-object's on/off function to
be called to turn program input from the
view-object on or off. This will be called
by the xdl_get_events routine. A null may
be given if such a routine is not required
or implemented*/
void (*tidy_up)(); /*Pointer to the view_object's tidy up
function to be called when the view-object is
deleted by calling the xdl_delete_view_object
routine. This routine will for example free
any memory areas allocated by the view object.
(It need not free the global data area as this
will be automatically freed by the
xdl_delete_view_object routine). A NULL may
be given if such a routine is not required*/
}
XDl_view_object;
As already indicated, the entry for a view-object contains a pointer to a list
of windows associated with the view-object. Each entry in this list is a
structure with the following format:
typedef struct
{
Window wid; /*Window i.d. for the window*/
void (*repaint)(); /*Repaint routine to be called on expose,
configure notify (resize) */
void (*ehp)(); /*Event Handling Procedure for other events*/
XDl_libdata *libdata; /*Pointer to XDl_libdata structure for a library
routine window - otherwise NULL*/
}
XDl_window;
If a window is associated with some special library type of routine (e.g.
a panel item) then an additional structure of type XDl_libdata may be
present. This has the following format:
typedef struct
{
char *gd; /*Pointer to a private data area used by the
library window function*/
void (*callback)(); /*Callback routine to return data to
view-object*/
void (*tidy_up)(); /*Tidy up routine to be called when library
routine window is deleted via
xdl_delete_view_object (this need not free gd
as this will be done automatically by
xdl_delete_view_object)*/
}
XDl_libdata;
2.4 ROUTINES FOR MANAGING THE VIEW-OBJECTS LIST
A number of routines are available for managing the list of view-objects. These include the following:
- xdl_open_view
- Initialises the view-objects list amongst other
functions (see next section).
- xdl_new_view_object
- Add a new view-object to the list of view-objects.
- xdl_add_window
- Add details of a window to the windows list for a view object.
- xdl_add_libwin
- Add library routine window to the list of
windows for a view-object.
- xdl_delete_view_object
- Delete a view-object from the view-objects list.
- xdl_get_events
- Event handling (also xdl_getio_events)
- xdl_getiv
- Get offset in view-objects list for a
view-object given the view-object handle.
- xdl_get_global
- Get 'global data' pointer from a window id.
- xdl_get_vh
- Get view-object handle for the view-object associated with a given window id.
A list of all the routines in the xdl_view.c source file is given in Volume 3 of the documentation. The calls to the repaint, event handling, on_off and tidy_up routines are also described in Volume 3 of the documentation.
2.5 THE INITIALISATION ROUTINE
The initialisation routine xdl_open_view (or xdlf_open_view for Fortran) must be called before any other XDL_VIEW routine. As already indicated, it initialises the array of XDl_view_object structures. It also sets up, in addition to a a small default colour map which contains the colours black, white and the six primary and secondary colours, colour maps based on the user's requirements for the application. In addition to these items, a number of other global data items, which may be used within the code for the individual view-objects, are set up by the initialisation routine.
The global data items set up are as follows:
- X-windows Display and Screen Parameters
Display *XDL_display; Display. XtAppContext XDL_app; Application Context int XDL_screen; Screen no. int XDL_open = 0; XDL_VIEW opened flag.
- View-objects List
int XDL_num_view_objects; Number of view-objects set up. XDl_view_object **XDL_view_objects; Array of pointers to XDL_view_object structures int XDL_max_alloc_objects; Max. no. of view-objects for which table space has been allocated. - Fonts
XFontStruct *XDL_fontinfo; Standard (small) font. XFontStruct *XDL_fontinfo_bold; Standard (small) bold font. XFontStruct *XDL_fonts[5]; Fonts very small, small, medium, large and very large. XFontStruct *XDL_bold_fonts[5]; Bold fonts very small, small, medium, large and very large. - Default Cursor (Arrow pointing up and left)
Cursor XDL_default_cursor; Default cursor.
- Colour Requirements
int XDL_color; Colour availability flag = 0, not available - monochrome = 1, grays = 2, colour int XDL_display_type; Display type to be used = StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor or DirectColor (Values defined in X.h) int XDL_csets_alloc; =1 requested colour sets allocated with writeable colour cells =0 requested colour sets not allocated (static display type or less than 8 bit planes) int XDL_display_cells; No. of color cells available. Visual *XDL_visual; Visual for creating windows. int XDL_pw_depth; Depth for paint windows. Colormap XDL_colormap; Colormap selected for the application. int XDL_num_colorsets; Number of colormap sets (in addition to the standard short pallette). XDl_colorset XDL_colorsets[MAXCOLORSETS]; Array of allocated colormap sets unsigned long XDL_blackpixel; Black pixel no. unsigned long XDL_whitepixel; White pixel no. unsigned long XDL_redpixel; Red pixel no. unsigned long XDL_yellowpixel; Yellow pixel no. unsigned long XDL_greenpixel; Green pixel no. unsigned long XDL_cyanpixel; Cyan pixel no. unsigned long XDL_bluepixel; Blue pixel no. unsigned long XDL_magentapixel; Magenta pixel no. - Graphics Context for 'active strip' (used by routines in xdl_view.c)
GC XDL_active_strip_gc; GC for standard 'view-object active for input to the application' window use. - Flag for event handling routine (xdl_get_events)
int XDL_return_data_vh; Data returned from 'active' view-object. flag = 0, none returned. > 0, the view-object handle of the view-object returning the data. - Select/Paste Options
Atom XDL_paste_buffer; Atom for xdl_view cut/paste string buffers. - Handling events at timed intervals
int XDL_tmr_events; Timer events handling in progress flag. =0 no, =1 yes - Pointers list for XDLSTR function
char * XDL_pointers[MAXPOINTERS]; List of string pointers. int XDL_pointers_index; Last index to pointers currently used (list used in a circular manner).
The definitions are included in the file 'xdl_view_extern.h' which should be included in all view-objects source code files.
2.6 EVENT HANDLING
An important part of XDL_VIEW is the X event handling mechanism. This is normally done through a call from the application program to the routine xdl_get_events (in C) or xdlf_get_events (in Fortran). When the routine is called, the user specifies a list of the view objects from which the program is ready to receive input ('active' view-objects). The routine services all the X events, passing them on to the approriate event handling routines, as defined in the XDl_view_objects array, until an event causes program input from one of the active view-objects; when this occurs, a return is made from the routine giving the view-object handle of the routine from which the input originated. The structure of the event handling routine is shown below:
Structure of the event handling routine xdl_get_events
Set XDL_return_data_vh, the data returned
from view-object flag, to zero.
|
For each view-object in the user specified
active view-objects list, call the on/off
routine specified for that view-object in
the XDL_view_objects array (unless a NULL)
with the flag set to 'on'.
|
|-------------------------->|
| |
| Get (wait for) next X event and find the
| id of the window associated with it (wid)
| |
| Find the offset in the XDL_view_objects
| array (iv) for the view-object to which
| the window belongs and the XDl_window
| structure associated with the window.
| |
| If the event was a Configure Notify or an
| Expose, then call the repaint routine for
| that window (unless a NULL) as defined in
| the XDL_window structure. Otherwise call
| the general event handling procedure
| (unless a NULL) from the XDL_window
| structure.
| |
| Has the XDL_return_data_vh flag been set
|<--No--- to a view-object handle?
| |
| Yes
| |
| Is the view-object in the list of active
| view-objects (reset XDL_return_data_vh to
|<--No--- zero before continuing)
|
Yes
|
For each view-object in the user specified
active view-objects list, call the on/off
routine specified for that view-object in
the XDL_view_objects array (unless a NULL)
with the flag set to 'off'.
|
Flush display and return the view-object
handle to the calling program.
When the program is not waiting for events from a view-object and is in the middle of a long calculation, it may be desirable to call, at intervals, the routine xdl_flush_events (in C) or xdlf_flush_events (in Fortran) to service any X events currently in the event queue. This will enable 'background' activity to continue in the windows of the view-objects for events which do not give rise to program input.
Routines are also available which will handle keyboard input from the standard input stream whilst handling events xdl_getio_events (xdlf_getio_events). Their use is best avoided if possible.
2.7 THE FORTRAN TO 'C' INTERFACE
Some thought has been given to the portability of the Fortran to C interface. Passing integer and real parameters seems to pose no problems. When needed, the address of a character string is passed as a parameter using a function XDLSTR to return an index to an internal table of pointers which contains the address of the character string. The string length is always passed as an additional, integer, parameter. A table relating the routine names expected by the linker to those within the C source code is set up within each view-object source code file. Two parameter definitions in a file xdl_view_systyp.h select the option to be used for the XDLSTR routine and the form of the linking name. These are CHAR_STRING_TYPE and LINKTYP. The xdl_systyp.h file also contains a few other definitions required to cope with variations in system functions available on different operating systems or versions of operating systems. The required options are set in this file for a range of machine types and others will be added as the information becomes available.
For routines, which return character strings, it may be useful to follow the example of a routine such as xdl_io_window_getstring. The routine allows for either the return of the character data into a Fortran string padded with blanks, if the 'max_len' parameter is given a negative value in the call, or into a null terminated C string, if the 'max_len' parameter is given a positive value. The xdl_copy_chars routine is available to assist such an implementation.
2.8 FONTS
The original set of view-objects were written to use the five sizes of Courier fonts as set up by the the xdl_open_view initialisation routine. These fonts are available in both normal and bold print (structure pointers *XDL_fonts[5] and *XDL_bold_fonts[5]). The following default font specifications are now used within the routines:
static char *font_default[] =
{
"*adobe-courier-medium-r*--8*",
"*adobe-courier-medium-r*--12*",
"*adobe-courier-medium-r*--14*",
"*adobe-courier-medium-r*--18*",
"*adobe-courier-medium-r*--24*"}; /* Default fontnames */
static char *font_bold_default[] =
{
"*adobe-courier-bold-r*--8*",
"*adobe-courier-bold-r*--12*",
"*adobe-courier-bold-r*--14*",
"*adobe-courier-bold-r*--18*",
"*adobe-courier-bold-r*--24*"}; /* Default fontnames */
Fonts will normally be defined as X-windows resources Xdl*font1...Xdl*font5
and Xdl*boldFont1...Xdl*boldFont5. There are five normal and five bold fonts.
These should normally be fixed width fonts. Each series must be in ascending
size order. Bold fonts must match normal fonts to within 1 pixel in width
and two in height. Some of the view-objects assume that the small font does
not exceed 7x13 in pixels in size; a warning will be output if this size
is exceeded.
The following is an example of specifing the fonts as X-windows resources:
Xdl*font1: -adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1 Xdl*font2: -adobe-courier-medium-r-normal--12-120-75-75-m-70-iso8859-1 Xdl*font3: -adobe-courier-medium-r-normal--14-140-75-75-m-90-iso8859-1 Xdl*font4: -adobe-courier-medium-r-normal--18-180-75-75-m-110-iso8859-1 Xdl*font5: -adobe-courier-medium-r-normal--24-240-75-75-m-150-iso8859-1Xdl*boldFont1: -adobe-courier-bold-r-normal--10-100-75-75-m-60-iso8859-1 Xdl*boldFont2: -adobe-courier-bold-r-normal--12-120-75-75-m-70-iso8859-1 Xdl*boldFont3: -adobe-courier-bold-r-normal--14-140-75-75-m-90-iso8859-1 Xdl*boldFont4: -adobe-courier-bold-r-normal--18-180-75-75-m-110-iso8859-1 Xdl*boldFont5: -adobe-courier-bold-r-normal--24-240-75-75-m-150-iso8859-1
John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998