pgplotmanager.setagent

set the PGPLOT agent to be managed by this tool

Synopsis
setagent(pgpagent, close)

Description
This function makes it possible to switch in a new pgplot client for management by this tool. This is most useful after constructing pgplotmanager tool that isn't attached to an output device.

Care should be taken by the caller of this function, especially when the new 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 function still has a reference. Note in the example below how the caller takes care to destroy its reference to the agent after passing it to this function.

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.)
close	if true, the previous agent will be explicitly closed before its replacement is set. Set this to F if agent is attached to a GUI being shared with another pgplotmanager
	Allowed:	boolean
	Default:	T

Returns
T or fail if pgpagent is not an agent

Example
In this example, 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

In the next example, the pgplot agent is passed to another pgplotmanager tool. This is, admittedly, a somewhat contrived example.

# this will record commands for drawing a special plot
drawplot := pgplotmanager(record=T);
drawplot.env(0, 2 * pi, -1, 1, 0, 0);

# this will display the plot to the user
f := frame();
pgpm := pgplotmanager(pgplot(f));

# draw plot to widget
pgpa := pgpm.getagent();
drawplot.setagent(pgpa);
drawplot.refresh();
drawplot.setagent(close=F);  # reset agent to null, but don't close widget
pgpa := F;                   # Now pgpm has the only reference to the agent

# now continue plotting
pgpm.arro(1, -1, 5, -0.5)

Next: pgplotmanager.resetplotnumber - Function Up: pgplotmanager - Tool Previous: pgplotmanager.getagent - Function Contents Index

	Package	display
	Module	plotter
	Tool	pgplotmanager

pgplotmanager.setagent - Function