pgplotmanager - Constructor

Manage a previously created pgplot agent

Synopsis
pgplotmanager(pgpagent, interactive, record, playlist, ownplaylist, askfunction, widgetset)

Description

This constructor creates a pgplotmanager tool that will manage an arbitrary pgplot agent. This agent should have already been created with either a graphical widget or hardcopy device (see examples below). The agent can be created either via the widgetserver tool or directly witht the Glish pgplot() global function (see the PGPLOT section of the Glish Manual for details). Note that for many applications, this constructor is not needed: the pgplotps constructor can be used to attach to a file, and the pgplotwidget tool can be used to attach to a widget.

It is possible to create a pgplotmanager that is attached to neither a widget nor real file device by passing F to this constructor's pgpagent parameter. (This actually causes the output device to be set to the /dev/null file.) This allows one to use the pgplotmanager to record commands into its internal display-list without sending them to any real output device; these commands could be played back to a real device later. This could be done by setting the agent later with the setagent() function. Alternatively, the display list could be save to a file via the plotfile() function and then reloaded later (e.g. in another session) into a new pgplotmanager or pgplotter tool.

Care should be taken by the caller of this constructor when the agent is attached to a graphical widget. Widgets are destroyed only when all references to its agent are eliminated. When this tool's done() function is called, the tool will eliminate its internal reference; however, the widget will not disappear if the caller of this constructor still has a reference. See examples below.

Arguments

pgpagent	the pgpagent to manage. A pgpagent is usually constructed either from a widgetset tool's pgplot() function or directly through glish with the pgplot() global function. Alternatively, it can ``borrowed'' from another pgplotmanager via its getagent() function (but see caveat described above).
	Allowed:	pgplot agent or F
	Default:	F - causes the device to be set to a null file (/dev/null; see explanation above.)
interactive	sets controls whether interactive prompting of the user should be allowed. This is usually set to F if the PGPLOT agent is attached to a file.
	Allowed:	boolean; T - the pgplot ask() function is enabled, allowing the user to turn prompting on and off; F - prompting is not allowed and the ask() function has no effect.
	Default:	T
record	sets whether recording is initially turned on
	Default:	F
playlist	a displaylist tool to use to store plot commands. This allows pre-record commands to be attached to this pgplotmanager.
	Default:	F - a new display list will be created internally
ownplaylist	if true, the displaylist tool passed by the playlist parameter will be shut down when this tool is shut down. This is only used when the playlist parameter is used.
	Allowed:	boolean
	Default:	T
askfunction	the function to call when prompting the user to advance to the next plot. This can either one of the global functions pgplotaskviaprompt() or pgplotaskviagui(), or it can be a user provided function. The interactive parameter must be set to T for this function to get used.
	Allowed:	function
	Default:	F - pgplotaskviaprompt() will be used by default
widgetset	the widgetserver tool to use when creating an internal displaylist. This is used only when a displaylist is not provided via the playlist parameter.
	Allowed:	widgetserver tool
	Default:	dws - the default widgetserver tool

Returns
pgplotmanager tool or fail

Example
In this example, note how the reference to the pgplot agent, in this case, attached to a GUI device, is handled.

f := frame();
pgpa := pgplot(f);
pgpm := pgplotmanager(pgpa);
pgpa := F;          # Now pgpm has the only reference to the agent

Here, the pgplotmanager is attached to a PostScript file. Note that the pgplotps constructor is the simpler way to do this.

pgpa := pgplot('plot.ps/PS');
pgpm := pgplotmanager(pgpa, interactive=F);
pgpa := F;

Here, the pgplot agent is set after the construction of the pgplotmanager tool.

pgpm := pgplotmanager(record=T);

# do some plotting
pgpm.env(0, 2 * pi, -1, 1, 0, 0);

# now attach an agent and replay the plotting done thus far
f := frame();
pgpa := pgplot(f);
pgpm.setagent(pgpa);
pgpm.refresh();
pgpa := F;          # Now pgpm has the only reference to the agent
pgpm.done();        # widget should disappear

Next: pgplotps - Constructor Up: pgplotmanager - Tool Previous: pgplotmanager - Tool Contents Index

	Package	display
	Module	plotter
	Tool	pgplotmanager