pgplotmanager

Postscript file available

tool used in application development to send plot commands to a plot device

include "pgplotmanager.g"

Constructors

pgplotmanager	Manage a previously created pgplot agent
pgplotps	Create a pgplotmanager attached a file

Functions

addredrawfunction	Add a function to redraw a command in the displaylist
canplay	return whether a command can be executed
clear	empty the display list
displaylist	return the displaylist currently in use
done	shutdown the manager
getagent	return the PGPLOT agent being managed by this tool
lastchange	Version of the last change
maskline	Draw line segments based on input vectors and a mask
play	Execute a series of plot commands
plotfile	Save the plot in native format
plotxy	Plot X,Y vectors as lines or points with auto-scaling
record	set whether drawing commands are saved
recording	return whether plot commands are being saved
refresh	replay the display list
resetplotnumber	reset the internal plot number counter to 0
restore	Retrieve a plot
setagent	set the PGPLOT agent to be managed by this tool
settings	Set many PGPLOT attributes at once

Description
The pgplotmanager is tool that is useful for building Glish applications that do specialized plotting. Many applications will prefer instead to use the pgplotwidget which is an extension of the pgplotmanager tool, specialized for plotting to a graphical widget. (Interactive users will normally use the pgplotter tool.) In contrast, pgplotmanager is device-independent; that is, its capabilities are relevent to plotting either to a widget or to a file. As a result, applications can:

use the same code for plotting to both graphical and hardcopy devices
open a hardcopy device without opening a graphical widget (as is necessary with the pgplotwidget tool) to do non-interactive plotting.

See the Example below for details on how one can accomplish this using pgplotmanager tool.

pgplotmanager is built on top of the ``raw'' Glish/PGPLOT agent, providing access to most of its capabilities through its tool functions. (That is, instead accessing pgplot function through the event syntax, e.g. pg->line(), you access it like any tool function: pg.line().) In addition, a few higher level functions have been added:

settings() -- sets many PGPLOT attributes (e.g. line width, character height) all at once.
plotxy() -- a simple function for plotting a ``y'' array versus an ``x'' array.
maskline() -- similar to the the ``raw'' function line(), but uses a mask array to determine with points plot.

An important added feature is pgplotmanager's maintenance of an internal display list--a record of plot commands (i.e. calls made to the plotmanager's plotting functions) stored inside the tool that can be played back at any time. This enables several useful capabilities:

when the GUI is resized, the plot commands can be replayed to refresh the plot, filling the new size.
plot commands can be save to a ``plot'' file, which can be opened and edited later (for example, by a user via pgplotter).
plot commands sent to a GUI can be replayed to a PostScript file.
recording of commands can be turned ``on'' and ``off.'' This allows you to ``erase'' parts of the plot. For example, you could interactively draw ellipses on the plot widget with recording turned off, and then remove the ellipses by doing a replaying the commands that were recorded.

Only those functions that add functionality beyond that of the Glish pgplot agent are described explicitly in this reference manual section. For descriptions of the ``raw'' pgplot agent functions, refer to the Glish/PGPLOT description found in the Glish User's Manual. Those functions are as follows:

: sep 0in
arro: - draw an arrow
ask: - control new page prompting
bbuf: - begin batch of output (buffer)
beg: - begin PGPLOT, open output device
bin: - histogram of binned data
box: - draw labeled frame around viewport
circ: - draw a filled or outline circle
clos: - close the selected graphics device
conb: - contour map of a 2D data array, with blanking
conl: - label contour map of a 2D data array
cons: - contour map of a 2D data array (fast algorithm)
cont: - contour map of a 2D data array (contour-following)
ctab: - install the color table to be used by PGIMAG
draw: - draw a line from the current pen position to a point
ebuf: - end batch of output (buffer)
end: - terminate PGPLOT
env: - set window and viewport and draw labeled frame
eras: - erase all graphics from current page
errb: - horizontal or vertical error bar
errx: - horizontal error bar
erry: - vertical error bar
gray: - gray-scale map of a 2D data array
hi2d: - cross-sections through a 2D data array
hist: - histogram of unbinned data
iden: - write username, date, and time at bottom of plot
imag: - color image from a 2D data array
lab: - write labels for x-axis, y-axis, and top of plot
ldev: - list available device types
len: - find length of a string in a variety of units
line: - draw a polyline (curve defined by line-segments)
move: - move pen (change current pen position)
mtxt: - write text at position relative to viewport
numb: - convert a number into a plottable character string
open: - open a graphics device
page: - advance to new page
panl: - switch to a different panel on the view surface
pap: - change the size of the view surface
pixl: - draw pixels
pnts: - draw one or more graph markers, not all the same
poly: - fill a polygonal area with shading
pt: - draw one or more graph markers
ptxt: - write text at arbitrary position and angle
qah: - inquire arrow-head style
qcf: - inquire character font
qch: - inquire character height
qci: - inquire color index
qcir: - inquire color index range
qcol: - inquire color capability
qcr: - inquire color representation
qcs: - inquire character height in a variety of units
qfs: - inquire fill-area style
qhs: - inquire hatching style
qid: - inquire current device identifier
qinf: - inquire PGPLOT general information
qitf: - inquire image transfer function
qls: - inquire line style
qlw: - inquire line width
qpos: - inquire current pen position
qtbg: - inquire text background color index
qtxt: - find bounding box of text string
qvp: - inquire viewport size and position
qvsz: - find the window defined by the full view surface
qwin: - inquire window boundary coordinates
rect: - draw a rectangle, using fill-area attributes
rnd: - find the smallest `round' number greater than x
rnge: - choose axis limits
sah: - set arrow-head style
save: - save PGPLOT attributes
unsa: - restore PGPLOT attributes
scf: - set character font
sch: - set character height
sci: - set color index
scir: - set color index range
scr: - set color representation
scrn: - set color representation by name
sfs: - set fill-area style
shls: - set color representation using HLS system
shs: - set hatching style
sitf: - set image transfer function
slct: - select an open graphics device
sls: - set line style
slw: - set line width
stbg: - set text background color index
subp: - subdivide view surface into panels
svp: - set viewport (normalized device coordinates)
swin: - set window
tbox: - draw frame and write (DD) HH MM SS.S labelling
text: - write text (horizontal, left-justified)
updt: - update display
vect: - vector map of a 2D data array, with blanking
vsiz: - set viewport (inches)
vstd: - set standard (default) viewport
wedg: - annotate an image plot with a wedge
wnad: - set window and adjust viewport to same aspect ratio

Example
This example illustrates the pattern one can use to support both interactive, GUI-oriented plotting and non-interactive, batch plotting.

# In this tool, the pgplot device is either a widget or a file,
# depending on whether the psfile argument is set.  If it is, we use
# pgplotps() to construct our pgplot tool; otherwise, we use the 
# pgplotwidget() constructor.  All plot commands are collected in the
# tool function, drawplot().  This works because, in terms of its
# interface, a pgplotwidget is a pgplotmanager.
#
pipelineplotter := function(psfile=unset) {
    public := [=];
    private := [file=psfile, topframe=F];

    if (is_unset(psfile)) {

        # no filename given, so create a pgplot GUI
	include 'widgetset.g';
	include 'pgplotwidget.g';
	private.topframe := dws.frame();

        private.pgp := pgplotwidget(private.topframe);

	# do further setup of GUI as necessary; e.g. setting callbacks

    }
    else {

        # record plot to a file
	include 'pgplotwidget.g';

	private.pgp := pgplotps(psfile);
    }

    # This function draws the plot to the pgplot device (be it a GUI
    # or a file.
    public.drawplot := function() {

        # PGPLOT commands go here.  Only those functions supported by
        # the pgplotmanager tool should be used via the tool held in the
	# private.pgp variable.  GUI related commands should go elsewhere.

	private.pgp.box('BC', 0, 0, 'BC', 0, 0);
	# etc....
    }

    # Other functions...

}

Next: pgplotmanager - Constructor Up: plotter - Module Previous: plotter - Module Contents Index

	Package	display
	Module	plotter

pgplotmanager - Tool