- 1 - Formatted: April 23, 2024
libploticus_API(PL) libploticus_API(PL)
11-MAR-2009 PL ploticus.sourceforge.net
This simple C language API has all of the funcionality of the pl(1)
executable and is similarly covered by the General Public License.
Build libploticus by making certain settings in the src/Makefile.
Applications linking to libploticus may need additional libraries such
as zlib, but this depends on exactly how libploticus was built (see
the Makefile). The externally visible symbols in libploticus begin
with these prefixes: ploticus, PL, TDH, DT, and GL. No header file is
required. All functions return 0 when successful, or a non-zero error
code. As of version 2.11 multiple sequential plot "jobs" can be
performed by a single OS process. Each plot job should begin with a
ploticus_init() call and terminate with a ploticus_end() call. No
attempt has been made to write libploticus as thread-safe. As of
version 2.40 script lines can no longer be passed as string constants.
Examples
Here's a simple example (it may be found in ./pltestsuite/api_examp.c)
main()
{
int stat;
char sln[80];
stat = ploticus_init( "png", "hello.png" );
stat += ploticus_arg( "-scale", "0.8" );
if( stat != 0 ) {
printf( "error in pl setup\n" );
exit(1);
}
strcpy( sln, "#proc annotate" ); ploticus_execline( sln );
strcpy( sln, "location: 2 2" ); ploticus_execline( sln );
strcpy( sln, "text: hello" ); ploticus_execline( sln );
strcpy( sln, " world." ); ploticus_execline( sln );
ploticus_end();
}
Multi-job example
Another included example, which invokes a series of 25+ plot jobs, is
in ./src/api_test.c To build:
make clean
make -f Makefile_api
make api_test -f Makefile_api
Then, go to the pltestsuite directory and type: ../src/api_test
libploticus API
ploticus_init( char *device, char *outfilename )
- 1 - Formatted: April 23, 2024
libploticus_API(PL) libploticus_API(PL)
11-MAR-2009 PL ploticus.sourceforge.net
Initialize, read your ploticus config file if any, and set the
output device to one of png, gif, x11, svg, jpeg, eps, or swf.
(Not all devices may be available, depending on the build.)
outfilename is the pathname of the file where the result will be
written. Example:
stat = ploticus_init( "png", "bargraph.png" );
if( stat != 0 ) error
ploticus_arg( name, value )
Specify a pl command line argument. name specifies the argument
name and value an argument value. If there is no argument value,
value should be passed as "". All arguments are supported except
-f, -prefab, and -ver. If needed, this function should be called
after ploticus_init() but before any other ploticus function. It
may be called as many times as necessary. Example:
stat = ploticus_arg( "-debug", "" );
stat += ploticus_arg( "-diagfile", "stdout" );
stat += ploticus_arg( "-scale", "0.8" );
if( stat != 0 ) error
ploticus_begin( )
This function is no longer necessary. Old code that uses it will
still be OK.
ploticus_execline( char *line )
Interpret one "raw" ploticus script line. Typically called
multiple times, allowing ploticus scripts to be generated
programatically. Script lines can contain only these directives:
#proc, #procdef,
#endproc, #clone and #saveas. You can't use set, if/else,
loops, or other flow-of-control directives (but these types of
things can be handled by your host application). Further, these
script lines do not undergo a variable-evaluation pass, so
variables cannot be referenced, and select statements (etc.) that
reference data field names should use one at sign (@) instead of
two (@@). If your program needs to access a variable that has
been set by the ploticus engine, use ploticus_getvar(), described
below. The script line may include a trailing newline or not.
An alternative is to use ploticus_execscript() (described below)
to execute an entire script file. You can't use both
ploticus_execline() and ploticus_execscript() in the same
application.
- 2 - Formatted: April 23, 2024
libploticus_API(PL) libploticus_API(PL)
11-MAR-2009 PL ploticus.sourceforge.net
Caution As of ploticus version 2.40 string constants cannot be
passed in this function. See the example in the page intro
above.
ploticus_execscript( char *scriptfile, int prefabflag )
Interpret an entire ploticus script file or prefab. scriptfile
is the name of the ploticus script file. There are no syntax
limitations as with ploticus_execline(). prefabflag is 1, then
scriptfile is taken to be a ploticus prefab name such as vbars.
If prefabflag is 0, then scriptfile should be a pathname.
An alternative is to use ploticus_execline() (described above) to
execute program-generated "raw" script lines one at a time. You
can't use both ploticus_execscript() and ploticus_execline() in
the same application.
Example: stat = ploticus_execscript( "vbars", 1 );
Example: stat = ploticus_execscript(
"/home/steve/plfiles/myscript.pl", 0 );
ploticus_end()
Finish up the graphic result, write it to the output file, and
free up allocated memory.
These functions are also available:
ploticus_getvar( char *name, char *value )
Get the contents of ploticus variable name. Result is copied
into value.
Example: stat = ploticus_getvar( "XFINAL", xf );
ploticus_setvar( char *name, char *value )
Set ploticus variable name to value.
gdImagePtr PLGG_getimg( int *width, int *height )
Returns a pointer to the working GD image, for situations where
the host application wants to directly issue gd drawing calls.
The width and height of the working image (in pixels) are also
provided. Note that the result image is generally cropped based
on the extent of ploticus drawing actions, before being written
out. Only valid in applications built with GD, when ploticus was
initialized with one of the GD image devices (eg. png or jpeg).
- 3 - Formatted: April 23, 2024
