Provided by: libploticus0_2.42-4.2_amd64 
Name
Libploticus - C language API library for ploticus
Description
This simple C language API has all of the funcionality of the ploticus program and is
similarly covered by the General Public License.
libploticus is built using Makefile.
make clean
make FPIC=-fPIC libploticus-so
Applications linking to libploticus may need additional libraries such as zlib, but this
depends on exactly how libploticus was built. The specifics are noted in Makefile. The
externally visible symbols in libploticus begin with these prefixes: ploticus, PL, TDH,
DT, and GL.
The header file libploticus.h is required to avoid compiler warnings.
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 ploticus 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 )
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 programmatically. 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.
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).
11-MAR-2009 PLOTICUS ploticus.sourceforge.net libploticus(3)