libploticus

libploticus is built using Makefile_api. 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_api. 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.

Program example

   main()
   {
   int stat;
   stat = ploticus_init( "png", "bargraph.png" );
   stat += ploticus_arg( "-scale", "0.8" );
   stat += ploticus_begin();
   if( stat != 0 ) { 
  	printf( "error in pl setup\n" ); 
       exit(1); 
       }
   ploticus_execline( "#proc annotate" );
   ploticus_execline( "  location: 2 2" );
   ploticus_execline( "  text: hello" );
   ploticus_execline( "  world" );
   ploticus_execline( "" );
   ploticus_end();
   }

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 eps. (Not all devices may be available, depending on the build.) outfilename is the pathname of the file where the result will be written. This function must be called first. Example:

   stat = ploticus_init( "png", "bargraph.png" );
   if( stat != 0 ) error

ploticus_arg( name, value )

Get a pl command line argument. name specifies the argument name and value an argument value. If there is no argument value, value may 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( )

Perform further initializations that take into account command line arguments. This must be used after any calls to ploticus_arg() and before any other ploticus functions.
Example: ploticus_begin();

ploticus_execline( char *line )

Interpret one "raw" ploticus script line. ploticus_execline() is generally called multiple times, and allows ploticus scripts to be generated programatically. "Raw" ploticus script lines may contain no @variable references, and the only directives supported are #proc, #procdef, #endproc, #clone and #saveas. Lines may or may not be newline terminated. Intermingling with ploticus_execscript() is not allowed. Example:

    ploticus_execline( "#proc annotate" );
    ploticus_execline( "  location: 2 2" );
    ploticus_execline( "  text: hello" );
    ploticus_execline( "  world" );
    ploticus_execline( "" );

ploticus_execscript( char *scriptfile, int prefabflag )

Interpret an entire ploticus script file. scriptfile is the name of the script file. prefabflag is 1, then scriptfile should be a ploticus prefab name. If prefabflag is 0, then scriptfile should be a pathname. Intermingling with ploticus_execline() is not allowed.
Example: stat = ploticus_execscript( "vbars", 1 );
Example: stat = ploticus_execscript( "/home/steve/plfiles/myscript.pl", 0 );

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).

ploticus_end()

Finish up the graphic result (usually this involves writing it out to a file), and terminate ploticus. This must be the last ploticus function called.