9.3.1 The Plotter class

The C++ binding for libplot is provided by a class library named libplotter. This library implements a Plotter class of which all Plotters are instances. Actually, a Plotter would normally be an instance of an appropriate derived class, determined by the Plotter's output format. Derived classes include XPlotter, XDrawablePlotter, PNGPlotter, PNMPlotter, GIFPlotter, AIPlotter, PSPlotter, CGMPlotter, FigPlotter, PCLPlotter, HPGLPlotter, ReGISPlotter, TekPlotter, and MetaPlotter. The names should be self-explanatory. The operations that may be applied to any Plotter (e.g., the openpl operation, which begins a page of graphics) are implemented as public function members of the Plotter class.

At the time a Plotter is created, its input, output, and error streams must be specified, along with a PlotterParams object that optionally contains other Plotter parameters. (The input stream is ignored, since at present, all Plotters are write-only.) The streams may be specified either as iostreams or as FILE pointers. That is, the two constructors

       Plotter(istream& instream, ostream& outstream, ostream& errstream,
               PlotterParams &params);
       Plotter(FILE *infile, FILE *outfile, FILE *errfile,
               PlotterParams &params);

are provided for the base Plotter class, and similarly for each of its derived classes. So, for example, both

     PSPlotter plotter(cin, cout, cerr, params);

and

     PSPlotter plotter(stdin, stdout, stderr, params);

are possible declarations of a Postscript Plotter that writes to standard output. In the iostream case, an ostream with a null stream buffer may be specified as the output stream and/or the error stream, to request that no output take place. In the FILE pointer case, specifying a null FILE pointer would accomplish the same thing. Instances of the XPlotter and XDrawablePlotter classes always ignore the output stream argument, since they write graphics to an X Display rather than to a stream.

The PlotterParams class supports copying and assignment, but has only a single public function member, setplparam. The following is a formal description.

int PlotterParams::setplparam (const char *parameter, void *value);

Set the value of the Plotter parameter parameter to value. For most parameters, value should be a char *, i.e., a string. Unrecognized parameters are ignored. For a list of the recognized parameters and their meaning, see Plotter Parameters.

Like the plPlotterParams datatype and the function pl_setplparam of the C binding, the PlotterParams class and the PlotterParams::setplparam function of the C++ binding give the programmer fine control over the parameters of subsequently created Plotters. The parameter values used by any Plotter are constant over the lifetime of the Plotter, and are those that were specified when the Plotter was created. If at Plotter creation time a parameter has not been set in the specified PlotterParams object, its default value will be used, unless the parameter is string-valued and there is an environment variable of the same name, in which case the value of that environment variable will be used.

Once set in a PlotterParams object, a parameter may be unset by the programmer by invoking PlotterParams::setplparam with a value argument of NULL. This further increases flexibility.

There is an alternative (older) way of constructing a Plotter, which is deprecated but still supported. By using either of

       Plotter(istream& instream, ostream& outstream, ostream& errstream);
       Plotter(FILE *infile, FILE *outfile, FILE *errfile);

one may construct a Plotter without specifying a PlotterParams object. In this case the parameter values for the Plotter are copied from static storage. A parameter may be set in static storage by invoking a static member function of the Plotter class, Plotter::parampl, which has declaration

int PlotterParams::parampl (const char *parameter, void *value);

This alternative way of creating a Plotter is not thread-safe, which is why it is deprecated.