Additional mouse functionality for interactive PGPLOT programs


 

Introduction

I often write programs that use the PGPLOT Graphics Subroutine Library to produce plots or graphics. Some of these programs are interactive: after having produced a plot the program will pause and allow the user to interact with it by positioning the cursor in the PGPLOT graphics window and hitting some key or clicking a mouse button. I usually achieve this by using the PGBAND subroutine. However, I have always been annoyed by the following three shortcomings (which apply to all interactive subroutines, but I am only concerned with PGBAND):

The purpose of the "patch" described and provided here is to fix these shortcomings.
 

Download and installation

Simply download this file: http://www.hs.uni-hamburg.de/jliske/pub/pgplot_mouse.tar.gz. After unzipping and unpacking the file you will find a directory called pgplot_mouse. It contains the document you are reading, some source code and two scripts.

In the following I will assume that you have a "classic" PGPLOT installation, i.e. that you have downloaded the original PGPLOT distribution file and went through the standard PGPLOT installation procedure. Unfortunately, this is a requirement for you to be able to install this patch. If instead you have obtained PGPLOT as an RPM or as part of a software collection (such as Scisoft) you will not be able to install the patch. The reason is that in order to integrate the new functionality into the PGPLOT library you will need to (re-)compile it, meaning that you need the PGPLOT source code which is usually not included in an RPM or in the Scisoft distribution. This is a bit painful, I know. However, it's not very hard to install PGPLOT yourself. Just follow the instructions.

Assuming that you have successfully installed PGPLOT, the script pgplot_mouse/patch_pgplot pretty much tells you what you need to do to install the "patch". In the following I will assume that your PGPLOT installation lives in the directory PGPLOT_DIR (usually /usr/local/pgplot), and that the PGPLOT distribution directory tree (i.e. the result of unpacking the PGPLOT distribution file) is found at PGPLOT_SRC (usually /usr/local/src/pgplot).

First of all, you need to edit the file PGPLOT_DIR/drivers.list. Add the following two lines to the list of drivers:

 XJDRIV 1 /XJWINDOW   Workstations running X Window System              C
 XJDRIV 2 /XISERVE    Persistent window on X Window System              C
Now delete everything in PGPLOT_DIR except for the file drivers.list which you just edited. Next you need to copy the second script and the source files included in the patch to the appropriate directories:
cp -f pgplot_mouse/makemake PGPLOT_SRC/
cp -f pgplot_mouse/xjdriv.c PGPLOT_SRC/drivers/
cp -f pgplot_mouse/pgjband.f PGPLOT_SRC/src/
cp -f pgplot_mouse/grcurs2.f PGPLOT_SRC/src/
Now simply follow the normal PGPLOT installation instructions from the point where you run makemake. I.e. change to the PGPLOT_DIR directory and type something like:
PGPLOT_SRC/makemake PGPLOT_SRC linux g77_gcc
make
make cpg
make pgplot.html
make clean
The exact command on the first line above will depend on your system, see the PGPLOT installation instructions. Finally, put the resulting libraries where they can be found by your system, something like:
cp libpgplot.* /usr/local/lib/
cp libcpgplot.* /usr/local/lib/
cp cpgplot.h /usr/local/include/
Done.

Obviously, if you have multiple versions of PGPLOT (e.g. a patched version and a Scisoft version) then you need to make sure that you are linking against the patched library when compiling a program that is supposed to make use of the new functionality.
 

Using the new features

Essentially, the patch provides a new subroutine called PGJBAND. It is identical to the standard PGBAND routine, except that it fixes all of the above issues. In order to be able to use this new subroutine your program needs to select one of the two new devices provided by the patch: /xjwindow or /xiserve. These are identical to the standard /xwindow and /xserve devices, respectively, except that they fix all of the above issues.

Like the standard PGBAND routine the new PGJBAND routine also reads the cursor position and a character typed by the user. The character that was typed is returned in one of the function's arguments. If, instead of typing a character, a mouse button is clicked both routines return the characters 'A', 'D' or 'X' for the left, middle and right mouse buttons, respectively. In addition, PGJBAND also recognises the scroll wheel and mouse button 6 (if it exists), returning 'Y', 'P' and 'T', respectively. Furthermore, pressing SHIFT while clicking a mouse button (or using the scroll wheel) causes lower case characters to be returned. CTRL + (mouse click) is identical to CTRL + (corresponding character). Finally, in contrast to the standard routine, PGJBAND returns two cursor positions: the position where the mouse button was pressed as well as the position where it was released. It also returns a flag indicating whether the cursor was moved between the two events. Although this is nowhere near a real "drag'n'drop" feature (because nothing apart from the cursor actually moves while dragging), one can at least use this to provide a feature resembling "drag'n'drop".

A full description of PGJBAND is included in the file pgplot.html that was created above.
 

License / Disclaimer

Copyright (C) 2009 by Jochen Liske.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Joe Liske Imprint